{ "openapi": "3.0.0", "info": { "version": "3.0.0", "title": "Didit Verification API", "description": "身份证件验证 API。使用 x-api-key 请求头进行身份验证。" }, "servers": [ { "url": "https://verification.didit.me" } ], "tags": [], "paths": { "/system/healthcheck": { "get": { "summary": "服务健康检查（公开，无需认证）", "description": "公开未认证存活探针。当服务、数据库、缓存和消息代理处于健康状态时，返回包含 `{status: \"ok\", timestamp}` 的 `HTTP 200`。", "operationId": "get_system_healthcheck", "x-didit-sdk": { "resource": "system", "method": "healthcheck", "auth": "public", "server": false }, "tags": [ "System" ], "security": [ {} ], "parameters": [], "responses": { "200": { "description": "服务正常并接受请求。响应体始终为 `{\"status\": \"ok\", \"timestamp\": \"\"}`。", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "timestamp" ], "properties": { "status": { "type": "string", "enum": [ "ok" ], "description": "活体标记。在 200 响应中始终为字面字符串 `\"ok\"`。", "example": "ok" }, "timestamp": { "type": "string", "format": "date-time", "description": "评估健康检查时的服务器时间，采用毫秒精度的 ISO 8601 格式，带 `Z`（UTC）后缀。", "example": "2026-04-21T16:42:50.445Z" } } }, "examples": { "Healthy": { "summary": "服务正常运行", "value": { "status": "ok", "timestamp": "2026-04-21T16:42:50.445Z" } } } } } }, "503": { "description": "服务不健康：配置的某个健康检查插件（数据库、缓存、消息代理）运行失败。响应体特意保持极简；HTTP 状态码是承载关键信息的信号。请使用指数退避重试。" }, "5XX": { "description": "验证服务降级或不可用。将任何非 2xx 响应视为“不健康”，并采用指数退避算法进行重试。" } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -i https://verification.didit.me/system/healthcheck" }, { "lang": "Python", "label": "Python (requests)", "source": "import requests\n\nresp = requests.get(\"https://verification.didit.me/system/healthcheck\", timeout=5)\nresp.raise_for_status()\nprint(resp.json()) # {'status': 'ok', 'timestamp': '2026-04-21T16:42:50.445Z'}" }, { "lang": "JavaScript", "label": "Node.js (fetch)", "source": "const res = await fetch(\"https://verification.didit.me/system/healthcheck\");\nif (!res.ok) throw new Error(`Didit unhealthy: ${res.status}`);\nconst body = await res.json();\nconsole.log(body); // { status: 'ok', timestamp: '2026-04-21T16:42:50.445Z' }" } ] } }, "/v3/email/risk/": { "post": { "summary": "对邮箱地址进行风险评分", "description": "返回送达率、一次性地址、数据泄露、跨会话匹配以及标准化的风险情报信号，而无需发送 OTP。该 endpoint 会创建一个 API 会话，并将其 ID 作为 `request_id` 返回。\n\n**决策。** 顶层 `status` 与 `email.status` 保持一致。通常为 `Approved`；风险评估可能会产生 `In Review` 或 `Declined`。\n\n**兼容性别名。** 生产环境响应将标准化的情报对象同时作为 `email.email_intelligence` 和 `email.enrichment` 暴露。两者的值完全相同。新的集成可以直接读取 `email.enrichment`。当未返回可用的情报数据时，这两个键均不存在。\n\n**计费。** 生产环境调用按 Email Risk API 定价计费。一旦查询开始，该请求即计费，即使某些尽力而为的字段不可用也是如此。\n\n**沙盒。** 沙盒密钥会验证请求并返回确定性的已通过数据，不会发送电子邮件、消耗额度、创建会话或向 Networks 提供数据。\n\n**认证。** 在 `x-api-key` 中发送您应用的 API 密钥。缺失或无效的凭据将返回 `403`，该 API 从不返回 `401`。\n\n**速率限制。** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 之间共享每分钟 300 次请求的写入配额（交易创建和事件摄入拥有单独的 600 次配额）。\n\n**社交足迹。** 将 `enable_social` 设置为 `true` 以添加 `email_social` 块：该地址注册过的在线平台、各类别数量以及任何可用的个人资料详情。`profiles_registered: 0` 表示已检查这些平台且未在其中找到该地址，这是有效且计费的响应。如果未请求该附加功能或无法完成检查，则该块不存在，并且在那种情况下不计费。计费会在该 endpoint 自身价格的基础上，按每次请求增加一个 `email_social` 单位。", "operationId": "post_v3email_risk", "x-didit-sdk": { "resource": "email", "method": "assess_risk", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/email/risk/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"alice@example.com\",\n \"country_code\": \"US\",\n \"vendor_data\": \"lead-123\",\n \"metadata\": {\"source\": \"signup_prescreen\"}\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.email.assess_risk(\n email=\"alice@example.com\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.email.assessRisk({\n email: \"alice@example.com\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.AssessRisk(ctx, didit.EmailRiskRequest{\n\tEmail: \"alice@example.com\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EmailRiskRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.email().assessRisk(EmailRiskRequest.builder()\n .email(\"alice@example.com\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "email->assessRisk([\n 'email' => 'alice@example.com',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.email.assess_risk(email: \"alice@example.com\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Email.AssessRiskAsync(new EmailRiskRequest\n{\n Email = \"alice@example.com\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRiskRequest" }, "examples": { "Minimal": { "summary": "使用默认值对地址评分", "value": { "email": "alice@example.com" } }, "Full context": { "summary": "附带信号、国家/地区提示和关联 ID 的评分", "value": { "email": "alice@example.com", "country_code": "US", "signals": { "ip": "192.0.2.1", "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2", "device_platform": "web", "os_version": "14.4", "app_version": "1.2.34", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15" }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" } } } } } } }, "responses": { "200": { "description": "风险评估已完成。检查 `status` 获取决策；对于已完成的查询，HTTP 状态码始终为 `200`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailRiskResponse" }, "examples": { "Clean address": { "summary": "可送达且无数据泄露风险的地址", "value": { "request_id": "82397be9-5921-4970-a979-2d5b43e08b33", "status": "Approved", "email": { "status": "Approved", "email": "alice@example.com", "is_breached": false, "breaches": [], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "email_intelligence": { "score": 4.0, "deliverable": "high", "breach_risk_level": "Low", "breach_risk_index": 4, "is_recent_breach": false, "is_frequent_breached": false, "is_disposable": false, "is_free_domain": false, "is_breached": false, "no_of_breaches": 0, "reason_codes": [] }, "enrichment": { "score": 4.0, "deliverable": "high", "breach_risk_level": "Low", "breach_risk_index": 4, "is_recent_breach": false, "is_frequent_breached": false, "is_disposable": false, "is_free_domain": false, "is_breached": false, "no_of_breaches": 0, "reason_codes": [] } }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" }, "created_at": "2026-09-01T10:30:00.123456+00:00" } }, "Breached address": { "summary": "在已知数据泄露事件中发现该地址", "value": { "request_id": "d1e5c2a8-6f30-4c1a-8b2d-3e4f5a6b7c8d", "status": "In Review", "email": { "status": "In Review", "email": "bob@example.org", "is_breached": true, "breaches": [ { "name": "ExampleBreach2023", "domain": "example.org", "breach_date": "2023-06-01", "breach_emails_count": 1200000, "description": "A data breach affecting example.org accounts.", "logo_path": "https://logos.example.org/example.png", "data_classes": [ "email_addresses", "passwords" ], "is_verified": true } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "email_intelligence": { "score": 58.0, "deliverable": "high", "breach_risk_level": "High", "breach_risk_index": 72, "is_recent_breach": true, "is_frequent_breached": true, "is_disposable": false, "is_free_domain": true, "is_breached": true, "no_of_breaches": 4, "reason_codes": [ { "code": "IR-F784B630", "direction": "risk", "message": "Email's digital footprint diversity is Very Low", "impact_level": "low" } ] }, "enrichment": { "score": 58.0, "deliverable": "high", "breach_risk_level": "High", "breach_risk_index": 72, "is_recent_breach": true, "is_frequent_breached": true, "is_disposable": false, "is_free_domain": true, "is_breached": true, "no_of_breaches": 4, "reason_codes": [ { "code": "IR-F784B630", "direction": "risk", "message": "Email's digital footprint diversity is Very Low", "impact_level": "low" } ] } }, "vendor_data": "lead-125", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } } } } } }, "400": { "$ref": "#/components/responses/EmailRiskValidationError" }, "403": { "$ref": "#/components/responses/RiskPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/ip/risk/": { "post": { "summary": "对 IP 地址进行风险评分", "description": "返回所提供 IP 地址的地理位置、网络所有权、VPN/Tor 和数据中心标记、威胁数据以及 `country_mismatch`。该 endpoint 会创建一个 API 会话，并将其 ID 作为 `request_id` 返回。\n\n**决策。** 当解析出的国家/地区与 `claimed_country` 冲突，或者地址与 VPN、Tor 或数据中心基础设施关联时，`status` 为 `In Review`。否则为 `Approved`。\n\n**尽力而为。** IP 数据增强是尽力而为的。如果没有数据增强来源返回可用数据，该 endpoint 会返回一个已通过的响应，其中 `ip.ip_address: null`、`ip.country_mismatch: null`，以及一个空的 `ip.threat` 对象。\n\n**计费。** 生产环境调用按 IP Risk API 定价计费。一旦查询开始，该请求即计费。\n\n**沙盒。** 沙盒密钥会验证请求并返回确定性的已通过数据，不会消耗额度、创建会话或向 Networks 提供数据。\n\n**认证。** 在 `x-api-key` 中发送您的应用的 API 密钥。缺失或无效的凭据将返回 `403`，该 API 从不返回 `401`。\n\n**速率限制。** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 之间共享每分钟 300 次请求的写入配额（交易创建和事件摄入拥有单独的 600 次配额）。", "operationId": "post_v3ip_risk", "x-didit-sdk": { "resource": "ip", "method": "assess_risk", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/ip/risk/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"ip_address\": \"8.8.8.8\",\n \"claimed_country\": \"ESP\",\n \"user_agent\": \"Mozilla/5.0\",\n \"vendor_data\": \"lead-123\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.ip.assess_risk(\n ip_address=\"8.8.8.8\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.ip.assessRisk({\n ip_address: \"8.8.8.8\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IP.AssessRisk(ctx, didit.IPRiskRequest{\n\tIPAddress: \"8.8.8.8\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.IPRiskRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.ip().assessRisk(IPRiskRequest.builder()\n .ipAddress(\"8.8.8.8\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "ip->assessRisk([\n 'ip_address' => '8.8.8.8',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.ip.assess_risk(ip_address: \"8.8.8.8\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Ip.AssessRiskAsync(new IPRiskRequest\n{\n IpAddress = \"8.8.8.8\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IPRiskRequest" }, "examples": { "Minimal": { "summary": "使用默认值对地址评分", "value": { "ip_address": "8.8.8.8" } }, "With claimed country": { "summary": "使用声明的国家/地区进行不匹配检测评分", "value": { "ip_address": "8.8.8.8", "claimed_country": "ESP", "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.4 Safari/605.1.15", "vendor_data": "lead-123" } } } } } }, "responses": { "200": { "description": "风险评估已完成。检查 `status` 获取决策；对于已完成的查询，HTTP 状态码始终为 `200`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IPRiskResponse" }, "examples": { "Clean residential IP": { "summary": "居住地址，声明的国家/地区匹配", "value": { "request_id": "9a96ed2a-721e-4b86-8cbf-d61eda529279", "status": "Approved", "ip": { "status": "Approved", "ip_address": "192.0.2.10", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Madrid", "ip_city": "Madrid", "latitude": 40.4168, "longitude": -3.7038, "isp": "Example Telecom", "organization": "Example Telecom SA", "is_vpn_or_tor": false, "is_data_center": false, "time_zone": "Europe/Madrid", "time_zone_offset": "+0200", "asn_number": 3352, "asn_organization": "EXAMPLE-TELECOM", "connection_type": "broadband", "carrier": "Example Telecom", "proxy_type": null, "claimed_country": "ESP", "country_mismatch": false, "threat": {} }, "vendor_data": "lead-123", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } }, "Datacenter mismatch": { "summary": "数据中心地址与声称的国家/地区冲突", "value": { "request_id": "5b1d4e9a-3c7b-4f8e-9a2d-1b0c9d8e7f6a", "status": "In Review", "ip": { "status": "In Review", "ip_address": "8.8.8.8", "ip_country": "United States", "ip_country_code": "US", "ip_state": "California", "ip_city": "Mountain View", "latitude": 37.386, "longitude": -122.0838, "isp": "Google", "organization": "Google LLC", "is_vpn_or_tor": true, "is_data_center": true, "time_zone": "America/Los_Angeles", "time_zone_offset": "-0700", "asn_number": 15169, "asn_organization": "GOOGLE, US", "connection_type": "hosting", "carrier": null, "proxy_type": "VPN", "claimed_country": "ESP", "country_mismatch": true, "threat": { "is_proxy": true, "is_data_center": true, "is_tor": false } }, "vendor_data": "lead-126", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } } } } } }, "400": { "$ref": "#/components/responses/IPRiskValidationError" }, "403": { "$ref": "#/components/responses/RiskPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/phone/risk/": { "post": { "summary": "对电话号码进行风险评分", "description": "解析电话号码，并在不发送 OTP 的情况下返回运营商、线路类型、携号转网、一次性号码、跨会话匹配以及归一化风险情报信号。该 endpoint 会创建一个 API 会话，并将其 ID 作为 `request_id` 返回。\n\n**决策。** 顶层的 `status` 与 `phone.status` 保持一致。通常为 `Approved`；风险评估可能会产生 `In Review` 或 `Declined`。\n\n**兼容性别名。** 生产环境响应将归一化情报对象同时公开为 `phone.phone_intelligence` 和 `phone.enrichment`。两者值完全一致。新的集成可读取 `phone.enrichment`。若未返回可用的情报数据，则两个键均不存在。\n\n**计费。** 生产环境调用采用 Phone Risk API 定价。一旦开始查询，即使某些尽力而为的字段不可用，该请求也将被计费。\n\n**沙盒。** 沙盒密钥会验证请求并返回确定性的已通过数据，而无需发送 OTP、消耗额度、创建会话或向 Networks 提供数据。\n\n**身份验证。** 在 `x-api-key` 中发送您应用的 API 密钥。缺少或无效的凭据将返回 `403`，该 API 从不返回 `401`。\n\n**速率限制。** 所有 POST/PATCH/DELETE endpoints 共享每个 API 密钥每分钟 300 次请求的写入配额（交易创建和事件摄入具有单独的 600 次配额）。\n\n**社交足迹。** 将 `enable_social` 设置为 `true` 可添加 `phone_social` 区块：该号码注册过的在线平台、各分类计数以及任何可用的个人资料详情。`profiles_registered: 0` 表示已检查相关平台且未在其中任何一个发现该号码，这是一个有效且计费的回答。如果未请求该附加功能或检查无法完成，则不包含该区块，在此情况下亦不计费。计费时会在该 endpoint 自身价格的基础上，按每次请求增加一个 `phone_social` 计费单位。", "operationId": "post_v3phone_risk", "x-didit-sdk": { "resource": "phone", "method": "assess_risk", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/phone/risk/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"+14155552671\",\n \"country_code\": \"US\",\n \"vendor_data\": \"lead-123\",\n \"metadata\": {\"source\": \"signup_prescreen\"}\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.phone.assess_risk(\n phone_number=\"+14155552671\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.phone.assessRisk({\n phone_number: \"+14155552671\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.AssessRisk(ctx, didit.PhoneRiskRequest{\n\tPhoneNumber: \"+14155552671\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.PhoneRiskRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.phone().assessRisk(PhoneRiskRequest.builder()\n .phoneNumber(\"+14155552671\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "phone->assessRisk([\n 'phone_number' => '+14155552671',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.phone.assess_risk(phone_number: \"+14155552671\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Phone.AssessRiskAsync(new PhoneRiskRequest\n{\n PhoneNumber = \"+14155552671\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneRiskRequest" }, "examples": { "Minimal": { "summary": "使用默认值对号码评分", "value": { "phone_number": "+14155552671" } }, "Full context": { "summary": "附带信号、国家/地区提示和关联 ID 的评分", "value": { "phone_number": "+14155552671", "country_code": "US", "signals": { "ip": "192.0.2.1", "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2", "device_platform": "ios", "device_model": "iPhone17,2", "os_version": "18.0.1", "app_version": "1.2.34", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1" }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" } } } } } } }, "responses": { "200": { "description": "风险评估已完成。检查 `status` 获取决策；对于已完成的查询，HTTP 状态码始终为 `200`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneRiskResponse" }, "examples": { "Clean mobile number": { "summary": "经过清理且具备情报覆盖的移动电话号码", "value": { "request_id": "4fd09d2e-9bc9-4c4e-9c46-7f625ac0ab62", "status": "Approved", "phone": { "status": "Approved", "phone_number_prefix": "+1", "phone_number": "4155552671", "full_number": "+14155552671", "country_code": "US", "country_name": "United States", "carrier": { "name": "Example Mobile", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": null, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "phone_intelligence": { "score": 3.0, "phone_type_risk": "Low", "phone_trust_index": 97, "network_stability_index": 95, "is_disposable": false, "is_ported": false, "is_recently_ported": false, "carrier_type": "mobile", "reason_codes": [] }, "enrichment": { "score": 3.0, "phone_type_risk": "Low", "phone_trust_index": 97, "network_stability_index": 95, "is_disposable": false, "is_ported": false, "is_recently_ported": false, "carrier_type": "mobile", "reason_codes": [] } }, "vendor_data": "lead-123", "metadata": { "source": "signup_prescreen" }, "created_at": "2026-09-01T10:30:00.123456+00:00" } }, "Number in review": { "summary": "标记待审核的一次性或虚拟号码", "value": { "request_id": "8c22e1f0-4b3d-4a3a-9d1e-2f6b7c8d9e0f", "status": "In Review", "phone": { "status": "In Review", "phone_number_prefix": "+44", "phone_number": "7700900123", "full_number": "+447700900123", "country_code": "GB", "country_name": "United Kingdom", "carrier": { "name": "Example VoIP", "type": "voip" }, "is_disposable": true, "is_virtual": true, "verification_method": null, "verification_attempts": 0, "verified_at": null, "warnings": [], "lifecycle": [], "matches": [], "phone_intelligence": { "score": 72.0, "phone_type_risk": "High", "phone_trust_index": 28, "network_stability_index": 40, "is_disposable": true, "is_ported": true, "is_recently_ported": true, "carrier_type": "voip", "reason_codes": [ { "code": "IR-5AC67A32", "direction": "risk", "message": "Phone type identified as non-mobile", "impact_level": "medium" } ] }, "enrichment": { "score": 72.0, "phone_type_risk": "High", "phone_trust_index": 28, "network_stability_index": 40, "is_disposable": true, "is_ported": true, "is_recently_ported": true, "carrier_type": "voip", "reason_codes": [ { "code": "IR-5AC67A32", "direction": "risk", "message": "Phone type identified as non-mobile", "impact_level": "medium" } ] } }, "vendor_data": "lead-124", "metadata": null, "created_at": "2026-09-01T10:30:00.123456+00:00" } } } } } }, "400": { "$ref": "#/components/responses/PhoneRiskValidationError" }, "403": { "$ref": "#/components/responses/RiskPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/": { "post": { "summary": "创建验证会话", "description": "创建用户验证（KYC）或企业验证（KYB）会话，并获取托管验证 `url` 以及 `session_token`，以便为您的终端用户重定向或嵌入。`workflow_id` 用于选择运行哪些验证步骤以及该会话是 KYC 还是 KYB。\n\n每当需要验证用户或企业时，请从您的后端调用此接口（切勿在浏览器中调用 — API 密钥属于机密）：例如在注册时、执行敏感操作前或需要重新验证时。前置条件：已发布的工作流（在控制台 [Workflows](https://docs.didit.me/zh/console/workflows) 页面中创建）以及具有可用额度的应用 API 密钥。沙盒应用会跳过额度检查。\n\n**幂等性：**当提供了 `vendor_data` 且该工作流的**当前最新已发布版本**上已存在具有相同 `vendor_data` 的未完成会话（`Not Started`、`In Progress`、`Resubmitted` 或 `Awaiting User`）（并且该会话已具有托管验证 URL）时，将返回现有会话（状态码仍为 `201`）而不是创建重复会话 — 其 `callback` 和 `metadata` 会更新为新提供的值。在旧版本工作流（此后已重新发布）上创建的未完成会话**不会**被复用；而是会创建一个固定到最新已发布版本的新会话。处于 `Approved`、`Declined`、`In Review`、`Expired`、`Abandoned` 或 `Kyc Expired` 状态的会话绝不会被复用。\n\n**副作用：**生成并存储托管验证 URL；如果 `contact_details.send_notification_emails` 为 `true` 且提供了邮箱，则会发送验证邀请邮件。会话将在工作流配置的会话过期时间后过期。对于 KYB 工作流，`contact_details.phone` 和 `expected_details` 将被忽略。", "operationId": "post_v3_session_create", "x-didit-sdk": { "resource": "sessions", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "201": { "description": "会话已创建（如果工作流最新发布的版本上已存在具有相同 `vendor_data` 的未完成会话，则直接返回）。响应为序列化的会话，包括用于将用户重定向至托管验证页面的 `url`。", "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "session_number", "session_token", "url", "vendor_data", "metadata", "status", "workflow_id", "workflow_version", "callback" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "验证会话的唯一标识符。调用 `GET /v3/session/{sessionId}/decision/` 时使用此 ID。", "example": "11111111-2222-3333-4444-555555555555" }, "session_number": { "type": "integer", "description": "在您的应用内分配给该会话的便于人类阅读的序号。便于客服支持和在仪表板中使用。", "example": 43762 }, "session_token": { "type": "string", "description": "12 个字符的 URL 安全 token，用于授权终端用户通过 `url` 访问托管验证流程。在会话过期前一直有效。请将其视为机密信息 — 任何持有该 token 的人都可以打开此会话的验证流程。", "example": "3FaJ9wLqX2Mz" }, "url": { "type": "string", "format": "uri", "description": "用于重定向终端用户的托管验证 URL。该 URL 内嵌了 `session_token`，若已配置，还会使用您的白标域名。当请求包含 `language` 时，URL 会包含语言路径段：`https://verify.didit.me/{language}/session/{session_token}`（例如 `/es/session/...`）；若未提供 `language`，则省略该路径段。", "example": "https://verify.didit.me/session/3FaJ9wLqX2Mz" }, "vendor_data": { "type": "string", "nullable": true, "description": "您在请求中传递的标识符，用于将该会话链接到您自身系统中的用户或企业。逐字回传。未提供时为 null。", "example": "user-123" }, "metadata": { "description": "在创建会话时随其一起存储的任意 JSON payload。原样回显：无论您发送的是何种 JSON 值（对象、字符串、数字、数组），都将按原样返回，但建议使用 JSON 对象。不对终端用户显示。始终在响应中提供；创建时未提供则为 `null`。", "example": { "user_type": "premium", "account_id": "ABC123" } }, "tags": { "type": "array", "items": { "type": "string" }, "description": "会话中的标签，按名称列出。", "example": [ "VIP", "ONBOARDING Q4" ] }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "会话的当前状态。新创建的会话返回 `Not Started`。如果工作流最新发布的版本上已存在具有相同 `vendor_data` 的未完成会话，则返回的状态反映该现有会话。", "example": "Not Started" }, "callback": { "type": "string", "format": "uri", "nullable": true, "description": "用户完成流程后被重定向到的最终重定向 URL。Didit 会在此 URL 后追加 `?verificationSessionId={session_id}&status={status}`。若请求中未提供，则回退到工作流配置的回调 URL；若两者均未设置则为 `null`。当应用配置了允许的域名且此 URL 是域名列表之外的 Web URL 时（例如在更改列表前设置的工作流默认值），托管流程不会将用户重定向至该 URL。", "example": "https://example.com/verification/callback" }, "workflow_id": { "type": "string", "format": "uuid", "description": "此会话运行所在工作流的稳定标识符。始终为工作流的稳定分组标识符。即使您在请求中引用了特定工作流版本的 UUID（向后兼容的查找方式），响应中也会包含稳定的 `workflow_id`。使用它可将会话与您在控制台中配置的工作流进行关联。", "example": "11111111-2222-3333-4444-555555555555" }, "workflow_version": { "type": "integer", "description": "会话在创建时所绑定的已发布工作流版本号。在创建会话时，Didit 会将 `workflow_id` 解析为该工作流最新发布的版本，即使之后重新发布工作流，该会话也会继续运行该版本。", "example": 3 } } }, "examples": { "KYC session": { "summary": "KYC 会话已创建", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "session_number": 43762, "session_token": "3FaJ9wLqX2Mz", "url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz", "vendor_data": "user-123", "metadata": { "user_type": "premium", "account_id": "ABC123" }, "status": "Not Started", "workflow_id": "11111111-2222-3333-4444-555555555555", "workflow_version": 3, "callback": "https://example.com/verification/callback" } }, "KYB session": { "summary": "KYB 会话已创建", "value": { "session_id": "22222222-3333-4444-5555-666666666666", "session_number": 43763, "session_token": "Yk7pQ2vN8aBc", "url": "https://verify.didit.me/en/session/Yk7pQ2vN8aBc", "vendor_data": "company-acme-001", "metadata": { "tier": "enterprise" }, "status": "Not Started", "workflow_id": "33333333-4444-5555-6666-777777777777", "workflow_version": 1, "callback": "https://example.com/kyb/callback" } } } } } }, "400": { "description": "错误请求：payload 未通过验证（缺失或未知的 `workflow_id`、无效的 `language`、已列入黑名单的 `vendor_data`、格式错误的 `portrait_image`、缺少 `country`/`poa_country` 的 `address`、无效的 `sandbox_scenario`，或者工作流的电子签名步骤拒绝的 `sign` 证件、字段或值，例如 `signature_document_not_supported`、`signature_document_conversion_failed`、`field_anchor_not_found` 或 `field_value_missing` 等），或者您的组织没有足够的额度来启动会话。\n\n响应体是一个以违规字段名为键的对象（对于非字段错误，键为 `detail`）。输入验证失败（例如缺少必填字段、无效语言、人像图片过大）对应的值为**字符串数组**；创建会话期间检测到的失败（未知的 `workflow_id`、已列入黑名单的 `vendor_data`、人脸比对工作流无可用的参考人脸）对应的值为**纯字符串**。请处理这两种格式。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "detail": { "type": "string", "description": "非字段错误的便于人类阅读的错误消息（例如额度不足）。字段级失败则改用字段名作为键，对应的值为字符串或字符串数组。", "example": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } }, "examples": { "Missing workflow_id": { "summary": "遗漏了必填字段（字符串数组格式）", "value": { "workflow_id": [ "This field is required." ] } }, "Invalid workflow_id": { "summary": "未知的 workflow_id（纯字符串格式）", "value": { "workflow_id": "Invalid workflow_id." } }, "Insufficient credits": { "summary": "组织额度已用尽", "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } }, "Blocklisted vendor_data": { "summary": "vendor_data 已被列入黑名单", "value": { "vendor_data": "This user or business has been blocked and cannot create new verification sessions." } }, "Portrait image too large": { "summary": "portrait_image 未通过大小验证", "value": { "portrait_image": [ "Image size exceeds 2MB." ] } }, "No stored face for vendor_data": { "summary": "不带 portrait_image 且没有为 vendor_data 用户存储人脸的人脸比对工作流", "value": { "portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first." } }, "Portrait image required without vendor_data": { "summary": "不带 portrait_image 且不带 vendor_data 的人脸比对工作流", "value": { "portrait_image": "A portrait image is required to perform face match for this workflow. Send a portrait_image, or provide the vendor_data of a user with a previously stored face image to reuse it." } } } } } }, "403": { "description": "身份验证或授权失败。错误、已撤销或已过期的密钥将返回 `401`。当缺少 `x-api-key` 请求头，或者 API 密钥有效但客户端无权在此应用中创建会话（例如该 API 密钥属于其他组织）时，该 endpoint 将返回 `403`。这些失败均共享响应体 `{\"detail\": \"You do not have permission to perform this action.\"}`。请检查 `x-api-key` 请求头是否存在且属于目标应用，如有需要，可通过 [Auth API](/zh/auth-api/get-credentials) 重新获取应用 API 密钥，然后重试。\n\n**已删除的应用：**在应用被删除后的几分钟内，使用其 API 密钥发出的请求可能会返回 `{\"detail\": \"This application was deleted.\", \"code\": \"application_deleted\"}`。请勿重试：该应用及其 API 密钥已不复存在。几分钟后，该密钥将像其他无效密钥一样被拒绝。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." }, "code": { "type": "string", "description": "机器可读的原因，仅在某些失败情况下出现。`application_deleted`：API 密钥属于已被删除的应用。", "example": "application_deleted" } }, "required": [ "detail" ] }, "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头或 API 密钥无效", "value": { "detail": "You do not have permission to perform this action." } }, "No permission": { "summary": "客户端无法创建会话", "value": { "detail": "You do not have permission to perform this action." } }, "Application deleted": { "summary": "已删除应用的 API 密钥", "value": { "detail": "This application was deleted.", "code": "application_deleted" } } } } } }, "429": { "description": "超出速率限制：同一 API 密钥 / IP 在 60 秒时间窗口内发起的会话创建请求超过 600 次。请检查 `Retry-After` 并在重试前进行退避等待。\n\n**注意：**源代码中还在 `PAID_SESSION_RATE_LIMIT=600` 之外定义了 10 次调用/分钟的 `FREE_SESSION_RATE_LIMIT`（`sessions/serializers/session.py`），但该免费额度上限**不适用于此 V3 endpoint**：无论何种套餐，速率限制中间件均执行 600 次/分钟的 `SESSION_CREATE_RATE_LIMIT`。600 次/分钟是您在此处可能触发的唯一限制。", "headers": { "Retry-After": { "description": "调用方在重试请求前必须等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 42 } }, "X-RateLimit-Limit": { "description": "当前 60 秒时间窗口内针对已触发限制所允许的最大请求数（创建会话为 600）。在沙盒配额变体中不存在。", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "对于已超出限制的速率限制，在当前窗口内仍允许的请求次数。在沙盒配额变体中不存在此项。", "schema": { "type": "integer", "minimum": 0, "example": 0 } }, "X-RateLimit-Reset": { "description": "当前速率限制窗口重置时的 UTC 纪元秒数。沙盒配额变体中不存在此项。", "schema": { "type": "integer", "minimum": 0, "example": 1747497600 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "超出速率限制的便于人类阅读的说明。使用此消息可区分触发了三项限制中的哪一项。", "example": "Session creation rate limit exceeded. You can make up to 600 requests per minute." } } }, "examples": { "Session-create limit": { "summary": "每分钟创建会话请求超过 600 次", "value": { "detail": "Session creation rate limit exceeded. You can make up to 600 requests per minute." } }, "Sandbox session quota": { "summary": "沙盒应用在 24 小时内超过 500 次会话", "value": { "detail": "Sandbox session quota exceeded (500 sessions per 24h). Wait for the window to reset. Expected available in 3600 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/session/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"workflow_id\": \"11111111-2222-3333-4444-555555555555\",\n \"vendor_data\": \"user-123\",\n \"callback\": \"https://example.com/verification/callback\",\n \"callback_method\": \"both\",\n \"metadata\": {\"user_type\": \"premium\", \"account_id\": \"ABC123\"},\n \"language\": \"en\",\n \"contact_details\": {\n \"email\": \"john.doe@example.com\",\n \"send_notification_emails\": true,\n \"email_lang\": \"en\",\n \"phone\": \"+14155552671\"\n },\n \"expected_details\": {\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"id_country\": \"USA\",\n \"expected_document_types\": [\"P\", \"ID\"]\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.create(\n workflow_id=\"11111111-2222-3333-4444-555555555555\",\n vendor_data=\"user-123\",\n callback=\"https://example.com/verification/callback\",\n callback_method=\"both\",\n metadata={\"user_type\": \"premium\", \"account_id\": \"ABC123\"},\n language=\"en\",\n contact_details={\n \"email\": \"john.doe@example.com\",\n \"send_notification_emails\": True,\n \"email_lang\": \"en\",\n \"phone\": \"+14155552671\",\n },\n expected_details={\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1990-05-15\",\n \"nationality\": \"USA\",\n \"id_country\": \"USA\",\n \"expected_document_types\": [\"P\", \"ID\"],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.create({\n workflow_id: \"11111111-2222-3333-4444-555555555555\",\n vendor_data: \"user-123\",\n callback: \"https://example.com/verification/callback\",\n callback_method: \"both\",\n metadata: { user_type: \"premium\", account_id: \"ABC123\" },\n language: \"en\",\n contact_details: {\n email: \"john.doe@example.com\",\n send_notification_emails: true,\n email_lang: \"en\",\n phone: \"+14155552671\",\n },\n expected_details: {\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1990-05-15\",\n nationality: \"USA\",\n id_country: \"USA\",\n expected_document_types: [\"P\", \"ID\"],\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Create(ctx, didit.SessionsCreateParams{\n\tWorkflowID: \"11111111-2222-3333-4444-555555555555\",\n\tVendorData: didit.String(\"user-123\"),\n\tCallback: didit.String(\"https://example.com/verification/callback\"),\n\tCallbackMethod: didit.Some(didit.SessionsCreateParamsCallbackMethod(\"both\")),\n\tMetadata: didit.Some[any](map[string]any{\"user_type\": \"premium\", \"account_id\": \"ABC123\"}),\n\tLanguage: didit.Some(didit.SessionsCreateParamsLanguage(\"en\")),\n\tContactDetails: didit.Some(didit.SessionsCreateParamsContactDetails{\n\t\tEmail: didit.String(\"john.doe@example.com\"),\n\t\tSendNotificationEmails: didit.Bool(true),\n\t\tEmailLang: didit.Some(didit.SessionsCreateParamsContactDetailsEmailLang(\"en\")),\n\t\tPhone: didit.String(\"+14155552671\"),\n\t}),\n\tExpectedDetails: didit.Some(didit.SessionsCreateParamsExpectedDetails{\n\t\tFirstName: didit.String(\"John\"),\n\t\tLastName: didit.String(\"Doe\"),\n\t\tDateOfBirth: didit.String(\"1990-05-15\"),\n\t\tNationality: didit.String(\"USA\"),\n\t\tIDCountry: didit.String(\"USA\"),\n\t\tExpectedDocumentTypes: didit.Some([]didit.SessionsCreateParamsExpectedDetailsExpectedDocumentTypes{\"P\", \"ID\"}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().create(SessionsCreateParams.builder()\n .workflowId(\"11111111-2222-3333-4444-555555555555\")\n .vendorData(\"user-123\")\n .callback(\"https://example.com/verification/callback\")\n .callbackMethod(SessionsCreateParams.CallbackMethod.of(\"both\"))\n .metadata(Map.of(\"user_type\", \"premium\", \"account_id\", \"ABC123\"))\n .language(SessionsCreateParams.Language.of(\"en\"))\n .contactDetails(SessionsCreateParams.ContactDetails.builder()\n .email(\"john.doe@example.com\")\n .sendNotificationEmails(true)\n .emailLang(SessionsCreateParams.ContactDetails.EmailLang.of(\"en\"))\n .phone(\"+14155552671\")\n .build())\n .expectedDetails(SessionsCreateParams.ExpectedDetails.builder()\n .firstName(\"John\")\n .lastName(\"Doe\")\n .dateOfBirth(LocalDate.parse(\"1990-05-15\"))\n .nationality(\"USA\")\n .idCountry(\"USA\")\n .expectedDocumentTypes(List.of(SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of(\"P\"), SessionsCreateParams.ExpectedDetails.ExpectedDocumentTypes.of(\"ID\")))\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->create([\n 'workflow_id' => '11111111-2222-3333-4444-555555555555',\n 'vendor_data' => 'user-123',\n 'callback' => 'https://example.com/verification/callback',\n 'callback_method' => 'both',\n 'metadata' => ['user_type' => 'premium', 'account_id' => 'ABC123'],\n 'language' => 'en',\n 'contact_details' => [\n 'email' => 'john.doe@example.com',\n 'send_notification_emails' => true,\n 'email_lang' => 'en',\n 'phone' => '+14155552671',\n ],\n 'expected_details' => [\n 'first_name' => 'John',\n 'last_name' => 'Doe',\n 'date_of_birth' => '1990-05-15',\n 'nationality' => 'USA',\n 'id_country' => 'USA',\n 'expected_document_types' => ['P', 'ID'],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.create(\n workflow_id: \"11111111-2222-3333-4444-555555555555\",\n vendor_data: \"user-123\",\n callback: \"https://example.com/verification/callback\",\n callback_method: \"both\",\n metadata: { user_type: \"premium\", account_id: \"ABC123\" },\n language: \"en\",\n contact_details: {\n email: \"john.doe@example.com\",\n send_notification_emails: true,\n email_lang: \"en\",\n phone: \"+14155552671\",\n },\n expected_details: {\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1990-05-15\",\n nationality: \"USA\",\n id_country: \"USA\",\n expected_document_types: [\"P\", \"ID\"],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.CreateAsync(new SessionsCreateParams\n{\n WorkflowId = \"11111111-2222-3333-4444-555555555555\",\n VendorData = \"user-123\",\n Callback = \"https://example.com/verification/callback\",\n CallbackMethod = new SessionsCreateParamsCallbackMethod(\"both\"),\n Metadata = new Dictionary { [\"user_type\"] = \"premium\", [\"account_id\"] = \"ABC123\" },\n Language = new SessionsCreateParamsLanguage(\"en\"),\n ContactDetails = new SessionsCreateParamsContactDetails\n {\n Email = \"john.doe@example.com\",\n SendNotificationEmails = true,\n EmailLang = new SessionsCreateParamsContactDetailsEmailLang(\"en\"),\n Phone = \"+14155552671\",\n },\n ExpectedDetails = new SessionsCreateParamsExpectedDetails\n {\n FirstName = \"John\",\n LastName = \"Doe\",\n DateOfBirth = \"1990-05-15\",\n Nationality = \"USA\",\n IdCountry = \"USA\",\n ExpectedDocumentTypes = new SessionsCreateParamsExpectedDetailsExpectedDocumentTypes[] { \"P\", \"ID\" },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "workflow_id" ], "properties": { "workflow_id": { "type": "string", "format": "uuid", "description": "工作流的稳定标识符，用于定义会话将运行哪些验证步骤。工作流在控制台的 [工作流](/zh/console/workflows) 页面中创建和管理。`workflow_id` 还会隐式选择该会话是 KYC 还是 KYB。", "example": "11111111-2222-3333-4444-555555555555", "x-readme-id": "0.0" }, "vendor_data": { "type": "string", "description": "正在接受验证的用户的唯一标识符，例如 UUID、邮箱或内部用户 ID。此字段用于：(1) **用户分组**：具有相同 vendor_data 的会话将关联到“用户”选项卡中的同一个用户资料。(2) **跨会话重复检测**：在检查重复的人脸、证件、电话号码、邮箱、IP 地址或设备指纹时，具有相同 vendor_data 的会话将被视为同一用户并从匹配项中排除。若不提供 vendor_data，每个会话都将被视为独立用户，且所有潜在重复项都会被显示。我们强烈建议始终提供 vendor_data，以减少重复检测中的干扰。", "example": "user-123", "x-readme-id": "0.1" }, "multi_account_segment": { "type": "string", "maxLength": 64, "description": "您组织内部可选的重复检测领域（realm）。重复人脸检查仅会将当前会话与带有相同 segment 的其他会话进行比对，因此独立的账户体系（个人账户和企业账户，或每个 B2B 子客户对应一个账户体系）不会将合法在两边各持有一个账户的用户误标记。省略此项将使用单一的默认领域，这也是目前所有会话所使用的模式。黑名单和白名单匹配会忽略此字段。", "example": "business-accounts" }, "callback": { "type": "string", "description": "验证完成后重定向用户的 URL。Didit 会自动将 `verificationSessionId` 和 `status`（Approved、Declined、In Review）作为查询参数附加。支持自定义 URL 方案（例如 `myapp://`）用于移动端回调。如果省略，将使用工作流的默认 `callback_url`。当应用配置了允许的域名（`PATCH /v3/webhook/` 上的 `allowed_domains`）时，`http` 或 `https` 回调必须位于这些源之一上（相同的方案、主机和端口），否则请求将在 `callback` 上失败并返回 400：`callback must be on one of the application's allowed domains: https://app.example.com`。自定义 URL 方案始终会被接受。", "example": "https://example.com/verification/callback", "x-readme-id": "0.2" }, "callback_method": { "type": "string", "description": "决定哪个设备应处理重定向到提供的回调 URL。使用 `initiator` 仅重定向启动流程的设备，使用 `completer` 重定向完成流程的设备，或使用 `both` 允许任一设备触发回调。如果您发现回调无法可靠触发，我们建议将此值设置为 `both`。", "enum": [ "initiator", "completer", "both" ], "default": "initiator", "example": "both", "x-readme-id": "0.3" }, "metadata": { "description": "随会话一起存储并在响应和 Webhook 中原样回显的任意 JSON。接受任何 JSON 值（对象、字符串、数字、数组），但建议使用键/值对形式的 JSON 对象。不对终端用户显示。可用于传递您自己的关联 ID、A/B 测试变体或业务上下文。", "example": { "user_type": "premium", "account_id": "ABC123" }, "x-readme-id": "0.4" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 50 }, "maxItems": 10, "description": "创建会话时按名称添加到该会话的标签。最多 10 个，每个最多 50 个字符。名称不区分大小写，并以大写形式存储。应用中尚不存在的名称将作为新标签创建。这些标签会显示在控制台的会话中，您可以在控制台中按标签进行过滤。", "example": [ "VIP", "ONBOARDING Q4" ] }, "language": { "type": "string", "description": "验证流程界面的语言代码（ISO 639-1）。控制验证期间向终端用户显示的语言。如果未提供，将自动检测并使用浏览器的语言。请在[此处](/zh/integration/supported-languages)查看所有支持的语言。", "enum": [ "en", "ar", "bg", "bn", "bs", "ca", "cnr", "cs", "da", "de", "el", "es", "et", "fa", "fi", "fr", "he", "hi", "hr", "hu", "hy", "id", "it", "ja", "ka", "kk", "ko", "ky", "lt", "lv", "mk", "mn", "ms", "nl", "no", "pl", "pt-BR", "pt", "ro", "ru", "sk", "sl", "so", "sq", "sr", "sv", "th", "tr", "uk", "uz", "vi", "zh-CN", "zh-TW", "zh" ], "example": "en", "x-readme-id": "0.5" }, "contact_details": { "type": "object", "description": "可用于通知、预填验证表单以及电话验证的用户联系信息。包括电子邮箱地址、首选沟通语言和电话号码。", "example": { "email": "john.doe@example.com", "send_notification_emails": true, "email_lang": "en", "phone": "+14155552671" }, "properties": { "email": { "type": "string", "format": "email", "description": "用户的邮箱地址（例如 \"john.doe@example.com\"），将在[邮箱验证](/zh/core-technology/email-verification/overview)步骤中使用。如果未提供，用户必须在验证流程中自行提供。", "example": "john.doe@example.com", "x-readme-id": "1.0" }, "send_notification_emails": { "type": "boolean", "default": false, "description": "若为 true 且提供了邮箱，Didit 会在创建用户验证（KYC）或企业验证（KYB）会话时以异步方式发送初始“验证您的身份”邮件。Didit 还会将需要人工审核的会话的验证状态通知发送至所提供的邮箱地址（例如，从“审核中”变为“已通过”或“已拒绝”）。这有助于用户在验证完成后返回您的应用。如果您为该会话启用了白标，发送的邮件将采用白标定制。", "example": true, "x-readme-id": "1.1" }, "email_lang": { "type": "string", "description": "邮件通知的语言代码（ISO 639-1）。控制所有邮件通信的语言（例如 \"en\"、\"es\"、\"fr\"）。未存储默认值；省略时，验证邀请邮件仅在发送时回退为英语（`en`）。下方的枚举为快照；支持值的实时基准信息请参阅[支持的语言](/zh/integration/supported-languages)文档，在依赖特定代码之前，请始终查阅该文档。", "enum": [ "en", "ar", "bg", "bn", "bs", "ca", "cnr", "cs", "da", "de", "el", "es", "et", "fa", "fi", "fr", "he", "hi", "hr", "hu", "hy", "id", "it", "ja", "ka", "kk", "ko", "ky", "lt", "lv", "mk", "mn", "ms", "nl", "no", "pl", "pt-BR", "pt", "ro", "ru", "sk", "sl", "so", "sq", "sr", "sv", "th", "tr", "uk", "uz", "vi", "zh-CN", "zh-TW", "zh" ], "example": "en", "x-readme-id": "1.2" }, "phone": { "type": "string", "description": "将在[电话验证](/zh/core-technology/phone-verification/overview)步骤中使用的 E.164 格式电话号码（例如 \"+14155552671\"）。如果未提供，用户必须在验证流程中输入。企业验证（KYB）工作流会忽略此字段。**重要提示：**仅当该电话号码为有效的 E.164 电话号码时才会强制生效。如果提供的号码无效或无法解析，系统将忽略该号码，用户可以在电话验证步骤中输入任意有效电话号码。", "example": "+14155552671", "x-readme-id": "1.3" } }, "x-readme-id": "0.4" }, "expected_details": { "type": "object", "description": "预期的用户详细信息，用于与从用户身份证件、地址证明和其他验证步骤中提取的数据进行交叉比对。不匹配项将在决策中作为警告呈现；某些字段（例如 `id_country`、`expected_document_types`）还会改变面向用户的流程。对于企业验证（KYB）工作流，仅使用企业字段（`company_name`、`registry_country`、`registration_number`），它们会为用户预填充公司登记搜索，所有人员级字段均被忽略。", "example": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "nationality": "USA", "id_country": "USA", "expected_document_types": [ "P", "ID" ] }, "properties": { "first_name": { "type": "string", "description": "用户的名。例如 `John`。比对采用模糊比较，您可以通过在控制台中为身份证件和地址证明工作流配置姓名匹配分数阈值来调整严格程度。", "example": "John", "x-readme-id": "1.0" }, "last_name": { "type": "string", "description": "用户的姓。例如 `Doe`。比对采用模糊比较，您可以通过在控制台中为身份证件和地址证明工作流配置姓名匹配分数阈值来调整严格程度。", "example": "Doe", "x-readme-id": "1.1" }, "date_of_birth": { "type": "string", "format": "date", "description": "用户的出生日期，格式为：YYYY-MM-DD。例如 `1990-05-15`。", "example": "1990-05-15", "x-readme-id": "1.2" }, "gender": { "type": "string", "nullable": true, "enum": [ "M", "F" ], "default": null, "description": "用户的性别。必须为 'M'、'F' 或 null。", "example": "M", "x-readme-id": "1.3" }, "nationality": { "type": "string", "description": "代表申请人原籍国家/地区的 ISO 3166-1 alpha-3 国家/地区代码。例如 `USA`。请参阅[受支持国家/地区代码的完整列表](https://docs.didit.me/zh/core-technology/id-verification/supported-documents-id-verification#按国家/地区列出的支持证件)。", "example": "USA", "x-readme-id": "1.4" }, "country": { "type": "string", "description": "用作身份证件验证和地址证明国家/地区不匹配检查备用项的 ISO 3166-1 alpha-3 国家/地区代码。当提供了 `address` 且未设置 `id_country` 和 `poa_country` 时必填。", "example": "USA", "x-readme-id": "1.4.1" }, "id_country": { "type": "string", "description": "代表申请人身份证件预期国家/地区的 ISO 3166-1 alpha-3 国家/地区代码（可能与国籍不同）。例如 `GBR`。在身份证件验证国家/地区不匹配检查中优先于 `country`。请参阅[受支持国家/地区代码的完整列表](https://docs.didit.me/zh/core-technology/id-verification/supported-documents-id-verification#按国家/地区列出的支持证件)。", "example": "GBR", "x-readme-id": "1.5" }, "poa_country": { "type": "string", "description": "代表地址证明文件预期国家/地区的 ISO 3166-1 alpha-3 国家/地区代码。例如 `USA`。在 POA 国家/地区不匹配检查中优先于 `country`。请参阅[受支持国家/地区代码的完整列表](https://docs.didit.me/zh/core-technology/id-verification/supported-documents-id-verification#按国家/地区列出的支持证件)。", "example": "USA", "x-readme-id": "1.5.1" }, "address": { "type": "string", "description": "人类可读格式的地址，包含尽可能多的详细信息。例如 `123 Main St, San Francisco, CA 94105, USA`。提供此参数时，您还必须传递 `country` 或 `poa_country`，否则请求将失败并返回 `400`。", "example": "123 Main St, San Francisco, CA 94105, USA", "x-readme-id": "1.6" }, "identification_number": { "type": "string", "description": "用户的证件号码、个人编号或税号。例如 `123456789`。", "example": "123456789", "x-readme-id": "1.7" }, "ip_address": { "type": "string", "description": "会话的预期 IP 地址，采用 IPv4 或 IPv6 格式。如果实际 IP 地址与此值不一致，将记录警告。例如 `192.168.1.100` 或 `2001:db8::1`。", "example": "192.168.1.100", "x-readme-id": "1.8" }, "expected_document_types": { "type": "array", "description": "限制用户在身份证件验证（OCR）步骤中可以出示的证件类型。设置后，证件选择界面仅显示所请求的类型，且返回的 `documents_allowed` 会进行相应过滤。值不区分大小写并会自动去重；无法识别的值会被拒绝并返回 `400`。允许的代码：`P`（护照）、`ID`（国民身份证）、`DL`（驾照）、`RP`（居留许可）、`HIC`（健康保险卡）、`TC`（税卡）、`SSC`（社保卡）。", "items": { "type": "string", "enum": [ "P", "ID", "DL", "RP", "HIC", "TC", "SSC" ] }, "example": [ "P", "ID" ], "x-readme-id": "1.9" }, "company_name": { "type": "string", "maxLength": 255, "description": "待验证企业的预期法定名称。例如，`Tesco PLC`。在企业验证（KYB）工作流中预填充公司登记搜索的公司名称字段；若同时提供了 `registration_number`，登记查询将结合这两个标识符。在 KYC 工作流中忽略。", "example": "Tesco PLC", "x-readme-id": "1.10" }, "registry_country": { "type": "string", "maxLength": 10, "description": "企业所注册的公司登记处所在国家/地区的 ISO 3166-1 alpha-2 代码。例如 `GB`。如果公司登记处在州或省级别运作，请以 `XX-YY` 格式附加 ISO 3166-2 行政区划代码：`US-CA` 针对加利福尼亚州登记处。与 [KYB 登记处搜索 API](https://docs.didit.me/zh/standalone-apis/kyb-registry-search) 上的 `country_code` 格式相同。在企业验证（KYB）工作流中预选登记处国家/地区；在 KYC 工作流中忽略。", "example": "US-CA", "x-readme-id": "1.11" }, "registration_number": { "type": "string", "maxLength": 100, "description": "企业在公司登记中的预期注册号。例如，`00445790`。在企业验证（KYB）工作流中预填充登记搜索的注册号字段；若同时提供了 `company_name`，登记查询将结合这两个标识符。在 KYC 工作流中忽略。", "example": "00445790", "x-readme-id": "1.12" } }, "x-readme-id": "0.5" }, "portrait_image": { "type": "string", "format": "byte", "description": "终端用户人脸的 Base64 编码肖像图像（最大 2MB；JPEG、PNG、WebP 或 TIFF）。当工作流是启用了人脸比对的 `Biometric Authentication` 工作流，或人脸比对在身份证件验证（OCR）之前运行的任何图谱工作流时，用作与活体采集进行比对的参考图像。当 `vendor_data` 用户已有存储的人脸图像时为可选：Didit 会按以下优先级自动复用：已通过的活体人脸、电子护照芯片照片、身份证件肖像、手动录入的个人资料人脸（仅复用来自已通过会话的人脸或您自行录入的人脸）。提供时，`portrait_image` 始终优先于存储的人脸。如果省略且不存在已存储的人脸（或未发送 `vendor_data`），会话创建将失败并返回 `400`。对于其他工作流类型将被忽略。", "example": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=", "x-readme-id": "0.6" }, "sandbox_scenario": { "type": "string", "description": "仅限沙盒的场景 slug。仅在 API 密钥属于沙盒模式应用时被接受；在生产环境应用上会被拒绝。设置后，创建流程会将场景绑定的魔法值展开到会话的输入字段（contact_details、expected_details）中，以便模拟的供应商通过真实的工作流管道复现该场景的结果。请参阅 GET /v1/sandbox/scenarios/ 中的场景目录或[沙盒与测试数据](/zh/integration/sandbox-testing)。只要会话仍处于 `Not Started` 状态，您也可以在创建后通过 POST /v3/session/{sessionId}/sandbox/arm/ 预设（或重新预设）场景。对于非证件查询，使用 `lookup_partial_match`、`lookup_no_match` 或 `lookup_provider_error` 来测试配置的尝试预算和回退机制。对于身份钱包，使用 `wallet_cancelled`、`wallet_timeout` 或 `wallet_provider_error`；`approve` 模拟已验证的钱包。所有目录中的钱包均可在沙盒中进行测试，包括生产环境应用中不可用的方案。模拟的尝试不会被计费。", "example": "decline_document_expired" }, "sign": { "type": "object", "description": "此会话的电子签名输入。`documents` 为待签署的文件，适用于电子签名步骤从会话中获取文件（`signature_documents_source` 为 `session` 或 `both`）的工作流：总计最多 20 个文件和 50 MB。`field_values` 用于填充工作流文件和会话文件中 `prefill` 为 `api.` 的字段。针对相同的 `workflow_id` 和 `vendor_data` 再次创建会话将返回待处理的会话；如果该调用发送了 `sign`，其文件、字段和值必须与首次调用完全一致，若有任何不同，将返回 `400` 以及 `{\"sign\": \"signature_document_changed\"}`。请参阅 [电子签名文件](/zh/sessions-api/create-session#电子签名文档)。", "properties": { "documents": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/SessionSignDocument" } }, "field_values": { "type": "object", "description": "以每个 `api.` 预填充源的 `` 为键的值：`text` 和 `data` 字段为 1 到 500 个字符的字符串，`checkbox` 为布尔值。若键未被任何字段使用则返回 `400` 及 `field_value_unknown`，若必填字段缺少值则返回 `field_value_missing`，若值未通过字段验证则返回 `field_value_invalid`。", "additionalProperties": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "boolean" } ] }, "example": { "credit_limit": "3,000 EUR" } } } }, "user_state": { "type": "string", "maxLength": 16, "description": "此人的居住地（已知时）：ISO 3166-2 行政区划代码（`US-IL`、`ES-M`）或美国州代码或名称（`IL`、`Illinois`）。法律要求明确生物识别同意的州（伊利诺伊州、得克萨斯州、科罗拉多州）会使验证流程在捕获人脸之前征求同意，触发器为 `declared_state`。无法识别的值将返回 `400`。请参阅[生物识别同意](/zh/getting-started/biometric-consent)。", "example": "US-IL" }, "biometric_consent": { "type": "object", "description": "您已向该人员收集的显式生物识别同意。这满足了要求，因此验证流程不会再次询问，决策会将其记录为 `status: \"given\"`，触发器为 `customer_collected`。该人员在流程中已给出的回答绝不会被替换。请参阅[生物识别同意](/zh/getting-started/biometric-consent)。", "required": [ "given_at", "text_version" ], "properties": { "given_at": { "type": "string", "format": "date-time", "description": "当事人给出明确生物识别同意的时间（ISO 8601）。不能是未来的时间。" }, "text_version": { "type": "string", "maxLength": 64, "description": "该人员接受的同意文本在您自身记录中的版本 ID。" } } } }, "example": { "workflow_id": "11111111-2222-3333-4444-555555555555", "vendor_data": "user-123", "callback": "https://example.com/verification/callback", "callback_method": "both", "metadata": { "user_type": "premium", "account_id": "ABC123" }, "language": "en", "contact_details": { "email": "john.doe@example.com", "send_notification_emails": true, "email_lang": "en", "phone": "+14155552671" }, "expected_details": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "id_country": "USA", "expected_document_types": [ "P", "ID" ] } } }, "examples": { "Create KYC session": { "summary": "用户验证（KYC）会话的完整成功路径 payload", "description": "使用了所有通常设置的字段的真实创建调用：工作流选择、供应商关联、回调路由、元数据、语言环境、联系方式预填以及预期的用户详情。可直接复制并粘贴到上方的 cURL 示例中。", "value": { "workflow_id": "11111111-2222-3333-4444-555555555555", "vendor_data": "user-123", "callback": "https://example.com/verification/callback", "callback_method": "both", "metadata": { "user_type": "premium", "account_id": "ABC123" }, "language": "en", "contact_details": { "email": "john.doe@example.com", "send_notification_emails": true, "email_lang": "en", "phone": "+14155552671" }, "expected_details": { "first_name": "John", "last_name": "Doe", "date_of_birth": "1990-05-15", "nationality": "USA", "id_country": "USA", "expected_document_types": [ "P", "ID" ] } } }, "Create KYB session": { "summary": "企业验证（KYB）会话的正常流程 payload", "description": "数据结构与 KYC 调用相同，`workflow_id` 决定了会话为 KYB。`vendor_data` 通常引用您系统中的公司，`contact_details.email` 指向将完成该流程的法定代表人。`expected_details` 接收企业字段（`company_name`、`registry_country`、`registration_number`），这些字段会预填充公司登记搜索；个人级字段和 `contact_details.phone` 在 KYB 工作流中会被忽略。", "value": { "workflow_id": "33333333-4444-5555-6666-777777777777", "vendor_data": "company-acme-001", "callback": "https://example.com/kyb/callback", "callback_method": "both", "metadata": { "tier": "enterprise", "company_id": "ACME-001" }, "expected_details": { "company_name": "Tesco PLC", "registry_country": "GB", "registration_number": "00445790" }, "language": "en", "contact_details": { "email": "legal-rep@acme.example.com", "send_notification_emails": true, "email_lang": "en" } } } } } } } } }, "/v3/session/imports/": { "post": { "summary": "创建验证导入任务", "description": "为历史用户验证会话、企业验证会话、交易监控记录或工作流自定义状态规则创建异步导入任务。设置 `source=provider` 以从其他提供商迁移：Didit 使用您的只读密钥读取 Sumsub、Onfido、Persona 和 ComplyCube；通过您在 `file` 中上传的 ID 读取 Veriff、iDenfy 和 MetaMap 记录；对于其他提供商，则导入 Didit 格式的导出文件。记录 ID 按提供商进行命名空间隔离（`sumsub:`），因此重新运行会跳过 Didit 中已存在的所有内容；通过包含提供商裸 ID 的文件导入的记录也能双向被识别，因此在文件导入与提供商迁移之间切换绝不会重复导入记录。一个应用最多可同时运行 4 个导入任务；因部署或工作进程重启而中断的任务会自动从上次导入的行继续。导入功能默认处于禁用状态，必须由 Didit 按组织单独启用。", "operationId": "post_v3_session_imports_create", "x-didit-sdk": { "resource": "sessions.imports", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "import_type": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ], "default": "user_verification", "description": "要导入的内容：历史用户验证会话、历史企业验证会话、工作流自定义状态规则或历史交易监控记录。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "导入的会话或状态规则应关联的工作流 UUID。对于 user_verification、business_verification 和 status_rules 为必填项。对于 transactions 请省略。" }, "source_format": { "type": "string", "enum": [ "csv", "ndjson" ], "description": "可选。如果省略，将根据上传文件的扩展名推断。" }, "file": { "type": "string", "format": "binary", "description": "规范的 CSV 或 NDJSON 文件。大批量导入请使用 NDJSON。最大上传大小 25 MB（更大的文件请使用 `source_file_url`）。与 `source_file_url` 互斥。" }, "source_file_url": { "type": "string", "format": "uri", "description": "文件上传的替代方案。必须是解析为公共地址的 HTTPS URL（私有/回环网络将被拒绝）。与 `file` 互斥。" }, "source": { "type": "string", "enum": [ "file", "provider" ], "description": "`provider` 表示这是从另一家身份证件验证服务商进行的迁移。文件导入时请省略。" }, "provider": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ], "description": "迁移来源，来自 `GET /v3/session/imports/providers/`。当 `source` 为 `provider` 时必填。" }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "服务商的只读密钥，其字段名称由 `credential_fields` 列出。静态加密存储，从不返回，并在导入结束时抹除。请作为 multipart 中的 JSON 字符串发送。" }, "options": { "type": "object", "properties": { "region": { "type": "string", "description": "服务商区域，为其 `regions` 之一（Onfido：`eu`、`us`、`ca`）。" } } }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] }, "description": "对提供商默认状态映射的修改：将源状态映射到 Didit 状态。`Not Finished` 和 `Abandoned` 会被跳过并计数，绝不会被导入。" }, "dry_run": { "type": "boolean", "default": false, "description": "统计迁移将导入的内容（按状态、已在 Didit 中、同一人、未完成划分）且不写入任何内容。任务结束状态为 `READY`；使用 `POST /v3/session/imports/{importId}/start/` 启动它。" }, "face_templates": { "type": "boolean", "default": false, "description": "根据导入的自拍照构建人脸模板，并对照应用的人脸库和黑名单进行搜索。匹配项仅会被标记以供审核。需要 `lawful_basis_confirmed`。" }, "lawful_basis_confirmed": { "type": "boolean", "default": false, "description": "确认您拥有合法依据将这些自拍照共享给作为处理者的 Didit。" } } } }, "application/json": { "schema": { "type": "object", "required": [ "source_file_url" ], "properties": { "import_type": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ], "default": "user_verification", "description": "要导入的内容：历史用户验证会话、历史企业验证会话、工作流自定义状态规则或历史交易监控记录。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "导入的会话或状态规则应关联的工作流 UUID。对于 user_verification、business_verification 和 status_rules 为必填项。对于 transactions 请省略。" }, "source_format": { "type": "string", "enum": [ "csv", "ndjson" ], "description": "可选。如果省略，将根据 URL 的文件扩展名推断。" }, "source_file_url": { "type": "string", "format": "uri", "description": "文件上传的替代方案。必须是解析为公共地址的 HTTPS URL（私有/回环网络将被拒绝）。与 `file` 互斥。" }, "source": { "type": "string", "enum": [ "file", "provider" ], "description": "`provider` 表示这是从另一家身份证件验证服务商进行的迁移。文件导入时请省略。" }, "provider": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ], "description": "迁移来源，来自 `GET /v3/session/imports/providers/`。当 `source` 为 `provider` 时必填。" }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "服务商的只读密钥，其字段名称由 `credential_fields` 列出。静态加密存储，从不返回，并在导入结束时抹除。请作为 multipart 中的 JSON 字符串发送。" }, "options": { "type": "object", "properties": { "region": { "type": "string", "description": "服务商区域，为其 `regions` 之一（Onfido：`eu`、`us`、`ca`）。" } } }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] }, "description": "对提供商默认状态映射的修改：将源状态映射到 Didit 状态。`Not Finished` 和 `Abandoned` 会被跳过并计数，绝不会被导入。" }, "dry_run": { "type": "boolean", "default": false, "description": "统计迁移将导入的内容（按状态、已在 Didit 中、同一人、未完成划分）且不写入任何内容。任务结束状态为 `READY`；使用 `POST /v3/session/imports/{importId}/start/` 启动它。" }, "face_templates": { "type": "boolean", "default": false, "description": "根据导入的自拍照构建人脸模板，并对照应用的人脸库和黑名单进行搜索。匹配项仅会被标记以供审核。需要 `lawful_basis_confirmed`。" }, "lawful_basis_confirmed": { "type": "boolean", "default": false, "description": "确认您拥有合法依据将这些自拍照共享给作为处理者的 Didit。" } } }, "examples": { "URL-based import": { "value": { "import_type": "user_verification", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "source_file_url": "https://files.example.com/exports/sessions.ndjson" } } } } } }, "responses": { "201": { "description": "导入任务已受理。轮询返回的 `uuid`，直至 `status` 变为 `COMPLETED` 或 `FAILED`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" }, "examples": { "Job accepted": { "value": { "uuid": "3f9c1a2b-4d5e-4f60-8a7b-9c0d1e2f3a4b", "status": "PENDING", "import_type": "user_verification", "source_format": "ndjson", "source_filename": "sessions.ndjson", "total_rows": 0, "processed_rows": 0, "checkpoint_row": 0, "created_count": 0, "updated_count": 0, "skipped_count": 0, "failed_count": 0, "total_media_bytes": 0, "last_error": null, "created_at": "2026-05-17T08:42:11Z", "updated_at": "2026-05-17T08:42:11Z", "started_at": null, "completed_at": null } } } } } }, "400": { "description": "无效的工作流、文件类型、文件大小、来源 URL 或选择器组合。对于提供商拒绝其密钥的迁移，将返回 `code`（`invalid_credentials`、`missing_permission`、`wrong_region`、`provider_unavailable`、`rate_limited`、`ids_required`、`record_not_found`）、`missing_permissions` 和 `suggested_region`。", "content": { "application/json": { "examples": { "Invalid workflow": { "value": { "workflow_id": [ "Invalid workflow_id." ] } }, "Workflow required": { "value": { "workflow_id": [ "This field is required for this import type." ] } }, "Wrong file type": { "value": { "file": [ "Only CSV and NDJSON files are supported." ] } }, "File too large": { "value": { "file": [ "Import file exceeds the maximum allowed size." ] } }, "No source": { "value": { "file": [ "Upload a file or provide source_file_url." ] } }, "Both sources": { "value": { "file": [ "Use either file or source_file_url, not both." ] } } } } } }, "403": { "description": "未启用导入、沙盒应用或缺少 API 密钥（错误、已撤销或已过期的密钥会返回 `401`）。验证导入默认处于禁用状态，必须由 Didit 按组织单独启用。", "content": { "application/json": { "examples": { "Imports not enabled": { "value": { "detail": "Verification imports are not enabled for this organization." } }, "Sandbox": { "value": { "detail": "Verification imports are not enabled for sandbox applications." } }, "Bad API key": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "该应用已有 4 个处于活动状态的导入任务（PENDING/PROCESSING/PAUSED），已达同时运行的最大数量。请等待其中一个完成后再启动另一个。", "content": { "application/json": { "examples": { "Active job": { "value": { "detail": "This application already has 4 active import jobs, the most it can run at once. Wait for one to finish before starting another." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.create(\n import_type=\"user_verification\",\n workflow_id=\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n source_file_url=\"https://files.example.com/exports/sessions.ndjson\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.create({\n import_type: \"user_verification\",\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n source_file_url: \"https://files.example.com/exports/sessions.ndjson\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Create(ctx, didit.SessionsImportsCreateParams{\n\tImportType: didit.Some(didit.SessionsImportsCreateParamsImportType(\"user_verification\")),\n\tWorkflowID: didit.String(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\"),\n\tSourceFileURL: didit.String(\"https://files.example.com/exports/sessions.ndjson\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsImportsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().create(SessionsImportsCreateParams.builder()\n .importType(SessionsImportsCreateParams.ImportType.of(\"user_verification\"))\n .workflowId(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\")\n .sourceFileUrl(\"https://files.example.com/exports/sessions.ndjson\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->create([\n 'import_type' => 'user_verification',\n 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab',\n 'source_file_url' => 'https://files.example.com/exports/sessions.ndjson',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.create(\n import_type: \"user_verification\",\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n source_file_url: \"https://files.example.com/exports/sessions.ndjson\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.CreateAsync(new SessionsImportsCreateParams\n{\n ImportType = new SessionsImportsCreateParamsImportType(\"user_verification\"),\n WorkflowId = \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n SourceFileUrl = \"https://files.example.com/exports/sessions.ndjson\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/template/": { "get": { "summary": "下载验证导入模板", "description": "下载验证导入的标准 CSV 表头。列集合由 `import_type` 决定。会话模板的第一列为幂等性键 `external_id`。", "operationId": "get_v3_session_imports_template", "x-didit-sdk": { "resource": "sessions.imports", "method": "retrieve_template", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "import_type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ], "default": "user_verification" } } ], "responses": { "200": { "description": "CSV 模板文件。", "content": { "text/csv": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法下载导入模板。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "summary": "API 密钥缺失、无效或已撤销", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.imports.retrieve_template()\nwith open(\"download.csv\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.imports.retrieveTemplate();\nawait writeFile(\"download.csv\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Imports.RetrieveTemplate(ctx, didit.SessionsImportsRetrieveTemplateParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.csv\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().imports().retrieveTemplate()\n .writeTo(Path.of(\"download.csv\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->retrieveTemplate();\n$content->saveTo('download.csv');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.imports.retrieve_template\nFile.binwrite(\"download.csv\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Imports.RetrieveTemplateAsync();\nawait content.SaveToAsync(\"download.csv\");" } ] } }, "/v3/session/imports/{importId}/": { "get": { "summary": "获取验证导入作业", "description": "获取单个作业的导入进度计数器和最终状态。轮询直到 `status` 为 `COMPLETED` 或 `FAILED`；`failed_count` > 0 表示某些行被拒绝，可通过错误 endpoint 列出它们。", "operationId": "get_v3_session_imports_retrieve", "x-didit-sdk": { "resource": "sessions.imports", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "导入任务状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "404": { "description": "未找到此应用的导入任务。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法读取此应用的导入任务。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "summary": "API 密钥缺失、无效或已撤销", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/errors/": { "get": { "summary": "列出验证导入行错误", "description": "按 `row_number` 排序，列出验证导入作业的行级错误。使用此 endpoint 可生成仅包含失败行的更正重试文件。", "operationId": "get_v3_session_imports_errors", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_errors", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "页面大小。省略时默认为 50。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "要返回的第一条记录的从零开始的偏移量。" } ], "responses": { "200": { "description": "分页行错误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "错误行数：不超过 100 时为精确值，超过 100 时上限为 100。请依靠 `next` 为 `null` 来检测最后一页。" }, "next": { "type": "string", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SessionImportError" } } } }, "examples": { "Row errors": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "5a6b7c8d-9e0f-4a1b-8c2d-3e4f5a6b7c8d", "row_number": 17, "external_id": "ext-000017", "error": "status: invalid value 'unknown_status'", "raw_row": { "external_id": "ext-000017", "status": "unknown_status", "first_name": "Jane" }, "created_at": "2026-05-17T08:44:02Z" } ] } } } } } }, "404": { "description": "未找到此应用的导入任务。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法读取此应用的导入任务。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "summary": "API 密钥缺失、无效或已撤销", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.imports.list_errors(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.imports.listErrors(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.Imports.ListErrorsAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsImportsListErrorsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().imports().listErrors(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listErrors('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.imports.list_errors(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.Imports.ListErrorsAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/decision/": { "get": { "summary": "获取验证会话的完整决策", "description": "获取验证会话的完整决策报告，包含汇总的会话 `status` 以及工作流执行的每个验证功能对应的一份报告。这是用户验证（KYC）和企业验证（KYB）会话的标准读取 endpoint：同一个路径同时支持两者，顶层的 `session_kind` 鉴别器会告知您收到的数据结构（`\"user\"` 或 `\"business\"`）。\n\n**每个功能报告均为复数数组。** V3 工作流是图谱结构，可以多次运行同一功能，因此每个块（`id_verifications`、`nfc_verifications`、`liveness_checks`、`face_matches`、`poa_verifications`、`document_ai_documents`、`phone_verifications`、`email_verifications`、`aml_screenings`、`ip_analyses`、`database_validations`、`questionnaire_responses`）都是一个 JSON 数组，其中的每一项都带有一个 `node_id`，用于标识生成它的工作流图谱节点。读取 NFC 时请使用 `response.nfc_verifications[0]`，切勿作为单数 `nfc` 字段读取。在工作流至少运行该功能一次之前，该块为 `null`；工作流未包含的功能绝不会带有数据返回。电子签名结果位于 `signatures` 中，仅当工作流包含电子签名步骤时才会出现。\n\n**何时调用。** 推荐的模式是事件驱动：等待会话做出决策（`Approved`、`Declined`、`In Review`）时触发的 `status.updated` Webhook，然后调用此 endpoint 一次以获取完整报告。轮询也同样可行（该 endpoint 可以在会话生命周期的任何时间点调用，并返回迄今为止生成的数据），但“收到 Webhook 后再获取”成本更低且速度更快。响应中的媒体 URL（证件图像、视频、PDF）是短期的预签名链接：请及时获取或重新请求决策以获取最新链接，切勿将其作为长期引用持久化保存。\n\n**状态。** 顶层 `status` 是会话生命周期状态（`Not Started`、`In Progress`、`Awaiting User`、`In Review`、`Approved`、`Declined`、`Resubmitted`、`Expired`、`Kyc Expired`、`Abandoned`）。每个功能项还带有自己的功能级 `status`（`Not Finished`、`Approved`、`Declined`、`In Review` 等）。根据工作流的决策规则，即使某个单独功能处于 `In Review`，会话总体上也可能为 `Approved`。\n\n**身份验证与可见性。** 使用 `x-api-key` 请求头中的应用 API 密钥进行身份验证（具有 `read:sessions` 权限的控制台用户 Bearer token 也可使用）。只有通过身份验证的应用所拥有的会话才可见。如果您的工作流限制了响应属性，功能项内未允许的字段将作为 `null` 返回，而 `status`、`warnings` 和 `node_id` 始终予以保留。\n\n**速率限制。** 每个 API 密钥每分钟限制 600 次 GET 请求。超过限制将返回 `429` 以及 `Retry-After` 和 `X-RateLimit-*` 请求头。", "operationId": "get_v3_session_decision", "x-didit-sdk": { "resource": "sessions", "method": "retrieve_decision", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "完整决策报告。`session_kind` 用于区分两种结构：`user` 会话包含下方所示的 KYC 功能数组；而 `business` 会话则在共享数组的基础上包含 `registry_checks`、`document_verifications` 和 `key_people_checks`。在工作流运行相应功能之前，功能数组为 `null`；媒体 URL 是具有有效期的预签名链接。", "content": { "application/json": { "examples": { "Example": { "summary": "完整示例", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "session_kind": "user", "session_number": 43762, "session_url": "https://verify.didit.me/session/11111111-2222-3333-4444-555555555555", "status": "In Review", "environment": "live", "workflow_id": "11111111-2222-3333-4444-555555555555", "features": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACE_MATCH", "POA", "PHONE", "DATABASE_VALIDATION", "AML", "IP_ANALYSIS" ], "vendor_data": "11111111-1111-1111-1111-111111111111", "metadata": { "user_type": "premium", "account_id": "ABC123" }, "expected_details": { "first_name": "Carmen", "last_name": "Española Española" }, "contact_details": { "email": "carmen@example.com", "email_lang": "es", "send_notification_emails": false, "phone": null }, "callback": "https://verify.didit.me/", "id_verifications": [ { "node_id": "feature_ocr_1", "status": "Approved", "document_type": "Identity Card", "document_subtype": "ID_CARD_GENERIC", "document_number": "CAA000000", "personal_number": "99999999R", "portrait_image": "https:///portrait.jpg", "front_image": "https:///front.jpg", "front_video": "https:///front.mp4", "back_image": "https:///back.jpg", "back_video": "https:///back.mp4", "full_front_image": "https:///full_front.jpg", "full_back_image": "https:///full_back.jpg", "front_image_camera_front": "https:///front_camera_front.jpg", "back_image_camera_front": "https:///back_camera_front.jpg", "date_of_birth": "1980-01-01", "age": 45, "expiration_date": "2031-06-02", "date_of_issue": "2021-06-02", "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "Carmen", "last_name": "Española Española", "full_name": "Carmen Española Española", "gender": "F", "address": "Avda de Madrid 34, Madrid, Madrid", "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain", "place_of_birth": "Madrid", "marital_status": "Single", "nationality": "ESP", "extra_fields": { "dl_categories": [], "blood_group": null }, "mrz": { "surname": "ESPANOLA ESPANOLA", "name": "CARMEN", "country": "ESP", "nationality": "ESP", "birth_date": "800101", "expiry_date": "310602", "sex": "F", "document_type": "ID", "document_number": "CAA000000", "optional_data": "99999999R", "optional_data_2": "", "birth_date_hash": "4", "expiry_date_hash": "8", "document_number_hash": "4", "final_hash": "1", "personal_number": "99999999R", "warnings": [], "errors": [], "mrz_type": "TD1", "mrz_string": "IDESPCAA000000499999999R<<<<<<\n8001014F3106028ESP<<<<<<<<<<<1\nESPANOLA/match_face.jpg", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null, "source": "session" } ], "front_image_quality_score": { "focus_score": 85.3, "brightness_score": 92.1, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 72.4, "overall_score": 88.7 }, "back_image_quality_score": { "focus_score": 79.1, "brightness_score": 90.5, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 72.4, "overall_score": 85.2 }, "extra_files": [ "https:///extra_id_verification.jpg" ], "matches": [ { "session_id": "7d4f1f60-9c2e-4b8a-8f3d-2a1b5c6d7e8f", "session_number": 1234, "vendor_data": "user_ref_001", "verification_date": "2024-06-15T10:30:00Z", "user_details": { "name": "John Smith", "document_type": "ID", "document_number": "CLM148418" }, "status": "Approved", "is_blocklisted": false, "api_service": null, "front_image_url": "https:///document_front.jpg" }, { "session_id": "b2c8e4d1-6a3f-4e7b-95c0-1d8f2a6b4c9e", "session_number": 1235, "vendor_data": null, "verification_date": "2024-05-20T14:45:00Z", "user_details": { "name": "John Smith", "document_type": "ID", "document_number": "CLM148418" }, "status": "Declined", "is_blocklisted": true, "api_service": "ID_VERIFICATION", "front_image_url": "https:///document_front_2.jpg" } ], "warnings": [ { "feature": "ID_VERIFICATION", "risk": "QR_NOT_DETECTED", "additional_data": null, "log_type": "information", "short_description": "QR not detected", "long_description": "The system couldn't find or read the QR code on the document, which is necessary for document verification. This could be due to poor image quality or an unsupported document type.", "node_id": "feature_ocr_1" } ], "verification_method": "document", "assurance": "documentary", "wallet_provider": null, "fallback_from": null, "id_lookup": null, "wallet_verification": null, "document_liveness": { "portrait_replace": { "score": 96.46, "front": 96.46, "back": 98.2, "decline_threshold": 35, "review_threshold": 70, "bucket": "approve" }, "printed_copy": { "score": 91.2, "front": 91.2, "back": 93.7, "decline_threshold": 35, "review_threshold": 77, "bucket": "approve" }, "screen_replay": { "score": 99.9, "front": 99.9, "back": 99.5, "decline_threshold": 30, "review_threshold": 70, "bucket": "approve" } } }, { "node_id": "feature_ocr_2", "status": "Approved", "issuing_state": "ZAF", "issuing_state_name": "South Africa", "first_name": "Thabo", "last_name": "Mokoena", "full_name": "Thabo Mokoena", "date_of_birth": "1991-06-15", "personal_number": "9106155043088", "verification_method": "id_lookup", "assurance": "data_match", "wallet_provider": null, "fallback_from": null, "id_lookup": { "source": "Department of Home Affairs", "checked_at": "2026-09-04T09:12:44Z", "attempts": 1, "max_attempts": 2, "outcome": "match", "comparison": [ { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" }, { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" }, { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" } ], "registry_portrait": "https:///registry_portrait.jpg", "face_match_score": 96.4, "source_errors": [] }, "wallet_verification": null, "warnings": [] }, { "node_id": "feature_ocr_3", "status": "Approved", "issuing_state": "DNK", "issuing_state_name": "Denmark", "first_name": "Freja", "last_name": "Nielsen", "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "verification_method": "wallet", "assurance": "cryptographic", "wallet_provider": "mitid", "fallback_from": null, "id_lookup": null, "wallet_verification": { "provider": "mitid", "provider_name": "MitID", "issuing_authority": "Danish Agency for Digital Government", "issuing_country": "DNK", "credential_type": "person_identification", "level_of_assurance": "substantial", "verified_at": "2026-09-04T09:12:44Z", "signature_valid": true, "attributes": { "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678" }, "portrait": null, "face_match_score": null }, "warnings": [] } ], "nfc_verifications": [ { "node_id": "feature_nfc_1", "status": "In Review", "is_nfc_skipped": false, "skip_reason": null, "chip_protocol": "icao", "jpki": null, "portrait_image": "https:///portrait.jpg", "signature_image": "https:///signature.jpg", "chip_data": { "document_type": "ID", "issuing_country": "ESP", "document_number": "123456789", "expiration_date": "2030-01-01", "first_name": "John", "last_name": "Smith", "birth_date": "1990-05-15", "gender": "M", "nationality": "ESP", "address": "CALLE MAYOR 123 4B, MADRID, MADRID", "place_of_birth": "MADRID, MADRID" }, "authenticity": { "sod_integrity": true, "dg_integrity": true }, "certificate_summary": { "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES", "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES", "serial_number": "118120836164494130086420187336801405660", "not_valid_after": "2031-02-18 10:21:11", "not_valid_before": "2020-11-18 10:21:11" }, "warnings": [ { "feature": "NFC", "risk": "DATA_INCONSISTENT", "additional_data": null, "log_type": "warning", "short_description": "OCR and NFC mrz code extracted are not the same", "long_description": "The Optical Character Recognition (OCR) data and the NFC chip data don't match, indicating potential document tampering or data inconsistency.", "node_id": "feature_nfc_1" } ] } ], "liveness_checks": [ { "node_id": "feature_liveness_1", "status": "Approved", "method": "ACTIVE_3D", "score": 89.92, "reference_image": "https:///reference.jpg", "video_url": "https:///video.mp4", "age_estimation": 24.3, "matches": [ { "session_id": "7d4f1f60-9c2e-4b8a-8f3d-2a1b5c6d7e8f", "session_number": 1234, "vendor_data": "user_ref_001", "verification_date": "2024-06-15T10:30:00Z", "user_details": { "full_name": "John Smith", "document_type": "ID", "document_number": "CLM148418" }, "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null, "source": "session", "match_image_url": "https:///face_match.jpg", "similarity_percentage": 98.5 }, { "session_id": "3e9a7c21-5b48-4f0e-9c6a-8d2f4b1e0a35", "session_number": 1100, "vendor_data": "customer_xyz", "verification_date": "2024-04-10T09:15:00Z", "user_details": { "full_name": "John Smith", "document_type": "P", "document_number": "DZ8375806" }, "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": "PASSIVE_LIVENESS", "source": "session", "match_image_url": "https:///face_match_2.jpg", "similarity_percentage": 95.2 } ], "warnings": [ { "feature": "LIVENESS", "risk": "LOW_LIVENESS_SCORE", "additional_data": null, "log_type": "information", "short_description": "Low liveness score", "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.", "node_id": "feature_liveness_1" } ], "face_quality": null, "face_luminance": null } ], "face_matches": [ { "node_id": "feature_face_match_1", "status": "In Review", "score": 65.43, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///target-image.jpg", "warnings": [ { "feature": "FACEMATCH", "risk": "LOW_FACE_MATCH_SIMILARITY", "additional_data": null, "log_type": "warning", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.", "node_id": "feature_face_match_1" } ] } ], "phone_verifications": [ { "node_id": "feature_phone_1", "status": "Approved", "phone_number_prefix": "+34", "phone_number": "600600600", "full_number": "+34600600600", "country_code": "ES", "country_name": "Spain", "carrier": { "name": "Orange", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "sms", "verification_attempts": 1, "verified_at": "2024-07-28T06:47:35.654321Z", "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-08-24T09:12:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" }, "fee": 0.1 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-08-24T09:12:39.662157+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2025-08-24T09:12:39.684292+00:00", "details": null, "fee": 0 } ], "warnings": [], "matches": [ { "session_id": null, "session_number": null, "vendor_data": null, "verification_date": null, "phone_number": "+34600000000", "status": null, "is_blocklisted": true, "api_service": null, "source": "list_entry" } ] } ], "email_verifications": [ { "node_id": "feature_email_1", "status": "Approved", "email": "test@example.com", "is_breached": true, "breaches": [ { "name": "TAPAirPortugal", "domain": "flytap.com", "logo_path": "https://logos.example.com/TAPAirPortugal.png", "breach_date": "2022-08-25", "description": "In August 2022, the Portuguese airline TAP Air Portugal was the target of a ransomware attack perpetrated by the Ragnar Locker gang who later leaked the compromised data via a public dark web site. Over 5M unique email addresses were exposed alongside other personal data including names, genders, DoBs, phone numbers and physical addresses.", "is_verified": true, "data_classes": [ "dates_of_birth", "email_addresses", "genders", "names", "nationalities", "phone_numbers", "physical_addresses", "salutations", "spoken_languages" ], "breach_emails_count": 6083479 } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2025-09-15T17:36:19.963451Z", "warnings": [ { "feature": "EMAIL", "risk": "BREACHED_EMAIL_DETECTED", "additional_data": null, "log_type": "information", "short_description": "Breached email detected", "long_description": "This email address was found in one or more known data breaches.", "node_id": "feature_email_1" } ], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2025-09-15T17:36:19.792684+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2025-09-15T17:36:19.963427+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_DECLINED", "timestamp": "2025-09-15T17:36:20.081471+00:00", "details": { "reason": "BREACHED_EMAIL_DETECTED" }, "fee": 0 } ], "matches": [ { "session_id": null, "session_number": null, "vendor_data": null, "verification_date": null, "email": "test@example.com", "status": null, "is_blocklisted": true, "api_service": null, "source": "list_entry" } ] } ], "poa_verifications": [ { "node_id": "feature_poa_1", "status": "Declined", "document_file": "https:///poa_document.pdf", "issuing_state": "AR", "document_type": "UTILITY_BILL", "document_subtype": null, "document_language": "es", "document_metadata": { "file_size": 1000, "content_type": "application/pdf", "creation_date": "2021-01-01", "modified_date": "2021-01-01", "overlay_manipulation": null, "creator": null, "producer": "PDF Generator", "software": null, "encryption": null, "is_signed": false, "is_tampered": false, "signature_info": null, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": true }, "issuer": "Aguas del Norte", "issue_date": "2021-02-01", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 3396, SALTA", "poa_formatted_address": "Av. Monseñor Tavella 3396, A4400 Salta, Argentina", "poa_parsed_address": { "address_type": "Avenida", "street_1": "Avenida Monseñor Tavella 3396", "street_2": null, "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208664, "longitude": -65.4131 } }, "name_on_document": "Fernando De Lima", "name_match_score_expected_details": null, "name_match_score_id_verification": 38.5, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": {}, "extra_fields": { "bank_account_number": "1234567890", "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": "+5491112345678", "additional_names": [] }, "extra_files": [ "https:///extra_poa.pdf" ], "detected_codes": [ { "type": "QR_CODE", "page_number": 1, "position": [ [ 820, 1120 ], [ 1002, 1120 ], [ 1002, 1302 ], [ 820, 1302 ] ], "x": 820, "y": 1120, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==", "parsed_payload": "https://aguasdelnorte.com/factura/998811" }, { "type": "CODE_128", "page_number": 1, "position": [ [ 112, 1480 ], [ 560, 1480 ], [ 560, 1540 ], [ 112, 1540 ] ], "x": 112, "y": 1480, "width": 448, "height": 60, "page_width": 1190, "page_height": 1684, "raw_payload": "MDA5OTg4MTEwMDA0Mg==", "parsed_payload": "0099881100042" } ], "warnings": [] } ], "document_ai_documents": [ { "status": "Approved", "node_id": "feature_document_ai_1", "items": [ { "uuid": "c1a2b3c4-d5e6-7f80-9a1b-2c3d4e5f6071", "node_id": "feature_document_ai_1", "document_key": "proof_of_funds", "original_filename": "bank_statement.pdf", "file_size": 184320, "file_url": "https:///document_ai/proof_of_funds.pdf", "status": "Approved", "extracted_data": { "account_holder": "John Doe", "balance": 15230.55, "currency": "EUR", "statement_date": "2026-05-31" }, "detected_codes": [ { "type": "QR_CODE", "page_number": 2, "position": [ [ 124, 86 ], [ 306, 86 ], [ 306, 268 ], [ 124, 268 ] ], "x": 124, "y": 86, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "SU5WLTIwMjYtMDA0Mg==", "parsed_payload": "INV-2026-0042" } ], "fields": [ { "key": "account_holder", "name": "Account holder", "instruction": "Extract the full name of the account holder.", "type": "text", "required": true }, { "key": "balance", "name": "Closing balance", "instruction": "Extract the closing balance amount.", "type": "number", "required": true } ], "document_metadata": { "is_tampered": false }, "cross_check_result": null, "created_at": "2026-06-01T12:34:56Z" } ], "warnings": [] } ], "questionnaire_responses": [ { "node_id": "feature_questionnaire_1", "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213", "title": "Source of Funds", "description": "Reply to this questionnaire to help us understand the source of funds.", "languages": [ "en" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60", "version": 1, "published_at": "2025-11-02T09:14:55.000000Z", "sections": [ { "title": null, "description": null, "items": [ { "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db", "value": "question_1", "element_type": "DROPDOWN", "is_required": true, "title": "What is your primary source of funds?", "description": null, "placeholder": null, "choices": [ { "label": "Salary", "value": "salary" }, { "label": "Business Income", "value": "business_income" }, { "label": "Savings", "value": "savings" }, { "label": "Investments", "value": "investments" }, { "label": "Sale of Asset", "value": "sale_of_asset" }, { "label": "Inheritance/Gift", "value": "inheritance_gift" }, { "label": "Pension", "value": "pension" }, { "label": "Crypto Proceeds", "value": "crypto_proceeds" }, { "label": "Other", "value": "other", "requires_text_input": true } ], "max_files": 1, "answer": { "value": "salary" }, "required_if": null, "repeatable_config": null }, { "uuid": "2d16b527-72be-42e0-8e96-b164b818386c", "value": "question_2", "element_type": "LONG_TEXT", "is_required": true, "title": "Provide details of the primary source.", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null }, { "uuid": "a9239b7c-fbfb-4ea7-b7e4-c835cd4016e0", "value": "question_3", "element_type": "DROPDOWN", "is_required": true, "title": "What is your annual income range (pre-tax)?", "description": null, "placeholder": null, "choices": [ { "label": "Less than $25,000", "value": "<25k" }, { "label": "$25,000 - $50,000", "value": "25k-50k" }, { "label": "$50,001 - $100,000", "value": "50k-100k" }, { "label": "$100,001 - $250,000", "value": "100k-250k" }, { "label": "More than $250,000", "value": ">250k" } ], "max_files": 1, "answer": { "value": "<25k" }, "required_if": null, "repeatable_config": null }, { "uuid": "93dede62-6d0c-4a7f-934d-42175eb94011", "value": "question_4", "element_type": "DROPDOWN", "is_required": true, "title": "What is your approximate net worth (range)?", "description": null, "placeholder": null, "choices": [ { "label": "Less than $50,000", "value": "<50k" }, { "label": "$50,000 - $250,000", "value": "50k-250k" }, { "label": "$250,001 - $1,000,000", "value": "250k-1m" }, { "label": "$1,000,001 - $5,000,000", "value": "1m-5m" }, { "label": "More than $5,000,000", "value": ">5m" } ], "max_files": 1, "answer": { "value": "<50k" }, "required_if": null, "repeatable_config": null }, { "uuid": "2af60d6f-6961-4692-9ee7-24b3033610a6", "value": "question_5", "element_type": "LONG_TEXT", "is_required": true, "title": "For your initial deposit/funding, indicate the exact source and amount.", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null }, { "uuid": "0ad9d1aa-736f-46cf-947b-9e1241b53e40", "value": "question_6", "element_type": "LONG_TEXT", "is_required": true, "title": "Breakdown of sources by percentage.", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null }, { "uuid": "1bf8a2a3-14ee-48a8-bb3d-175481aae4aa", "value": "question_7", "element_type": "SINGLE_CHOICE", "is_required": true, "title": "Will any funds originate from third parties? If yes, please provide details.", "description": null, "placeholder": null, "choices": [ { "label": "Yes", "value": "yes", "requires_text_input": true }, { "label": "No", "value": "no" } ], "max_files": 1, "answer": { "text": "Additional details", "value": "yes" }, "required_if": null, "repeatable_config": null }, { "uuid": "e18d4dd3-b7bf-4883-ba18-d6046adbe313", "value": "question_8", "element_type": "SINGLE_CHOICE", "is_required": true, "title": "Do you hold or plan to use virtual assets (e.g., crypto) to fund this account? If yes, please provide details.", "description": null, "placeholder": null, "choices": [ { "label": "Yes", "value": "yes", "requires_text_input": true }, { "label": "No", "value": "no" } ], "max_files": 1, "answer": { "text": "Additional details", "value": "yes" }, "required_if": null, "repeatable_config": null }, { "uuid": "a90a073d-e098-404c-bbce-5130d8b12a13", "value": "question_9", "element_type": "FILE_UPLOAD", "is_required": true, "title": "Upload a proof of funds document", "description": "You can upload your three (3) most recent bank statements, three (3) most recent payslips, your most recent tax return, proof of company ownership, trading exchange statement, sale of property, or proof of inheritance.", "placeholder": null, "choices": null, "max_files": 3, "answer": { "files": [ "/media/ocr/", "/media/ocr/" ] }, "required_if": null, "repeatable_config": null }, { "uuid": "9503b486-7cb8-4c3b-a97d-4b64926a5a47", "value": "question_10", "element_type": "LONG_TEXT", "is_required": false, "title": "Would you like to add any details to help us expedite our review of the documents you submitted?", "description": null, "placeholder": null, "choices": null, "max_files": 1, "answer": { "value": "Test answer" }, "required_if": null, "repeatable_config": null } ] } ], "status": "Approved" } ], "aml_screenings": [ { "node_id": "feature_aml_1", "status": "In Review", "total_hits": 1, "entity_type": "person", "hits": [ { "id": "hit_7c1e9a40b2d35f86e0a4c912", "url": "https://news.example.org/articles/sample", "match": false, "score": 0.73, "target": null, "caption": "Javier Ejemplo Modelo", "datasets": [ "PEP" ], "features": null, "rca_name": "", "last_seen": "2025-06-13T00:00:00", "risk_view": { "crimes": { "score": 0, "weightage": 20, "risk_level": "Low", "risk_scores": {} }, "countries": { "score": 0, "weightage": 30, "risk_level": "Low", "risk_scores": {} }, "categories": { "score": 100, "weightage": 50, "risk_level": "High", "risk_scores": { "PEP": 100 } }, "custom_list": {} }, "first_seen": "2025-01-18T00:00:00", "properties": { "name": [ "Javier Ejemplo Modelo" ], "alias": [ "Javier Ejemplo Modelo", "David Azagra" ], "notes": [ "Spanish orchestra conductor" ], "title": null, "gender": [ "male" ], "height": null, "topics": null, "weight": null, "address": null, "country": null, "website": null, "eyeColor": null, "keywords": null, "lastName": [ "Ejemplo", "Modelo" ], "position": null, "religion": null, "birthDate": [ "1974" ], "education": [ "Tokyo Arts and Space (2012-2012)", "Saint Petersburg Conservatory (-2010)", "Comillas Pontifical University" ], "ethnicity": null, "firstName": [ "David" ], "hairColor": null, "weakAlias": null, "birthPlace": [ "Madrid" ], "modifiedAt": null, "wikidataId": null, "citizenship": null, "nationality": null }, "match_score": 98, "risk_score": 73, "review_status": "Unreviewed", "score_breakdown": { "name_score": 95, "name_weight": 60, "name_weight_normalized": 70.59, "name_contribution": 67.06, "dob_score": 100, "dob_weight": 25, "dob_weight_normalized": 29.41, "dob_contribution": 29.41, "country_score": 0, "country_weight": 15, "country_weight_normalized": 0, "country_contribution": 0, "document_number_match_type": "NEUTRAL", "document_number_effect": "No document number provided for screening", "total_score": 98 }, "pep_matches": [ { "aliases": [ "Javier Ejemplo Modelo", "David Azagra" ], "education": [ "Tokyo Arts and Space (2012-2012)", "Saint Petersburg Conservatory (-2010)", "Comillas Pontifical University" ], "list_name": "Wikidata", "publisher": "Wikidata", "source_url": "https://news.example.org/articles/sample", "description": "Wikidata is the structured data project of the Wikipedia community, providing fact-based information edited by humans and machines", "matched_name": "Javier Ejemplo Modelo", "pep_position": "", "date_of_birth": "1974", "other_sources": [], "place_of_birth": "Madrid" } ], "linked_entities": [ { "name": [ "Antonio Ejemplo" ], "active": [], "status": [], "details": [], "relation": [] } ], "warning_matches": [], "sanction_matches": [], "adverse_media_details": { "sentiment": "Moderately Negative", "entity_type": "person", "sentiment_score": -2, "adverse_keywords": { "fraud": 3, "juicio": 1, "delitos": 2, "imputado": 1, "impunidad": 1, "corruption": 2, "favoritism": 2, "privilegio": 1, "corrupción": 1, "persecution": 2, "desconfianza": 1, "desprestigio": 1, "fraude de ley": 2, "manipulación": 1, "investigación": 3, "prevaricación": 8, "trato de favor": 1, "irregularidades": 2, "crisis de confianza": 1, "tráfico de influencias": 8 } }, "adverse_media_matches": [ { "country": "spain", "summary": "Javier Ejemplo is implicated in legal violations related to favoritism and influence trafficking, leading to a negative portrayal in the article.", "headline": "La Diputación de Villaejemplo consolida la plaza a medida para el ex asesor de Moncloa amigo del \"hermanito\" de Ejemplo", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "fraud", "prevaricación", "tráfico de influencias", "irregularidades", "imputado" ], "sentiment_score": -2, "publication_date": "2025-06-10T20:46:38" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in legal issues regarding favoritism and corruption, leading to a negative portrayal in the article.", "headline": "La Diputación de Villaejemplo consolida la plaza a medida para el ex asesor de Moncloa amigo del \"hermanito\" de Ejemplo", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "fraud", "prevaricación", "tráfico de influencias", "irregularidades", "trato de favor" ], "sentiment_score": -2, "publication_date": "2025-06-10T20:46:38" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is mentioned in connection with Carlos Ficticio's corruption case, indicating his involvement in alleged influence peddling.", "headline": "España, paraíso del aforado", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "corrupción", "impunidad", "privilegio", "desconfianza", "manipulación", "fraude de ley" ], "sentiment_score": -2, "publication_date": "2025-06-10T05:05:34" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is implicated in the same investigation as Ficticio, which raises questions about his conduct and political ethics.", "headline": "Aforamientos: esa figura incómoda", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "investigación", "juicio", "fraude de ley", "desprestigio", "crisis de confianza", "delitos" ], "sentiment_score": -2, "publication_date": "2025-06-08T06:01:00" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in a legal investigation regarding irregularities in his hiring, which raises serious concerns about his conduct.", "headline": "La jueza del 'caso Javier Ejemplo' denuncia un «fraude de ley» en el aforamiento de Ficticio (Partido Ejemplo)", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "fraud", "irregularities", "prevaricación", "tráfico de influencias" ], "sentiment_score": -2, "publication_date": "2025-06-09T10:19:10" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is mentioned in connection with legal allegations of corruption, contributing to a negative perception.", "headline": "'Caso aforamiento': la letrada mayor de la Asamblea certifica a la juez que Ficticio es diputado desde antes de prometer su cargo en el Pleno", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias" ], "sentiment_score": -2, "publication_date": "2025-06-09T08:08:30" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is implicated in the same investigation as Ficticio, raising concerns about political corruption and influence.", "headline": "Aforamientos: esa figura incómoda", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "investigación" ], "sentiment_score": -2, "publication_date": "2025-06-08T06:01:00" }, { "country": "spain", "summary": "Javier Ejemplo Modelo is implicated in the same investigation as Ficticio, which raises concerns about political misconduct.", "headline": "Aforamientos: esa figura incómoda", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "prevaricación", "tráfico de influencias", "investigación", "delitos" ], "sentiment_score": -2, "publication_date": "2025-06-08T06:00:59" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in a case of favoritism and corruption, which casts a negative light on his character and actions.", "headline": "'Caso Javier Ejemplo': las asociaciones judiciales salen en defensa de la juez Luisa Inventada ante las \"presiones externas\" que sufre", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "favoritism", "corruption", "persecution" ], "sentiment_score": -2, "publication_date": "2025-06-06T10:08:15" }, { "country": "spain", "summary": "Javier Ejemplo is implicated in a case of alleged favoritism and corruption, which casts a negative light on his character and actions.", "headline": "'Caso Javier Ejemplo': las asociaciones judiciales salen en defensa de la juez Luisa Inventada ante las \"presiones externas\" que sufre", "sentiment": "moderately negative", "thumbnail": "https://news.example.org/articles/sample", "source_url": "https://news.example.org/articles/sample", "author_name": null, "other_sources": [], "adverse_keywords": [ "favoritism", "corruption", "persecution" ], "sentiment_score": -2, "publication_date": "2025-06-06T08:08:15" } ], "additional_information": {} } ], "score": 80, "screened_data": { "full_name": "Javier Ejemplo Modelo", "nationality": "ES", "date_of_birth": "1974-01-01", "document_number": null }, "is_ongoing_monitoring_enabled": true, "next_ongoing_monitoring_bill_date": "2026-07-24", "last_ongoing_screening_at": "2026-09-12T04:03:11Z", "last_ongoing_screening_datasets_updated_at": "2026-09-11T06:00:00Z", "warnings": [ { "feature": "AML", "risk": "POSSIBLE_MATCH_FOUND", "additional_data": null, "log_type": "warning", "short_description": "Possible match found in AML screening", "long_description": "The Anti-Money Laundering (AML) screening process identified potential matches with watchlists or high-risk databases, requiring further review.", "node_id": "feature_aml_1" } ] } ], "ip_analyses": [ { "node_id": "feature_ip_1", "status": "Approved", "device_brand": "Apple", "device_model": "iPhone", "browser_family": "Mobile Safari", "os_family": "iOS", "platform": "mobile", "device_fingerprint": "didit-fp-a1b2c3d4e5f6g7h8", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Barcelona", "ip_city": "Barcelona", "latitude": 41.4022, "longitude": 2.1407, "ip_address": "83.50.226.71", "isp": null, "organization": null, "is_vpn_or_tor": false, "is_data_center": false, "time_zone": "Europe/Madrid", "time_zone_offset": "+0100", "ip": { "location": { "latitude": 40.2206327, "longitude": 1.5770097 }, "distance_from_id_document": 23.4, "distance_from_poa_document": 12.3 }, "id_document": { "location": { "latitude": 41.2706327, "longitude": 1.9770097 }, "distance_from_ip": 23.4, "distance_from_poa_document": 18.7 }, "poa_document": { "location": { "latitude": 41.2706327, "longitude": 1.9770097 }, "distance_from_ip": 12.3, "distance_from_id_document": 18.7 }, "warnings": [], "matches": [ { "session_id": "99999999-8888-7777-6666-555555555555", "session_number": 41205, "vendor_data": "22222222-2222-2222-2222-222222222222", "verification_date": "2024-07-20T10:15:30Z", "match_type": "ip_address", "match_source": "ip_address", "matched_value": "83.50.226.71", "status": "Approved", "is_blocklisted": false, "api_service": null, "source": "session", "device_info": { "device_brand": "Apple", "device_model": "iPhone", "browser_family": "Mobile Safari", "os_family": "iOS", "platform": "mobile", "device_fingerprint": "didit-fp-f9e8d7c6b5a40312" }, "location_info": { "ip_address": "83.50.226.71", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Barcelona", "ip_city": "Barcelona", "is_vpn_or_tor": false, "is_data_center": false }, "confidence": 0.0, "match_mode": "co_occurrence" }, { "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "session_number": 42830, "vendor_data": "33333333-3333-3333-3333-333333333333", "verification_date": "2024-06-30T18:22:05Z", "match_type": "device_fingerprint", "match_source": "recovered_high", "matched_value": "f47ac10b-58cc-4372-a567-0e02b2c3d479", "status": "Declined", "is_blocklisted": false, "api_service": null, "source": "session", "device_info": { "device_brand": "Samsung", "device_model": "SM-G991B", "browser_family": "Chrome Mobile", "os_family": "Android", "platform": "mobile", "device_fingerprint": null }, "location_info": { "ip_address": "83.50.231.18", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Madrid", "ip_city": "Madrid", "is_vpn_or_tor": false, "is_data_center": false }, "confidence": 1.0, "match_mode": "deterministic", "recovery_similarity": 0.9874, "tls_ja4_corroborated": true, "recovery_gate_reason": "hardware_root_match" } ] } ], "database_validations": [ { "node_id": "feature_db_validation_1", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "last_name": "De Lima", "first_name": "Fernando", "tax_number": "01234567890", "date_of_birth": "1980-01-01", "document_type": "ID", "expiration_date": "2030-01-01" }, "validations": [ { "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "outcome_code": "MATCH", "validation": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "source_data": { "identification_number": "01234567890", "first_name": "FERNANDO", "last_name": "DE LIMA", "date_of_birth": "1980-01-01", "gender": "M", "nationality": "BRA" } } ], "match_type": "full_match", "status": "Approved", "warnings": [] } ], "reviews": [ { "user": "compliance@example.com", "new_status": "Declined", "comment": "Possible match found in AML screening", "created_at": "2024-07-18T13:29:00.366811Z" } ], "created_at": "2024-07-24T08:54:25.443172Z", "expires_at": "2025-07-24T08:54:25.443172Z", "biometric_consent": { "required": false, "trigger": null, "status": "not_required", "given_at": null, "declined_at": null, "text_version": null, "text_hash": null, "locale": null, "policy_url": null, "step": null, "node_id": null, "ip_address": null, "ip_country_code": null, "ip_state": null, "ip_city": null, "user_agent": null, "detected_ip_address": "83.50.226.71", "detected_country_code": "ES", "detected_state": "ES-B", "detected_city": "Barcelona", "declared_state": null, "document_state": null, "jurisdictions": [], "retention_months": null, "reason": null, "decline_reason": null, "face_data_deleted_at": null } } }, "BusinessExample": { "summary": "企业验证（KYB）会话示例", "description": "一个 `session_kind = \"business\"` 决策：KYB 会话将 KYC 功能数组替换为 `registry_checks`、`document_verifications` 和 `key_people_checks`，同时共享 `aml_screenings`、`phone_verifications`、`email_verifications`、`questionnaire_responses`、`ip_analyses`、`reviews` 以及会话外层结构。", "value": { "session_id": "66666666-7777-8888-9999-000000000000", "session_kind": "business", "session_number": 31415, "session_url": "https://verify.didit.me/session/business123", "status": "In Review", "environment": "live", "workflow_id": "abababab-cdcd-efef-0101-232323232323", "features": [ "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE" ], "vendor_data": "merchant-001234", "metadata": null, "callback": "https://example.com/verification/callback", "registry_checks": [ { "status": "Approved", "node_id": "feature_kyb_registry_1", "data_resolved": true, "company": { "uuid": "dddd4444-eeee-5555-ffff-666677778888", "node_id": "feature_kyb_registry_1", "status": "Approved", "registry_status": "active", "data_resolved": true, "company_name": "ACME HOLDINGS LTD", "registration_number": "12345678", "country_code": "GB", "region": null, "company_type": "Private Limited Company", "incorporation_date": "2015-03-12", "registered_address": "1 Example Street, London, EC1A 1AA", "tax_number": null, "risk_level": null, "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": null, "nature_of_business": "62012 - Business and domestic software development", "registered_capital": "100 GBP", "registered_capital_amount": "100.00", "registered_capital_currency": "GBP", "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": "England and Wales", "financial_summary": null, "officers": [ { "uuid": "aaaa1111-bbbb-2222-cccc-333344445555", "name": "Jane Smith", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/session/abc123def456" } ], "beneficial_owners": [ { "uuid": "bbbb2222-cccc-3333-dddd-444455556666", "name": "John Doe", "first_name": "John", "last_name": "Doe", "entity_type": "person", "roles": [ "ubo", "shareholder" ], "ownership_min_shares": "50", "ownership_max_shares": "75", "is_active": true, "kyc_status": "Pending", "kyc_session_url": "https://verify.didit.me/session/def456ghi789", "effective_ownership_percent": 75.0 } ], "addresses": [ { "type": "registered", "address": "1 Example Street, London, EC1A 1AA", "country": "GB" } ], "industries": [ { "code": "62012", "description": "Business and domestic software development" } ], "accounts": null, "registry_data": {}, "user_provided_data": { "company_name": "ACME HOLDINGS", "registration_number": "12345678" }, "confirmed_by_user_at": "2026-06-10T12:01:30.000000Z", "last_console_edit_at": null, "is_editable": false }, "ownership_structure": { "shareholders": [ { "name": "John Doe", "first_name": "John", "last_name": "Doe", "date_of_birth": null, "country_of_birth": null, "company_name": null, "registration_number": null, "entity_type": "person", "nationality": null, "designation": null, "roles": [ "shareholder" ], "ownership_min_shares": "75", "ownership_max_shares": "75", "voting_min_shares": null, "voting_max_shares": null, "appointment_date": null, "is_active": true, "shareholding": { "share_class": "ORDINARY", "number_of_shares": 750.0, "currency": "GBP", "nominal_value": 1.0, "total_value": null, "percentage": 75.0 } } ], "beneficial_owners": [] }, "warnings": [] } ], "aml_screenings": null, "document_verifications": [ { "status": "In Review", "node_id": "feature_kyb_documents_1", "items": [ { "uuid": "eeee5555-ffff-6666-0000-777788889999", "document_type": "LEGAL_PRESENCE", "document_subtype": "CERTIFICATE_OF_INCORPORATION", "document_group": "LEGAL_PRESENCE", "file_url": "https:///kyb/certificate-of-incorporation.pdf", "original_filename": "certificate_of_incorporation.pdf", "file_size": 482133, "status": "Approved", "created_at": "2026-06-10T12:03:11.000000Z", "cross_check_result": { "critical": { "company_name": { "document": "ACME HOLDINGS LTD", "registry": "ACME HOLDINGS LTD", "score": 1.0, "match": true }, "registration_number": { "document": "12345678", "registry": "12345678", "match": true } }, "non_critical": {}, "people": {} }, "document_metadata": { "file_size": 482133, "content_type": "application/pdf", "creation_date": "2015-03-12T09:00:00", "modified_date": "2015-03-12T09:00:00", "creator": null, "producer": null, "software": null, "encryption": null, "is_signed": true, "is_tampered": false, "signature_info": null, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": false, "overlay_manipulation": null }, "description": null, "is_requested": false, "ocr_data": { "company_name": "ACME HOLDINGS LTD", "registration_number": "12345678", "incorporation_date": "2015-03-12" }, "is_console_upload": false, "is_confirmed": true }, { "uuid": "ffff6666-0000-7777-1111-888899990000", "document_type": "OWNERSHIP_STRUCTURE", "document_subtype": null, "document_group": "OWNERSHIP_STRUCTURE", "file_url": null, "original_filename": null, "file_size": null, "status": "Not Finished", "created_at": "2026-06-10T15:40:02.000000Z", "cross_check_result": null, "document_metadata": null, "description": "Please upload an up-to-date shareholder registry", "is_requested": true, "ocr_data": null, "is_console_upload": false, "is_confirmed": true } ], "groups": { "LEGAL_PRESENCE": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }, "OWNERSHIP_STRUCTURE": { "total": 1, "approved": 0, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 1 } }, "required_groups": [ "LEGAL_PRESENCE", "OWNERSHIP_STRUCTURE" ], "warnings": [] } ], "key_people_checks": [ { "status": "In Review", "node_id": "feature_kyb_key_people_1", "registry": { "officers": [ { "uuid": "aaaa1111-bbbb-2222-cccc-333344445555", "name": "Jane Smith", "designation": "Director", "role": "director", "nationality": "British", "appointment_date": "2015-03-12", "termination_date": null, "is_active": true, "address": "1 Example Street, London, EC1A 1AA", "aml_status": "Approved", "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/session/abc123def456", "kyc_session_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb", "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "didit_internal_id": "99999999-0000-1111-2222-333333333333", "kyc_document_type": "P", "kyc_nationality": "GBR", "kyc_liveness_passed": true, "kyc_verified_at": "2026-06-10T14:22:31.123456Z", "kyc_aml_categories": { "sanctions": "clear", "pep": "clear", "adverse_media": "clear", "warnings": "clear" }, "kyc_notification_sent_at": "2026-06-09T09:00:00.000000Z" } ], "beneficial_owners": [ { "uuid": "bbbb2222-cccc-3333-dddd-444455556666", "name": "John Doe", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-05-04", "country_of_birth": null, "email": null, "company_name": null, "registration_number": null, "entity_type": "person", "nationality": "British", "designation": null, "roles": [ "ubo", "shareholder" ], "ownership_min_shares": "50", "ownership_max_shares": "75", "is_active": true, "aml_status": null, "kyc_status": "In Progress", "kyc_session_url": "https://verify.didit.me/session/def456ghi789", "kyc_session_id": "88888888-9999-aaaa-bbbb-cccccccccccc", "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" } ], "didit_internal_id": null, "kyc_document_type": null, "kyc_nationality": null, "kyc_liveness_passed": null, "kyc_verified_at": null, "kyc_aml_categories": null, "kyc_notification_sent_at": null, "child_beneficial_owners": [], "effective_ownership_percent": 75.0 } ] }, "submitted": { "parties": [ { "uuid": "cccc3333-dddd-4444-eeee-555566667777", "entity_type": "person", "source": "USER", "name": "John Doe", "first_name": "John", "last_name": "Doe", "company_name": null, "registration_number": null, "email": "john.doe@example.com", "nationality": "GBR", "phone_number": "+447700900123", "date_of_birth": "1980-05-04", "position": "Chief Executive Officer", "custom_fields": {}, "is_active": true, "is_skipped": false, "requires_verification": true, "roles": [ { "role": "ubo", "ownership_percent": 75.0, "voting_percent": 75.0 }, { "role": "director", "ownership_percent": null, "voting_percent": null } ], "kyc_session_id": "88888888-9999-aaaa-bbbb-cccccccccccc", "kyc_session_status": "In Progress", "kyc_session_url": "https://verify.didit.me/session/def456ghi789", "kyb_sub_session_id": null, "kyb_sub_session_status": null, "kyb_sub_session_url": null, "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" } ], "didit_internal_id": null } ] }, "ubo_kyc_summary": { "total": 1, "approved": 0, "flagged": 0, "pending": 1 }, "warnings": [] } ], "phone_verifications": null, "email_verifications": null, "questionnaire_responses": null, "ip_analyses": null, "reviews": [], "contact_details": null, "expected_details": { "company_name": "Tesco PLC", "registry_country": "GB", "registration_number": "00445790" }, "created_at": "2026-06-10T11:58:04.000000Z", "expires_at": "2026-06-24T11:58:04.000000Z" } } }, "schema": { "$ref": "#/components/schemas/SessionDecision" } } } }, "403": { "description": "认证或授权失败。缺少密钥返回 `403`；密钥错误、被撤销或已过期返回 `401`。两个 `detail` 字符串区分失败模式：\n\n- `\"Authentication credentials were not provided or are invalid.\"` — 缺少 `x-api-key` 请求头（且缺少 `Authorization: Bearer` token），或者提供的凭据内省失败（已撤销、已过期或格式错误）。\n- `\"You do not have permission to perform this action.\"` — 凭据有效但无权读取此会话：控制台用户的 Bearer token 缺少 `read:sessions` 权限或无法访问所属应用，或者 API 密钥属于与会话不同的组织。\n\n请注意，对于完全未知的 `sessionId`，endpoint 会在验证凭据之前解析所属应用，因此即使凭据缺失或无效，不存在的会话也会返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Authentication credentials were not provided or are invalid." } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥自省失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Insufficient permissions": { "summary": "凭证有效，但缺少 read:sessions 权限或无法访问所属应用", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未找到会话。当所提供的 `sessionId` 无法作为用户验证（KYC）或企业验证（KYB）会话与任何有效会话匹配时返回（已被删除的会话也会产生此结果）。响应体为标准 `{\"detail\": ...}` 封装。\n\n**两种不同的 `detail` 字符串。** 如果 `sessionId` 在 KYC 和 KYB 会话中均未知，则预认证所有者查找失败，您将收到 `{\"detail\": \"Not found.\"}`；这发生在凭据验证之前，因此即使对于未经身份验证的调用也会返回。如果会话存在但无法在经过身份验证的应用下检索（例如陈旧或刚刚删除的记录），则视图返回 `{\"detail\": \"Session not found.\"}`。两者都表示相同的结果（即会话无法访问），因此请匹配 `404` 状态码，而非匹配字符串。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Not found." } } }, "examples": { "Unknown session id": { "summary": "此应用无法识别该 sessionId", "value": { "detail": "Not found." } }, "Session not retrievable": { "summary": "会话存在，但此应用无法检索", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "超出速率限制。GET 请求限制为**每个凭证每分钟 600 次**（API 密钥、Bearer token，或未认证时的源 IP）。请检查 `Retry-After` / `X-RateLimit-Reset` 并在重试前进行退避等待。如果您在轮询决策时触发了此限制，请切换至 `status.updated` Webhook，改为在每次状态变更时获取一次决策。", "headers": { "Retry-After": { "description": "重试请求前需等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "当前时间窗口内允许的最大请求数（GET 请求为 600）。", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间戳（秒）。", "schema": { "type": "integer", "example": 1750000000 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "超出速率限制的便于人类阅读的说明。", "example": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } }, "examples": { "Throttled": { "summary": "同一凭证在一分钟内的 GET 请求超过 600 次", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "您想要检索其决策的验证会话的 UUID。这是由 `POST /v3/session/` 返回的 `session_id`。同一路径对用户验证（KYC）和企业验证（KYB）会话均有效，服务器会针对两种会话类型解析该 id。\n\n**必须是有效的 UUID。** 该路由仅匹配格式正确的 UUID，因此格式错误的值在任何应用代码运行之前就会被 URL 路由器拒绝，并且响应将是 `404` **HTML** 页面，而不是如下所示的 JSON `{\"detail\": ...}` 封装。请在客户端验证 UUID 格式，以便区分输入错误与真正的会话缺失导致的 `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "include", "in": "query", "required": false, "description": "以逗号分隔的附加 payload 部分列表。支持的值：`events` 和 `resubmissions`，可单独使用或组合使用（`events,resubmissions`）。传入 `include=events` 时，响应还会包含会话事件时间线（`events`，包括获取会话页面中描述的 `WORKFLOW_BRANCH_EVALUATED` / `WORKFLOW_STATUS_NODE_REACHED` 路由事件）、完整活动日志（`activity_reviews`）、黑名单标记（`blocklisted`）、每次会话的 `cost_breakdown`、工作流元数据（`workflow_type`、`workflow_version`、`workflow_version_id` 以及 `workflow_terminal_node_id`：设置会话状态的最后记录工作流状态节点，若未记录则为 `null`；该历史溯源信息不会被人工审核通过、拒绝或重新提交清除，并会被后续的工作流状态节点替换），以及会话元数据（`api_service`：字符串或 `null`，仅针对独立 API 会话设置；`session_type`：`API`、`HOSTED` 或 `MIGRATED`；`has_device_nfc_support`：布尔值）。与普通结构相比，有两个字段发生了变化：顶层的 `session_kind` 鉴别器被**省略**（事件结构仅存在于用户会话中），且 `features` 数组从纯字符串切换为 `{feature, node_id}` 对象，其中邮箱功能报告为 `EMAIL` 而不是 `EMAIL_VERIFICATION`。此扩展结构主要由 Didit Console 使用；大多数 API 集成应省略该参数。**KYB 限制：**`include=events` 仅适用于用户（KYC）会话。企业会话（`session_kind = \"business\"`）始终返回标准企业决策结构：企业会话绝不会返回 `events`、`activity_reviews`、`blocklisted`、`cost_breakdown` 和额外的 `workflow_*`/会话元数据，且其 `features` 数组保持为纯字符串数组。使用 `include=resubmissions`（用户会话和企业会话均适用）时，响应还会包含 `resubmissions`：每个重新提交请求对应一项，按时间由旧到新排序，每项包含 `number`、`created_at`、`previous_status`、`nodes`、`reasons`、`requested_by` 和 `results`（重新提交的步骤在请求前返回的内容，位于相同键下且具有与当前结果相同的结构）。每个 `cost_breakdown` 项包含 `usage_type`、`price`、`details` 和 `created_at`：再次运行的重新提交步骤将作为新项目计费。", "schema": { "type": "string", "enum": [ "events", "resubmissions", "events,resubmissions" ], "example": "events" } } ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/decision/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Accept: application/json'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.retrieve_decision(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.retrieveDecision(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.RetrieveDecision(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsRetrieveDecisionParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().retrieveDecision(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->retrieveDecision('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.retrieve_decision(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.RetrieveDecisionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/delete/": { "delete": { "summary": "删除验证会话（KYC 或 KYB）", "description": "通过 `session_id` 删除单个验证会话，包括用户验证（KYC）或企业验证（KYB）。系统会先针对 KYC 会话解析该 ID，然后再针对 KYB 会话解析，因此两种类型的会话均可通过这一个 URL 删除。\n\n**删除的内容：**\n- 会话及其包含的每次验证尝试，包括重新提交所替换的结果：决策、提取的数据、所有相关功能记录（身份证件验证、人脸、活体检测、人脸比对、AML、公司登记核验、IP 分析等）、其审核记录以及活动日志。\n- 会话拥有的所有存储文件：证件正/反面照片（完整版、裁剪版和隐私模糊处理版本）、证件采集视频、头像裁剪图、NFC 芯片头像和签名图像、人脸参考图像、活体视频、人脸比对源/目标图像、地址证明文件以及任何额外上传的文件（KYC）；已上传的公司文件和额外文件（KYB）。电子签名文件、已签名的 PDF、证据 PDF 和签名图像（KYC 和 KYB）：其下载路径将停止工作。之前签发的媒体 URL（`https:///...`）将停止解析。\n- 会话的人脸数据。其人脸特征向量也会被删除，除非您选择保留无图像模板（请参阅**人脸生物识别数据**）。\n- 仍在为该会话排队的 Webhook 投递及其重试。已投递的 Webhook 不受影响。\n- 对于企业验证（KYB）会话：其为其关键人员（KYC）和企业所有者（KYB）递归创建的验证，在响应中报告为 `deleted_child_verifications`。它仅关联的验证（例如其复用的现有已通过 KYC）不会被删除。\n\n该会话会立即从所有读取 endpoint 中消失：`GET /v3/session/{sessionId}/decision/` 返回 `404`，且 `GET /v3/sessions/` 不再将其列出。由被删除验证发起的持续 AML 监控和 KYB 公司登记监控将停止。\n\n**不受影响的内容：**从此会话创建的黑名单条目（人脸或证件）**不会**被移除；请使用黑名单 endpoint 管理这些条目。为该会话签发的共享 token 不会被撤销，但已无内容可供其导入：使用此类 token 导入将返回 `400` 以及 `{\"share_token\": [\"Original session does not exist.\"]}`。已消耗的额度**不予**退款。父级用户或企业实体**不会**被删除；如需删除这些实体，请使用 `POST /v3/users/delete/` 或 `POST /v3/businesses/delete/`。如果用户的个人资料头像来自此会话，该头像将随之一并移除。\n\n**人脸生物识别数据：**默认情况下，会话的人脸特征向量会随会话一起删除（`face_retention_outcome: deleted`）。选择保留生物特征模板的应用（在 `PATCH /v3/webhook/` 上设置 `face_retention_policy: retain_until_user_deleted`），或带有 `retain_face_embeddings: true` 的请求，将保留一份单独管理的、不含图像的人脸生物特征模板并锚定到该会话的用户（`retained_with_user`），以便重复项检测、人脸搜索和生物识别认证继续工作。该模板绝不包含人脸图像、媒体、身份字段、决策或已删除会话的 ID；它是生物识别数据，将在 `biometric_template_expires_at` 时删除，或在用户删除、隐私清除或通过 `/v3/biometric-templates/` 显式清除时提前删除。没有关联用户的会话无法保留模板（`ineligible_no_vendor_user`）。对于数据主体请求，请发送 `deletion_instruction: privacy_erasure`：它会清除该用户的所有保留模板，且绝不保留新模板。\n\n**不可逆：**删除是永久性的，没有恢复 endpoint。在调用之前，请导出您需要的任何内容（例如决策 PDF）。\n\n**副作用：**删除操作不会发出 Webhook。\n\n**响应：**删除完成后返回 `200 OK`，JSON 响应体报告 `face_retention_outcome`、保留模板的到期时间以及对于 KYB 会话的 `deleted_child_verifications`。此 endpoint 的早期版本返回 `204 No Content`；请更新断言 `204` 的客户端。请在您自己的清除日志中记录您的 `instruction_id`。\n\n**幂等性：**在 HTTP 级别非幂等：首次调用返回 `200`；重复调用返回 `404`，因为该会话已无法解析。发生 `503` 后，会话仍然存在；重复相同的请求以完成删除。\n\n**认证：**在 `x-api-key` 请求头中发送您的应用的 API 密钥；会话必须属于该应用。当控制台用户访问 token（`Authorization: Bearer ...`）携带 `delete:sessions` 权限时，也可以调用此 endpoint。认证和权限失败均返回 `403`；此 API 绝不返回 `401`。\n\n**速率限制：**所有 POST/PATCH/DELETE endpoint 共享每个 API 密钥 300 次请求/分钟的写入预算；超出将返回 `429`。\n\n如需通过数字 `session_number` 批量删除 KYC 会话，请改用 `POST /v3/sessions/delete/`。\n\n**已提交的监管报告：**如果选定的数据处于已定稿的监管报告中，整个请求将被拒绝并返回 `409`，且不会删除任何内容。响应体使用 `code: in_filed_report` 并列出每份报告的 `uuid`、`report_number`、`report_type` 和 `case_uuid`。删除这些报告，然后重试该请求。", "operationId": "delete_v3_session_by_id", "x-didit-sdk": { "resource": "sessions", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "要删除的用户验证（KYC）或企业验证（KYB）会话的 UUID（`session_id`），即创建会话时返回的值。必须是带连字符的标准规范 UUID — 非 UUID 值与该路由不匹配并返回 `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "responses": { "200": { "description": "会话已删除。响应体报告了该会话人脸生物特征数据的处理结果，对于 KYB 会话，还报告了其创建的验证中有多少个已随之一同删除。", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "已删除的会话。" }, "session_number": { "type": "integer", "nullable": true, "description": "已删除会话的编号。" }, "face_retention_outcome": { "type": "string", "enum": [ "retained_with_user", "deleted", "none", "ineligible_no_vendor_user" ], "description": "会话的人脸生物特征数据的处理结果。`deleted`：人脸特征向量随会话一同被删除（默认）。`retained_with_user`：会话被删除，且一个不含图像的生物特征模板继续锚定到用户；请参阅 `biometric_template_uuid`。`none`：该会话没有人脸特征向量（例如 KYB 会话，或没有活体自拍照的 KYC 会话）。`ineligible_no_vendor_user`：已请求保留，但该会话没有关联的用户，因此人脸特征向量随会话一同被删除。此 endpoint 从不通过该字段报告生物特征库故障：此时会返回 `503` 且会话不会被删除。" }, "biometric_template_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "当 `face_retention_outcome` 为 `retained_with_user` 时保留的生物特征模板 ID；否则为 `null`。可通过 `/v3/biometric-templates/{template_uuid}/` 进行管理。" }, "biometric_template_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "当 `face_retention_outcome` 为 `retained_with_user` 时，保留的生物特征模板被删除的时间；未保留模板时为 `null`。" }, "deleted_child_verifications": { "type": "integer", "description": "对于企业验证（KYB）会话：与其一同删除的、由其创建的验证数量（递归包括其关键人员的 KYC 会话及其企业所有者的 KYB 会话）。对于 KYC 会话始终为 `0`。" } } }, "examples": { "Deleted (default)": { "value": { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1024, "face_retention_outcome": "deleted", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } }, "Retained with User": { "value": { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1024, "face_retention_outcome": "retained_with_user", "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "biometric_template_expires_at": "2027-10-09T10:15:00Z", "deleted_child_verifications": 0 } }, "Ineligible: no User": { "summary": "针对未提供 vendor_data 创建的会话请求了保留", "value": { "session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c", "session_number": 1031, "face_retention_outcome": "ineligible_no_vendor_user", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } }, "KYB session": { "value": { "session_id": "0f3c9b7e-2d1a-4e5f-8c6b-7a9d8e1f2c3b", "session_number": 88, "face_retention_outcome": "none", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 3 }, "summary": "已删除的企业验证及其为关键人员创建的三项验证" } } } } }, "400": { "description": "验证错误 — 未删除任何内容。", "content": { "application/json": { "examples": { "Privacy erasure cannot retain": { "value": { "retain_face_embeddings": [ "Privacy erasure cannot retain biometric templates." ] } }, "No finite retention duration": { "summary": "在请求或应用中未包含 face_retention_days 时请求了保留", "value": { "detail": "A finite biometric-template retention duration is required." } } } } } }, "403": { "description": "身份验证或权限失败。缺少密钥同样会返回 `403`；错误、已撤销或已过期的密钥将返回 `401`。例外情况：当 `sessionId` 无法解析为有效会话时，预认证所有者查找将优先返回 `404`，即使凭证缺失或无效也是如此。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid API key": { "summary": "缺少 x-api-key 请求头，或该密钥无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Insufficient permission": { "summary": "没有 delete:sessions 权限的用户 token，或者不拥有该会话的应用的凭证", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "不存在具有此 `session_id` 的生产环境中的 KYC 或 KYB 会话：该 id 未知或会话已被删除（重复成功的删除操作将进入此状态）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not Found": { "summary": "未知或已删除的会话", "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出共享写入速率限制（每个 API 密钥每分钟 300 次 POST/PATCH/DELETE 请求）。重试前请检查 `Retry-After` 和 `X-RateLimit-*` 响应头。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "写入预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } }, "503": { "description": "由于存储服务、生物特征存储或监控提供商不可用，删除无法完成。会话仍然保留；请重复相同的请求，直到其返回 `200`。其存储的部分文件或其人脸特征向量可能已被删除，因此在收到 `503` 后请勿依赖它们。重试会收敛到单个模板。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Session deletion unavailable": { "summary": "存储服务或监控提供商不可用", "value": { "detail": "The session could not be deleted because a storage service or a monitoring provider is unavailable. The session is still in place; repeat the request to finish deleting it." } }, "Biometric store unavailable": { "summary": "在保留或清除模板时生物特征存储库不可用", "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } }, "409": { "description": "会话属于已定稿的监管报告的一部分。任何内容均未被删除。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl (default policy)", "source": "curl -X DELETE \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "curl", "label": "curl (retain template)", "source": "curl -X DELETE \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"retain_face_embeddings\": true, \"face_retention_days\": 365}'" }, { "lang": "curl", "label": "curl (privacy erasure)", "source": "curl -X DELETE \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"deletion_instruction\": \"privacy_erasure\", \"instruction_id\": \"dsar-2026-0142\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.delete(\n \"11111111-2222-3333-4444-555555555555\",\n retain_face_embeddings=True,\n face_retention_days=365,\n instruction_id=\"post-approval-cleanup-2026-08\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.delete(\"11111111-2222-3333-4444-555555555555\", {\n retain_face_embeddings: true,\n face_retention_days: 365,\n instruction_id: \"post-approval-cleanup-2026-08\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsDeleteParams{\n\tRetainFaceEmbeddings: didit.Bool(true),\n\tFaceRetentionDays: didit.Int(365),\n\tInstructionID: didit.String(\"post-approval-cleanup-2026-08\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().delete(\"11111111-2222-3333-4444-555555555555\", SessionsDeleteParams.builder()\n .retainFaceEmbeddings(true)\n .faceRetentionDays(365L)\n .instructionId(\"post-approval-cleanup-2026-08\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->delete('11111111-2222-3333-4444-555555555555', [\n 'retain_face_embeddings' => true,\n 'face_retention_days' => 365,\n 'instruction_id' => 'post-approval-cleanup-2026-08',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.delete(\n \"11111111-2222-3333-4444-555555555555\",\n retain_face_embeddings: true,\n face_retention_days: 365,\n instruction_id: \"post-approval-cleanup-2026-08\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsDeleteParams\n{\n RetainFaceEmbeddings = true,\n FaceRetentionDays = 365,\n InstructionId = \"post-approval-cleanup-2026-08\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": false, "description": "可选。完全省略请求体，以遵循应用的数据保留策略执行操作性删除。", "content": { "application/json": { "schema": { "type": "object", "properties": { "retain_face_embeddings": { "type": "boolean", "nullable": true, "description": "针对本次删除覆盖应用的 `face_retention_policy`。为 `true` 时，在会话删除后保留一个锚定到该会话用户的无图像人脸生物特征模板；为 `false` 时，随会话一同删除人脸特征向量；省略或设为 `null` 则遵循应用策略。对于 KYB 会话以及无人脸特征向量的会话，此项将被忽略。", "example": true }, "face_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "保留模板的有限保留时长（以天为单位）。除非应用已设置 `face_retention_days`，否则在保留模板时必填。模板的 `expires_at` 为此保留时长、应用的通用数据保留期和 `face_retention_deadline` 中的最早者。", "example": 365 }, "face_retention_deadline": { "type": "string", "format": "date-time", "description": "保留模板的可选硬性到期时间。必须是将来的时间。", "example": "2027-08-28T00:00:00Z" }, "deletion_instruction": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ], "default": "operational_session_delete", "description": "您发出的指令类别。`operational_session_delete` 会删除会话，并且仅在策略或 `retain_face_embeddings` 要求时才保留模板。`privacy_erasure` 会在删除会话之前清除锚定到该会话用户的每个已保留生物特征模板，此操作不能被应用策略覆盖，也不能与 `retain_face_embeddings: true` 组合使用（`400`）。", "example": "operational_session_delete" }, "instruction_id": { "type": "string", "maxLength": 255, "description": "您对该删除指令的持久化参考标识（例如删除工单 ID）。记录在审计追踪记录和任何保留的模板上。省略时由 Didit 自动生成。", "example": "dsar-2026-0142" } } }, "examples": { "Retain a biometric template": { "summary": "删除会话，保留无图像的模板 365 天", "value": { "retain_face_embeddings": true, "face_retention_days": 365, "instruction_id": "post-approval-cleanup-2026-08" } }, "Force deletion on an opted-in application": { "summary": "无论应用策略如何，均删除人脸特征向量", "value": { "retain_face_embeddings": false } }, "Privacy erasure": { "summary": "数据主体请求：删除会话并清除该人员保留的所有模板", "value": { "deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142" } } } } } } } }, "/v3/session/{sessionId}/generate-pdf/": { "get": { "summary": "下载验证会话的 PDF 报告", "description": "为已完成的验证会话渲染并下载合规级 PDF 报告。同一路径同时支持用户验证（KYC）和企业验证（KYB）会话，服务器会针对这两种会话类型解析 `sessionId` 并选择匹配的报告模板。\n\n**符合条件的会话状态。** 会话必须已处于最终状态或可审核状态：\n\n- KYC 会话：`Approved`、`Declined`、`In Review` 或 `Kyc Expired`。\n- KYB 会话：`Approved`、`Declined` 或 `In Review`。\n\n任何其他状态（`Not Started`、`In Progress`、`Expired`、`Abandoned` 等）均会返回 `403` 及解释性 `detail` 字符串，请参见下方的 `403` 响应。\n\n**报告内容。** PDF 反映了发起请求时控制台中的会话视图：\n\n- **KYC**：汇总的会话状态、警告列表以及每个已执行功能对应的独立板块：身份证件验证（证件图像及提取的字段）、NFC 验证、活体检测、人脸比对、邮箱验证、电话验证、地址证明、问卷答案、数据库核验、AML 筛查和 IP 分析，随后是会话标签、控制台审核活动（评论与状态变更）以及会话事件时间线。\n- **KYB**：登记核验（公司数据）、AML 筛查、企业证件验证、关键人员核验、问卷响应、电话/邮箱验证、IP 分析以及会话事件时间线，随后是标签和审核活动。\n\n**品牌定制。** 如果您的应用启用了白标定制，报告将使用您的 Logo 渲染并包含指向您隐私政策 URL 的链接；否则将采用 Didit 品牌标识。报告以英文渲染，不提供语言参数。\n\n**无缓存。** 每次调用都会基于当前的会话数据重新渲染 PDF，因此在人工审核后生成的报告会体现审核员的决策。针对同一会话的两次调用可能会生成字节不完全相同的文件；如果您需要不可变副本，请对下载的文件进行归档。\n\n**延迟。** 渲染过程在排版 PDF 之前需要下载所有已存储的图像（证件正反面、自拍照、额外文件），因此媒体文件较多的会话可能需要几秒钟。建议设置较充裕的客户端读取超时时间（推荐 60 秒）并将响应体流式传输至磁盘。\n\n**末尾斜杠。** 规范路由以斜杠结尾（`…/generate-pdf/`）。不带斜杠的请求将直接处理并返回相同的响应：不存在 `301` 重定向，因此客户端无需跟随重定向，`curl` 也不需要 `-L`。请按照示例使用带斜杠的 URL。\n\n如果您需要基础数据 JSON 而非渲染后的报告，请使用 `GET /v3/session/{sessionId}/decision/`。如果需要将单个用户的所有可报告会话整合到单个文档中，请使用 `GET /v3/users/{vendor_data}/generate-pdf/`。", "operationId": "get_v3_session_generate_pdf", "x-didit-sdk": { "resource": "sessions", "method": "generate_pdf", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "要渲染的用户验证（KYC）或企业验证（KYB）会话的 UUID — 即 `POST /v3/session/` 返回的 `session_id`。同一路径适用于两种会话类型；可通过响应中的 `Content-Disposition` 文件名区分您收到的报告类型。\n\n**必须是格式规范的小写 UUID。** 该路由仅匹配有效 UUID，因此格式错误的值在任何应用代码运行之前就会被 URL 路由器拒绝，且响应为 `404` **HTML** 页面，而不是如下所示的 JSON `{\"detail\": ...}` 信封。路由的 UUID 转换器仅匹配标准规范小写格式 — 大写十六进制 UUID 会被拒绝并返回 HTML 404。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "responses": { "200": { "description": "渲染生成的 PDF 文档，直接以二进制 `application/pdf` 形式返回，没有 JSON 包装，也没有下载 URL 重定向。正文以 `%PDF` 魔数开头（PDF 1.7）。可将其保存为 `.pdf` 文件或直接流式传输给您的调用方。", "headers": { "Content-Disposition": { "description": "KYC 会话为 `attachment; filename=session_{sessionId}.pdf`，KYB 会话为 `attachment; filename=business_{sessionId}.pdf`，前缀指示渲染了哪个报告模板。", "schema": { "type": "string", "example": "attachment; filename=session_11111111-2222-3333-4444-555555555555.pdf" } }, "Content-Length": { "description": "PDF 的总大小（以字节为单位）；正文未分块。", "schema": { "type": "integer", "example": 25191 } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "身份验证、授权或会话状态失败。缺少密钥将返回 `403`；错误、已撤销或已过期的密钥将返回 `401`。可通过 `detail` 字符串区分失败模式：\n\n- `\"Authentication credentials were not provided or are invalid.\"` — 未提供 `x-api-key` 请求头（且未提供 `Authorization: Bearer` token），或者提供的凭证未通过自省（已撤销、已过期或格式错误）。\n- `\"You do not have permission to perform this action.\"` — 凭证有效但无法读取此会话：控制台用户的 Bearer token 缺少 `read:sessions` 权限或无法访问所属应用，或者 API 密钥属于与该会话不同的组织。\n- `\"You can only generate a PDF for sessions in review, declined, approved or kyc expired\"` — KYC 会话存在但尚未处于符合条件的状态（例如 `Not Started` 或 `In Progress`）。在请求报告前请等待 `status.updated` Webhook。\n- `\"You can only generate a PDF for sessions in review, declined or approved\"` — KYB 会话的相同条件。\n\n请注意，对于完全未知的 `sessionId`，endpoint 会在验证凭证之前先解析所属应用，因此如果会话不存在，即使凭证缺失或无效，也会返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You can only generate a PDF for sessions in review, declined, approved or kyc expired" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥自省失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Insufficient permissions": { "summary": "凭证有效，但缺少 read:sessions 权限或无法访问所属应用", "value": { "detail": "You do not have permission to perform this action." } }, "KYC session not finished": { "summary": "KYC 会话仍处于未开始/进行中状态", "value": { "detail": "You can only generate a PDF for sessions in review, declined, approved or kyc expired" } }, "KYB session not finished": { "summary": "KYB 会话仍处于未开始/进行中状态", "value": { "detail": "You can only generate a PDF for sessions in review, declined or approved" } } } } } }, "404": { "description": "不存在具有此 `sessionId` 的活跃会话：从未创建，或已被删除。所有者解析发生在凭证验证之前，因此即使是未通过身份验证的请求也会返回此 `404`。根据具体未匹配到的查询，`detail` 字符串为 `\"Not found.\"`（常见情况）或 `\"Session not found.\"`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Not found." } } }, "examples": { "Unknown session": { "summary": "sessionId 与任何 KYC 或 KYB 会话均不匹配", "value": { "detail": "Not found." } }, "Recently deleted session": { "summary": "在两次查找之间会话已被删除", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "超出速率限制。除全局 600 次/分钟的 GET 限制外，PDF 生成还具有**每个凭证每分钟 50 次请求**的专属限制（API 密钥、Bearer token，或未认证时的源 IP）。请等待 `Retry-After` 秒（也会反映在 `X-RateLimit-*` 响应头中），然后重试。报告不会在服务端缓存，因此请下载每份报告一次并保存文件，而不是重复获取。", "headers": { "Retry-After": { "description": "重试请求前需等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "当前时间窗口内允许的最大 PDF 生成次数（50）。", "schema": { "type": "integer", "example": 50 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间戳（秒）。", "schema": { "type": "integer", "example": 1750000000 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "超出速率限制的便于人类阅读的说明。", "example": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } }, "examples": { "Throttled": { "summary": "同一凭证在一分钟内生成的 PDF 超过 50 份", "value": { "detail": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --fail \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/generate-pdf/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.generate_pdf(\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.generatePdf(\"11111111-2222-3333-4444-555555555555\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.GeneratePDF(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().generatePdf(\"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->generatePdf('11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.generate_pdf(\"11111111-2222-3333-4444-555555555555\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.GeneratePdfAsync(\"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/session/{sessionId}/sandbox/arm/": { "post": { "summary": "在会话上启用沙盒场景", "description": "在处于 `Not Started` 状态的会话上持久化沙盒场景，并将其绑定的魔法值（邮箱、电话或 `expected_details` 字段）展开到会话中，以便在流程运行时模拟的服务商能够复现该场景的结果。当测试人员在开始采集前选择某个结果时，Didit 托管验证页面中的流程前场景选择器调用的就是该 endpoint。您可以基于它构建自己的选择器，或直接从沙盒测试套件中调用它。\n\n请使用会话自身的 `Session-Token`（由[创建会话](/zh/sessions-api/create-session)在 `session_token` 中返回）进行身份验证，而不是使用应用的 `x-api-key`：该 endpoint 旨在从客户端调用，而非从您的后端调用。仅当 `status` 为 `Not Started` 时才接受场景。在状态仍为 `Not Started` 时再次调用将重新配置该会话：它会替换为新场景的魔法值，并仅清除*上一个*场景写入的值，因此用户已经手动输入的任何值（邮箱、名等）在重新配置后仍会保留。对已超过 `Not Started` 状态或属于生产环境（非沙盒）应用的会话进行场景配置将被拒绝。\n\n有关完整的场景目录以及驱动结果的其他两种方式（创建会话时的 `sandbox_scenario` 以及直接输入魔法值），请参阅[沙盒与测试数据](/zh/integration/sandbox-testing)。", "operationId": "post_v3_session_sandbox_arm", "x-didit-sdk": { "resource": "sessions", "method": "arm_sandbox", "auth": "device_token", "server": false }, "tags": [ "Sessions" ], "security": [ { "SessionTokenAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "要启用的沙盒验证会话的 UUID。必须与用于身份验证的 Session-Token 中编码的会话匹配。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scenario" ], "properties": { "scenario": { "type": "string", "description": "要准备的场景标识。请参阅 GET /v1/sandbox/scenarios/ 中的目录或[沙盒与测试数据](/zh/integration/sandbox-testing)中的场景表格。", "example": "decline_document_expired" } } }, "examples": { "Arm": { "summary": "启用 AML 政治公众人物命中场景", "value": { "scenario": "decline_aml_hit" } } } } } }, "responses": { "200": { "description": "场景已预设。其魔法值现已写入会话。`status` 反映会话的当前状态，此调用绝不会更改该状态：成功时始终为 `Not Started`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "scenario": { "type": "string", "description": "已激活的场景 slug（回显请求内容）。" }, "status": { "type": "string", "example": "Not Started" } } }, "examples": { "Armed": { "summary": "已在 Not Started 会话上预设场景", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "scenario": "decline_aml_hit", "status": "Not Started" } } } } } }, "400": { "description": "验证错误：未知的场景标识（slug），或者会话已越过 `Not Started` 阶段。", "content": { "application/json": { "examples": { "Unknown Scenario": { "summary": "scenario 不在目录中", "value": { "scenario": [ "Unknown sandbox scenario: 'not-a-real-scenario'." ] } }, "Already Started": { "summary": "会话已离开 Not Started 状态", "value": [ "Scenario can only be armed before the verification starts." ] } } } } }, "404": { "description": "Session-Token 未解析到此 `session_id`，或者该会话属于生产环境（非沙盒）应用。", "content": { "application/json": { "examples": { "Not Found": { "summary": "活跃会话，或 session_id / token 不匹配", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/sandbox/arm/ \\\n -H 'Session-Token: YOUR_SESSION_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"scenario\": \"decline_aml_hit\"\n }'" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/sandbox/arm/\",\n headers={\n \"Session-Token\": \"YOUR_SESSION_TOKEN\",\n \"Content-Type\": \"application/json\",\n },\n json={\"scenario\": \"decline_aml_hit\"},\n)\nresponse.raise_for_status()\nprint(response.json()) # {'session_id': '...', 'scenario': 'decline_aml_hit', 'status': 'Not Started'}" }, { "lang": "javascript", "label": "JavaScript", "source": "const response = await fetch(\n 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/sandbox/arm/',\n {\n method: 'POST',\n headers: {\n 'Session-Token': sessionToken,\n 'Content-Type': 'application/json',\n },\n body: JSON.stringify({ scenario: 'decline_aml_hit' }),\n },\n);\nif (!response.ok) throw new Error(`HTTP ${response.status}`);\nconst { session_id, scenario, status } = await response.json();" } ] } }, "/v3/session/{sessionId}/update-status/": { "patch": { "summary": "批准、拒绝或请求重新提交验证会话", "description": "手动覆盖 KYC 或 KYB 验证会话的最终决策。将 `new_status` 设置为 `Approved` 或 `Declined` 以记录人工决策，或设置为 `Resubmitted` 以清除特定的验证步骤并让用户通过同一个验证 URL 重新进行验证。该 endpoint 同时接受用户（KYC）和企业（KYB）会话 ID。\n\n在会话达到可审核状态后调用此接口：当前状态必须为 `Approved`、`Declined`、`In Review`、`Kyc Expired`、`Abandoned` 或 `Resubmitted`。仍处于 `Not Started`、`In Progress` 或 `Awaiting User` 状态，或以 `Expired` 结束的会话将返回 `400`。您的 API 密钥需要 `write:sessions` 权限（作用域 API 密钥需要对决策具有写入权限）。符合资格状态的检查在请求体验证之前运行，因此即使 payload 也无效，不符合条件的会话也会返回 `Wrong Current Status` 错误。\n\n对于 `Resubmitted`，传递 `nodes_to_resubmit` 以选择用户必须重做的流程步骤，或省略该参数以自动选择处于可重新提交状态（`Declined`、`In Review`、`Not Finished`、`Expired`）的现有功能尝试。从未尝试过的功能不会被自动选择：需在 `nodes_to_resubmit` 中显式列出它们，否则在没有记录的尝试需要重新提交时，请求将返回 `400`。所选步骤的先前结果将移至重新提交的历史记录中（通过带有 `include=resubmissions` 的获取决策返回），这些步骤会重新排序以匹配工作流图谱，会话的过期窗口重新启动，原始验证 URL 恢复可用。位于列表开头的纯后端步骤（`AML`、`DATABASE_VALIDATION`、`IP_ANALYSIS`）无需用户交互即可立即运行；如果所有重新提交的步骤都是纯后端步骤，会话将在同一请求内重新完成最终判定。`KYB_REGISTRY` 和 `KYB_KEY_PEOPLE` 无法直接重新提交：请改为重新提交相关的子 KYC 会话，父企业会话将自动重新计算。\n\n每个更改状态的调用都会在更改提交后触发 `status.updated` [Webhook](/zh/integration/webhooks)，并在会话的 `reviews` 中追加一条活动记录（包含操作者信息和您的 `comment`），该记录可在[获取决策](#get-/v3/session/-sessionId-/decision/)和控制台活动时间线中查看。链接到会话 `vendor_data` 的用户档案汇总数据也会随之更新。拒绝操作会禁用该会话的持续 AML 监控；当工作流启用了监控时，重新通过（从 `Resubmitted`、`Declined` 或 `Kyc Expired`）会重新启用该监控。批准或拒绝属于 KYB 关键人员检查的子 KYC 将重新计算父企业会话的状态。设置 `send_email: true`（配合 `email_address`）以通知用户：针对 `Approved`/`Declined` 发送状态通知，针对 `Resubmitted` 发送包含验证链接和各步骤原因的重新提交邮件。如需预先检查邮件，可使用[预览决策邮件](/zh/sessions-api/preview-decision-email)（`Approved`、`Declined`）或[预览重新提交邮件](/zh/sessions-api/preview-resubmission)（`Resubmitted`）进行预览，并将其 `preview_token` 作为 `email_preview_token` 传递：随后更新将精确发送预览的邮件，或者在预览后邮件或会话发生更改，或预览回执已超过 15 分钟时，在做出任何更改之前返回 `409`。\n\n对已处于该状态的会话重复设置 `Approved` 或 `Declined` 不会更改任何内容并返回 `200`：不触发 Webhook、不添加活动记录且不发送邮件。重复设置 `Resubmitted` 将返回 `400`（`The new status is the same as the current status.`）。凭据缺失或无效以及权限缺失将返回 `403`；过期的作用域 API 密钥将返回 `401`。", "operationId": "patch_v3_session_update_status", "x-didit-sdk": { "resource": "sessions", "method": "update_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "要更新的验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID，服务会跨两种会话类型解析该 ID。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string", "description": "目标状态。`Approved` 和 `Declined` 会记录最终的人工审核决策（二者也可相互推翻）。`Resubmitted` 会清除所选步骤并将该会话退回给用户。任何其他值都会返回 `400`。", "enum": [ "Approved", "Declined", "Resubmitted" ], "example": "Approved" }, "comment": { "type": "string", "description": "变更的自由文本原因，存储在该会话的审核轨迹中，并在 [Get Decision](#get-/v3/session/-sessionId-/decision/) 的 `reviews` 数组中返回。例如 `Duplicated user`。", "example": "All checks passed manual review" }, "nodes_to_resubmit": { "type": "array", "description": "用户必须重做的工作流步骤。仅在 `new_status` 为 `Resubmitted` 时生效。对于 `Approved`/`Declined`，条目仍会进行模式验证（无效的 `feature` 值会返回 `400`），但在语义上符合模式的条目会被忽略。如果省略，服务器会自动选择状态为 `Declined`、`In Review`、`Not Finished` 或 `Expired` 的现有 OCR、活体检测、人脸比对、地址证明、电话、邮箱、AML、数据库核验和问卷尝试（NFC、IP 分析、年龄估算、人脸搜索和 KYB 证件尝试绝不会被自动选择；非人脸比对的人脸尝试会被选为 `LIVENESS`）；用户从未尝试过的功能（无记录尝试）不会被选择，因此即使没有任何内容通过，零次尝试的会话也会返回 `400`（\"No features found that need resubmission\"）；在这种情况下请显式传递 `nodes_to_resubmit`。无论您发送步骤的顺序如何，步骤均按工作流图谱顺序执行。`KYB_REGISTRY`、`KYB_KEY_PEOPLE` 和 `KYB` 别名会被拒绝并返回 `400`，这些父级检查会根据其子 KYC 会话重新计算。", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "在会话的工作流定义中显示的节点标识符（例如 `feature_ocr`、`feature_liveness`）。", "example": "feature_ocr" }, "feature": { "type": "string", "description": "节点的功能类型。别名 `ID_VERIFICATION`、`POA`、`PHONE` 和 `EMAIL` 会在服务端规范化为 `OCR`、`PROOF_OF_ADDRESS`、`PHONE_VERIFICATION` 和 `EMAIL_VERIFICATION`。`KYB_REGISTRY`、`KYB_KEY_PEOPLE` 和 `KYB` 虽然能通过模式验证，但始终会被示例中所示的业务规则 `400` 拒绝。", "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_DOCUMENTS", "ID_VERIFICATION", "POA", "PHONE", "EMAIL", "KYB_REGISTRY", "KYB_KEY_PEOPLE", "KYB", "GEOLOCATION" ], "example": "OCR" } } } }, "send_email": { "type": "boolean", "description": "是否就此变更向用户发送邮件。需要提供 `email_address`。对于 `Approved`/`Declined`，用户会收到状态通知；对于 `Resubmitted`，邮件将包含验证链接以及针对各步骤的重新提交原因。", "default": false, "example": false }, "email_address": { "type": "string", "format": "email", "description": "通知邮件的收件人。**当 `send_email` 为 `true` 时为必填项**，省略将返回 `400`。", "example": "user@example.com" }, "email_language": { "type": "string", "description": "通知邮件的语言。在 schema 层面接受任何字符串；不支持的代码将以静默方式回退为英语（`en`）。", "default": "en", "example": "en" }, "email_preview_token": { "type": "string", "writeOnly": true, "minLength": 1, "maxLength": 512, "description": "来自[预览决策邮件](/zh/sessions-api/preview-decision-email)（适用于 `Approved` 和 `Declined`）或[预览重新提交邮件](/zh/sessions-api/preview-resubmission)（适用于 `Resubmitted`）的可选凭证：即其 `preview_token`。仅在 `send_email: true` 时有效；若未提供，请求将返回 `400`。收件人、语言、会话状态、发件人和邮件（以及在重新提交时所选的步骤）仍必须与预览匹配，且凭证在 15 分钟后过期。否则在会话发生变更或发送邮件之前，请求将返回 `409`。现有集成可以省略此字段。" } } }, "examples": { "Approve Session": { "summary": "人工审核后批准会话", "value": { "new_status": "Approved", "comment": "All checks passed manual review" } }, "Decline Session": { "summary": "拒绝会话", "value": { "new_status": "Declined", "comment": "Suspected fraud" } }, "Resubmit Specific Steps": { "summary": "请求通过电子邮件重新提交所选步骤", "value": { "new_status": "Resubmitted", "nodes_to_resubmit": [ { "node_id": "feature_ocr", "feature": "OCR" }, { "node_id": "feature_liveness", "feature": "LIVENESS" } ], "send_email": true, "email_address": "user@example.com", "email_language": "en" } }, "Resubmit Auto-select": { "summary": "请求重新提交（自动选择未通过的步骤）", "value": { "new_status": "Resubmitted" } }, "Approve With Previewed Email": { "summary": "批准并发送“预览决策邮件”返回的邮件", "value": { "new_status": "Approved", "send_email": true, "email_address": "person@example.com", "email_language": "en", "email_preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } } } } }, "responses": { "200": { "description": "状态已更新。响应仅包含 `session_id`；请通过 [Get Decision](#get-/v3/session/-sessionId-/decision/) 获取更新后的会话。变更提交后会触发 `status.updated` Webhook。重复传入 `Approved` 或 `Declined` 会返回相同的响应体且不做任何更改。", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "已更新会话的 UUID。" } } }, "examples": { "Updated": { "summary": "针对已通过、已拒绝和已重新提交均会返回", "value": { "session_id": "3472fb7c-8f7c-4d1a-9cf4-cf3d74ce1a60" } } } } } }, "400": { "description": "验证错误。字段错误以 `{\"\": [\"\"]}` 形式返回（某些业务规则拒绝使用字符串值代替：`{\"nodes_to_resubmit\": \"\"}`），跨状态错误以 `{\"detail\": \"\"}` 形式返回，相同状态错误以纯 JSON 数组形式返回。", "content": { "application/json": { "examples": { "Wrong Current Status": { "summary": "会话不处于可更新状态", "value": { "detail": "Only sessions with status Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted can be updated. Current status: In Progress" } }, "Invalid Status Value": { "summary": "new_status 是有效的会话状态，但不是 Approved/Declined/Resubmitted 之一", "value": { "new_status": [ "You can only update the status to 'Approved', 'Declined', or 'Resubmitted'." ] } }, "Missing new_status": { "summary": "遗漏了必填字段", "value": { "new_status": [ "This field is required." ] } }, "Same Status": { "summary": "针对已处于“已重新提交”状态的会话请求了重新提交", "value": [ "The new status is the same as the current status." ] }, "Email Address Required": { "summary": "send_email 为 true 但未提供 email_address", "value": { "email_address": [ "Email address is required when send_email is true." ] } }, "Non-resubmittable Feature": { "summary": "重新提交的目标是 KYB 父级检查", "value": { "nodes_to_resubmit": "The following features cannot be resubmitted directly: KYB_REGISTRY. Resubmit the relevant child KYC sessions instead; the parent will recompute automatically." } }, "Nothing To Resubmit": { "summary": "自动选择未找到未批准的功能", "value": { "nodes_to_resubmit": "No features found that need resubmission. All features are already approved." } }, "Invalid Feature Choice": { "summary": "nodes_to_resubmit 中存在未知功能", "value": { "nodes_to_resubmit": [ { "feature": [ "\"BOGUS\" is not a valid choice. Valid choices are: OCR, OCR_BACK, NFC, AML, FACE, LIVENESS, FACE_MATCH, IP_ANALYSIS, AGE_ESTIMATION, PROOF_OF_ADDRESS, PHONE_VERIFICATION, EMAIL_VERIFICATION, FACE_SEARCH, DATABASE_VALIDATION, QUESTIONNAIRE, KYB_REGISTRY, KYB_DOCUMENTS, KYB_KEY_PEOPLE, ID_VERIFICATION, POA, PHONE, EMAIL, KYB" ] } ] } }, "Invalid Status Value (not a status at all)": { "summary": "new_status 不是有效的 StatusChoices 值", "value": { "new_status": [ "\"Bogus\" is not a valid choice." ] } }, "Preview Receipt Without Email": { "summary": "发送了 email_preview_token 但未设置 send_email: true", "value": { "email_preview_token": [ "A preview receipt is only valid when the email is sent." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "已过有效期的作用域 API 密钥", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少凭据或权限不足，或者 `session_id` 属于另一个应用。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "API 密钥缺少 write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "不存在具有此 `session_id` 的 KYC 或 KYB 会话（已删除的会话同样返回 `404`）。", "content": { "application/json": { "examples": { "Not Found": { "summary": "未知的 session_id", "value": { "detail": "Not found." } } } } } }, "429": { "description": "仅针对纯后端功能（AML、DATABASE_VALIDATION、IP_ANALYSIS）的重新提交在 30 秒冷却窗口内重复发起；立即重复发起无法改变结果。请降低重试频率，并在 `Retry-After` 指示的间隔后重试。", "content": { "application/json": { "examples": { "Backend-only resubmit throttled": { "value": { "detail": "This session was already resubmitted for backend-only features within the last 30 seconds; repeating it cannot change the outcome. Wait before resubmitting again." } } } } } }, "409": { "description": "电子邮件预览已更改或已过期。请在确认前重新生成预览；不会发生会话更改或电子邮件投递。", "content": { "application/json": { "examples": { "Preview Changed": { "summary": "收据不再匹配，或已超过 15 分钟", "value": { "detail": "This email preview changed or expired. Preview the message again before confirming." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"new_status\": \"Approved\",\n \"comment\": \"All checks passed manual review\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_status(\n \"11111111-2222-3333-4444-555555555555\",\n new_status=\"Approved\",\n comment=\"All checks passed manual review\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateStatus(\"11111111-2222-3333-4444-555555555555\", {\n new_status: \"Approved\",\n comment: \"All checks passed manual review\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateStatusParams{\n\tNewStatus: \"Approved\",\n\tComment: didit.String(\"All checks passed manual review\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateStatus(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateStatusParams.builder()\n .newStatus(SessionsUpdateStatusParams.NewStatus.of(\"Approved\"))\n .comment(\"All checks passed manual review\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateStatus('11111111-2222-3333-4444-555555555555', [\n 'new_status' => 'Approved',\n 'comment' => 'All checks passed manual review',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_status(\n \"11111111-2222-3333-4444-555555555555\",\n new_status: \"Approved\",\n comment: \"All checks passed manual review\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateStatusParams\n{\n NewStatus = \"Approved\",\n Comment = \"All checks passed manual review\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/": { "post": { "summary": "身份证件验证（证件 OCR + 欺诈检查）", "description": "一次调用即可完成身份证件的 OCR 并运行证件防伪检查，返回提取的持有人字段、解析后的 MRZ、`Approved`/`Declined`/`In Review` 的 `status`，以及说明所发现每个问题的 `warnings` 列表。支持来自 220+ 个国家/地区的 14,000+ 种证件类型。\n\n**工作原理。** 发送证件的 `front_image`（必填）；对于双面证件，还需发送 `back_image`。上传证件四角完整可见的未裁剪照片，服务会自动检测、对齐并裁剪证件，因此请勿预先裁剪。系统会自动对证件进行分类（您无需声明国家/地区或证件类型），通过 OCR 读取视觉区域，并解码 MRZ 及所有条形码。随后进行交叉核对，验证日期、数字格式和 MRZ 校验位，并将视觉区域与 MRZ 进行比对。当 `perform_document_liveness=true` 时，还会额外排查图像是否存在屏幕翻拍、复印件和肖像篡改。\n\n**决策逻辑。** 除非至少有一个警告被判定为拒绝，否则 `status` 为 `Approved`。欺诈和硬性失败风险一律拒绝：`DOCUMENT_EXPIRED`、`SCREEN_CAPTURE_DETECTED`、`PRINTED_COPY_DETECTED`、`PORTRAIT_MANIPULATION_DETECTED`、`PUBLIC_DOCUMENT_IMAGE_DETECTED`，以及提取失败（`NAME_NOT_DETECTED`、`DATE_OF_BIRTH_NOT_DETECTED`、`DOCUMENT_NUMBER_NOT_DETECTED`）。（`PORTRAIT_IMAGE_NOT_DETECTED`、`INVALID_DATE` 和 `MRZ_NOT_DETECTED` 存在于工作流会话中，但此独立 endpoint 绝不会产生这些警告。当正面图像未能高置信度匹配已知的官方证件设计时，此处会返回 `COULD_NOT_DETECT_DOCUMENT_TYPE`，并拒绝该请求。）有三类风险组可通过 `invalid_mrz_action`、`inconsistent_data_action` 和 `expiration_date_not_detected_action` 按请求单独配置（`DECLINE` 或 `NO_ACTION`）。所有其他警告（例如 `POSSIBLE_DUPLICATED_USER`）仅供参考，本身绝不会导致拒绝。当 `perform_document_liveness=true`（默认值）且防伪检查未返回可用分数时（供应商失败、返回非 200，或返回 HTTP 200 且 `status=\"ERR\"`），调用将返回 `200`，并将状态设为 `status: \"In Review\"`，同时附带 `DOCUMENT_LIVENESS_NOT_COMPUTED` 警告（`log_type: \"warning\"`），而非 `Approved`：未运行的检查不能作为证件真实的凭据。此升级逻辑不可配置，且绝不会推翻 `Declined` 判定；若 `perform_document_liveness=false`，则跳过该检查，状态如前所述取决于其余警告。完全无法处理的证件返回 `400` 及 `{\"error\": \"COULD_NOT_RECOGNIZE_DOCUMENT\"}`；可读取但存在问题的证件返回 `200` 及 `status: \"Declined\"`，请务必检查 `id_verification.status` 和 `id_verification.warnings`，而不仅仅是 HTTP 状态码。\n\n**计费。** 每个 `200` 响应消耗一次身份证件验证 API 额度（从您的套餐额度或充值余额中扣除）。当组织的余额不足以支付本次调用时，endpoint 会在进行任何图像处理之前返回 `403` 及额度不足错误。\n\n**会话持久化（`save_api_request`，默认 `true`）。** 为 `true` 时，调用将作为 API 类型的会话持久化保存：它会显示在 Business Console 中，返回的 `request_id` 是真实的会话 ID，可传递给 `GET /v3/session/{sessionId}/decision/`，裁剪后的证件/肖像图像会被存储并以短时有效的媒体 URL（`https:///ocr/...`）返回，同时向您配置的 Webhook endpoint 发送 `status.updated` Webhook。为 `false` 时，不存储任何内容，`request_id` 为一次性关联 UUID，且 `portrait_image`/`front_image`/`back_image` 以 Base64 编码的 JPEG 字符串内联返回。\n\n**沙盒。** 沙盒 API 密钥会跳过所有处理和计费：在请求验证通过后（格式错误的输入仍返回 `400`），endpoint 返回静态的 `Approved` 模拟 payload（虚构的“Sandbox User”美国身份证件），不持久化保存会话，也不消耗额度。\n\n**认证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。凭证缺失或无效返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`），此 API 绝不返回 `401`。\n\n**速率限制。** 所有 POST/PATCH/DELETE endpoint 共享每个 API 密钥 300 次请求/分钟的写入预算；超出将返回 `429`。", "operationId": "post_v3id-verification", "x-didit-sdk": { "resource": "id_verification", "method": "verify", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "front_image" ], "properties": { "front_image": { "type": "string", "format": "binary", "description": "身份证件的正面。允许的文件扩展名：`tiff`、`jpg`、`jpeg`、`png`、`webp`、`pdf`。最大上传大小：**10 MB**（超出限制的文件将被拒绝并返回 `400`）。PDF 在进行 OCR 之前会渲染为图像；加密的 PDF 需要提供 `front_image_password`。图像会自动压缩至约 0.5 MB 并应用 EXIF 方向矫正。请上传完整、未裁剪且证件四角均可见的拍摄件。" }, "front_image_password": { "type": "string", "description": "当 `front_image` 为加密 PDF 时用于解密的密码。发送未附带（或附带错误）密码的加密 PDF 将返回 `400`。", "writeOnly": true }, "back_image": { "type": "string", "format": "binary", "description": "证件背面：证件有背面时请务必发送（许多身份证件在背面带有 MRZ 或条形码；省略背面仅会在响应中使 MRZ 和背面字段保持为空，此 endpoint 不会触发缺少 MRZ 的警告）。格式和大小限制与 `front_image` 相同。省略时，响应中的 `back_image` 和背面字段为 `null`。" }, "back_image_password": { "type": "string", "description": "当 `back_image` 为加密 PDF 时用于解密的密码。", "writeOnly": true }, "perform_document_liveness": { "type": "boolean", "default": true, "description": "对两张图像进行呈现欺诈筛查：屏幕重放（`SCREEN_CAPTURE_DETECTED`）、打印副本（`PRINTED_COPY_DETECTED`）以及肖像篡改（`PORTRAIT_MANIPULATION_DETECTED`）。出现上述任何一种情况都会自动拒绝。默认启用；设置为 `false` 可跳过欺诈筛查并减少延迟。启用后，若提供商未返回可用评分，响应结果为包含 `DOCUMENT_LIVENESS_NOT_COMPUTED` 警告的 `In Review`，而非 `Approved`。", "example": true }, "minimum_age": { "type": "integer", "nullable": true, "default": null, "minimum": 1, "maximum": 120, "description": "已接受并验证（1–120），但**目前未被此 endpoint 应用**，绝不会因该字段生成 `MINIMUM_AGE_NOT_MET` 警告。请根据返回的 `date_of_birth`/`age` 执行年龄规则，或使用带有年龄限制的验证会话工作流。" }, "expiration_date_not_detected_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当无法读取到期日期时的处理操作（`EXPIRATION_DATE_NOT_DETECTED`）。默认为 `NO_ACTION`，因为许多证件上并未印有到期日期。注意：无论此选项如何设置，*已检测到且已过期*的到期日期始终会导致拒绝（`DOCUMENT_EXPIRED`）。" }, "invalid_mrz_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "DECLINE", "description": "当提取的 MRZ 未通过校验位验证（`MRZ_VALIDATION_FAILED`）时采取的操作。在此 endpoint 上，缺少 MRZ 不会触发警告。仅适用于带有 MRZ 的证件。此 endpoint 不支持 `REVIEW`，并会返回 `400`。" }, "inconsistent_data_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "DECLINE", "description": "当提取的数据存在内部不一致时的处理操作：`DATA_INCONSISTENT`、`MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`（目视区与 MRZ 不一致）或 `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`。" }, "critical_field_occlusion_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "DECLINE", "description": "当拍摄时关键打印字段（身份证件号码、姓名、出生日期或到期日期）被物理遮挡（`CRITICAL_FIELD_OCCLUSION_DETECTED`）时的处理操作。默认拒绝，与该 endpoint 的其他证件完整性风险相同：遮挡报告核对所需的号码属于涂抹证件的表现。无论哪种方式，被遮挡字段读取到的值都会从提取结果中丢弃，因此通常会伴随相应的 `*_NOT_DETECTED` 警告。该 endpoint 不支持 `REVIEW` 并会返回 `400`。" }, "document_or_personal_number_format_mismatch_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当号码不符合其签发机构针对该证件类型所使用的格式（`DOCUMENT_NUMBER_FORMAT_MISMATCH`、`PERSONAL_NUMBER_FORMAT_MISMATCH`）时的处理操作。默认为 `NO_ACTION`，即报告警告而不改变状态。该 endpoint 不支持 `REVIEW` 并会返回 `400`。" }, "preferred_characters": { "type": "string", "enum": [ "latin", "non_latin" ], "default": "latin", "description": "印有拉丁和非拉丁文本（阿拉伯语、西里尔字母、中日韩字符等）的证件上姓名/地址字段的首选文字系统。`latin` 返回音译/拉丁值；`non_latin` 优先返回原生文字系统。" }, "save_api_request": { "type": "boolean", "default": true, "description": "为 `true`（默认）时，将此次调用持久化为 API 类型的会话，在 Business Console 中可见，可使用返回的 `request_id` 通过 `GET /v3/session/{sessionId}/decision/` 检索，通过 `status.updated` Webhook 发出通知，并将证件图像作为媒体 URL 返回。为 `false` 时，不存储任何内容，`request_id` 为临时 UUID，且图像以 base64 JPEG 字符串形式内联返回。", "example": true }, "vendor_data": { "type": "string", "description": "可选的不透明字符串（您的内部用户 ID、邮箱、UUID 等），存储在持久化会话中并在响应中回显。可用于将 API 调用与您自己的记录相关联，并在稍后筛选会话。", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "与会话一同存储（当 `save_api_request=true` 时）并在响应中原样返回的可选 JSON 对象。在 multipart 请求中，请将其作为 JSON 编码的字符串字段发送（例如 `metadata={\"flow\":\"onboarding\"}`），它将被解析为对象。", "example": { "flow": "onboarding" } } } }, "example": { "front_image": "(binary JPEG/PNG/PDF of the document front)", "back_image": "(binary JPEG/PNG/PDF of the document back)", "perform_document_liveness": true, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "onboarding" } } } } }, "responses": { "200": { "description": "证件已处理。`id_verification.status` 为 `Approved`、`Declined` 或 `In Review`；检测到的每个问题都在 `id_verification.warnings` 中逐项列出。当所请求的证件活体检查未产生可用结果时返回 `In Review`（`DOCUMENT_LIVENESS_NOT_COMPUTED`）。有问题的证件仍会返回 `200` 并附带 `status: \"Declined\"` — 请检查响应体，而不仅仅是 HTTP 状态码。当 `save_api_request=true` 时，`request_id` 为持久化的会话 ID，图像字段为短期有效的媒体 URL；当 `save_api_request=false` 时，它们是内联的 Base64 JPEG 字符串。", "content": { "application/json": { "examples": { "Approved": { "summary": "清晰读取双面身份证件（已保存 — 图像作为媒体 URL）", "value": { "request_id": "11d219ed-d59c-4b1d-8d65-9b933f12d5b8", "id_verification": { "status": "Approved", "document_type": "Identity Card", "document_subtype": "ID_CARD_GENERIC", "document_number": "CBX164224", "personal_number": "20446581H", "portrait_image": "https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=...", "front_image": "https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=...", "back_image": "https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=...", "front_image_camera_front": null, "back_image_camera_front": null, "front_image_camera_front_face_match_score": null, "back_image_camera_front_face_match_score": null, "front_image_quality_score": { "focus_score": 78.0, "brightness_score": 83.2, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 40.7, "overall_score": 70.2 }, "back_image_quality_score": { "focus_score": 100.0, "brightness_score": 95.6, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 43.0, "overall_score": 84.4 }, "date_of_birth": "1980-01-13", "age": 46, "expiration_date": "2032-03-31", "date_of_issue": "2022-03-31", "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "Julio Francisco", "last_name": "Fores Sena", "full_name": "Julio Francisco Fores Sena", "gender": "M", "address": "Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife", "formatted_address": "Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain", "place_of_birth": "Valencia, Valencia", "marital_status": "UNKNOWN", "nationality": "ESP", "extra_fields": { "first_surname": "Fores", "second_surname": "Sena" }, "mrz": { "surname": "FORES SENA", "name": "JULIO FRANCISCO", "country": "ESP", "nationality": "ESP", "birth_date": "800113", "expiry_date": "320331", "sex": "M", "document_type": "ID", "document_number": "CBX164224", "optional_data": "20446581H", "optional_data_2": "", "birth_date_hash": "9", "expiry_date_hash": "8", "document_number_hash": "3", "final_hash": "3", "personal_number": "20446581H", "warnings": [], "errors": [], "mrz_type": "TD1", "mrz_string": "IDESPCBX164224320446581H<<<<<<\n8001139M3203318ESP<<<<<<<<<<<3\nFORES/ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-portrait_image-1d9a.jpg?signature=...", "front_image": "https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-front_image-5c2b.jpg?signature=...", "back_image": null, "front_image_camera_front": null, "back_image_camera_front": null, "front_image_camera_front_face_match_score": null, "back_image_camera_front_face_match_score": null, "front_image_quality_score": { "focus_score": 100.0, "brightness_score": 95.7, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 22.2, "overall_score": 79.3 }, "back_image_quality_score": null, "date_of_birth": "1997-01-30", "age": 29, "expiration_date": "2025-11-26", "date_of_issue": null, "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "Lucia", "last_name": "Marin Castro", "full_name": "Lucia Marin Castro", "gender": "F", "address": null, "formatted_address": null, "place_of_birth": null, "marital_status": "UNKNOWN", "nationality": "ESP", "extra_fields": { "first_surname": "Marin", "second_surname": "Castro" }, "mrz": {}, "parsed_address": null, "warnings": [ { "risk": "DOCUMENT_EXPIRED", "feature": "ID_VERIFICATION", "additional_data": null, "log_type": "error", "short_description": "Document expired", "long_description": "The document's expiration date has passed, rendering it no longer valid for use." } ], "barcodes": [] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:25:48.117204+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。" }, "id_verification": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "没有警告判定为拒绝且所请求的证件活体检测得出了可用结果时为 `Approved`；所请求的检测未得出可用结果（`DOCUMENT_LIVENESS_NOT_COMPUTED`）时为 `In Review`；有警告判定为拒绝时为 `Declined`，`warnings` 列表说明了具体原因。" }, "document_type": { "type": "string", "nullable": true, "description": "检测到的证件类型显示名称：`Identity Card`、`Passport`、`Driver's License`、`Residence Permit`、`Health Insurance Card` 或 `Tax Card`。当证件无法分类时为 `null`。", "example": "Identity Card" }, "document_subtype": { "type": "string", "nullable": true, "description": "可用时提供更细粒度的子类型（例如 `ID_CARD_GENERIC`、`EPASSPORT`）。", "example": "ID_CARD_GENERIC" }, "document_number": { "type": "string", "nullable": true, "example": "CBX164224" }, "personal_number": { "type": "string", "nullable": true, "description": "某些证件上印制的次要个人/国民身份号码。", "example": "20446581H" }, "portrait_image": { "type": "string", "nullable": true, "description": "从证件中裁剪的头像照片。当 `save_api_request=true`（默认）时为短期有效的媒体 URL（`https:///ocr/...`）；当 `save_api_request=false` 时为内联 base64 编码的 JPEG 字符串。未检测到头像时为 `null`。" }, "front_image": { "type": "string", "nullable": true, "description": "证件正面的对齐裁剪图。保存后为媒体 URL，否则为内联 base64 JPEG。" }, "back_image": { "type": "string", "nullable": true, "description": "证件背面的对齐裁剪图。未上传 `back_image` 时为 `null`。" }, "front_image_camera_front": { "type": "string", "nullable": true, "description": "在此 endpoint 上始终为 `null`（仅在摄像头拍摄验证会话中填充）。" }, "back_image_camera_front": { "type": "string", "nullable": true, "description": "在此 endpoint 上始终为 `null`。" }, "front_image_camera_front_face_match_score": { "type": "number", "nullable": true, "description": "在此 endpoint 上始终为 `null`。" }, "back_image_camera_front_face_match_score": { "type": "number", "nullable": true, "description": "在此 endpoint 上始终为 `null`。" }, "front_image_quality_score": { "type": "object", "nullable": true, "description": "上传图像的采集质量诊断（如果未提供该面或评分失败则为 `null`）。所有分数范围均为 0–100。", "properties": { "focus_score": { "type": "number", "format": "float", "description": "证件裁剪图像的清晰度（数值越高越清晰）。" }, "brightness_score": { "type": "number", "format": "float", "description": "曝光质量（越高越好）。" }, "brightness_issue": { "type": "string", "nullable": true, "description": "曝光正常时为 `ok`，否则为检测到的问题（例如过暗/过亮）。" }, "is_document_fully_visible": { "type": "boolean", "nullable": true, "description": "证件的四个角是否全部位于画幅内。" }, "resolution_score": { "type": "number", "format": "float", "description": "证件区域的有效分辨率。" }, "overall_score": { "type": "number", "format": "float", "description": "综合质量分数。" } } }, "back_image_quality_score": { "type": "object", "nullable": true, "description": "上传图像的采集质量诊断（如果未提供该面或评分失败则为 `null`）。所有分数范围均为 0–100。", "properties": { "focus_score": { "type": "number", "format": "float", "description": "证件裁剪图像的清晰度（数值越高越清晰）。" }, "brightness_score": { "type": "number", "format": "float", "description": "曝光质量（越高越好）。" }, "brightness_issue": { "type": "string", "nullable": true, "description": "曝光正常时为 `ok`，否则为检测到的问题（例如过暗/过亮）。" }, "is_document_fully_visible": { "type": "boolean", "nullable": true, "description": "证件的四个角是否全部位于画幅内。" }, "resolution_score": { "type": "number", "format": "float", "description": "证件区域的有效分辨率。" }, "overall_score": { "type": "number", "format": "float", "description": "综合质量分数。" } } }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "example": "1980-01-13" }, "age": { "type": "integer", "nullable": true, "description": "持有人年龄（岁），根据 `date_of_birth` 计算。", "example": 46 }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "example": "2032-03-31" }, "date_of_issue": { "type": "string", "format": "date", "nullable": true, "example": "2022-03-31" }, "issuing_state": { "type": "string", "nullable": true, "description": "签发国家/地区（ISO 3166-1 alpha-3）。", "example": "ESP" }, "issuing_state_name": { "type": "string", "nullable": true, "example": "Spain" }, "first_name": { "type": "string", "nullable": true, "example": "Julio Francisco" }, "last_name": { "type": "string", "nullable": true, "example": "Fores Sena" }, "full_name": { "type": "string", "nullable": true, "example": "Julio Francisco Fores Sena" }, "gender": { "type": "string", "nullable": true, "description": "`M`、`F`，或在未打印在证件上/未检测到时为 `null`。", "example": "M" }, "address": { "type": "string", "nullable": true, "description": "与证件上印刷完全一致的地址。" }, "formatted_address": { "type": "string", "nullable": true, "description": "`address` 的地理编码规范化版本。" }, "place_of_birth": { "type": "string", "nullable": true, "example": "Valencia, Valencia" }, "marital_status": { "type": "string", "nullable": true, "description": "`UNKNOWN`，除非证件上印有婚姻状况。", "example": "UNKNOWN" }, "nationality": { "type": "string", "nullable": true, "description": "持有人国籍（ISO 3166-1 alpha-3）。", "example": "ESP" }, "extra_fields": { "type": "object", "nullable": true, "additionalProperties": true, "description": "没有专用列的证件特定附加信息（例如西班牙身份证上的 `first_surname`/`second_surname`、驾驶证上的准驾车型）。" }, "mrz": { "type": "object", "description": "解析后的机读区。如果证件没有 MRZ 或无法读取，则为**空对象**（`{}`），在这种情况下，还请检查 `warnings` 列表。MRZ 内的日期使用原始的 `YYMMDD` 格式。", "properties": { "surname": { "type": "string", "example": "FORES SENA" }, "name": { "type": "string", "example": "JULIO FRANCISCO" }, "country": { "type": "string", "description": "签发国家/地区（ISO 3166-1 alpha-3）。", "example": "ESP" }, "nationality": { "type": "string", "description": "持有人国籍（ISO 3166-1 alpha-3）。", "example": "ESP" }, "birth_date": { "type": "string", "description": "原始 MRZ 出生日期（`YYMMDD`）。", "example": "800113" }, "expiry_date": { "type": "string", "description": "原始 MRZ 到期日期（`YYMMDD`）。", "example": "320331" }, "sex": { "type": "string", "example": "M" }, "document_type": { "type": "string", "description": "MRZ 证件类型代码（例如 `ID`、`P`）。", "example": "ID" }, "document_number": { "type": "string", "example": "CBX164224" }, "optional_data": { "type": "string", "nullable": true, "example": "20446581H" }, "optional_data_2": { "type": "string", "nullable": true, "example": "" }, "birth_date_hash": { "type": "string", "description": "出生日期的 MRZ 校验位。", "example": "9" }, "expiry_date_hash": { "type": "string", "description": "到期日期的 MRZ 校验位。", "example": "8" }, "document_number_hash": { "type": "string", "description": "证件号码的 MRZ 校验位。", "example": "3" }, "final_hash": { "type": "string", "description": "综合 MRZ 校验位。", "example": "3" }, "personal_number": { "type": "string", "nullable": true, "example": "20446581H" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "非致命性 MRZ 解析警告。" }, "errors": { "type": "array", "items": { "type": "string" }, "description": "MRZ 校验位/解析错误。非空错误会表现为 `MRZ_VALIDATION_FAILED` 警告。" }, "mrz_type": { "type": "string", "description": "MRZ 排版格式：`TD1`（身份证，3 行）、`TD2` 或 `TD3`（护照，2 行）。", "example": "TD1" }, "mrz_string": { "type": "string", "description": "读取的原始 MRZ 文本，行以 `\\n` 分隔。" }, "mrz_key": { "type": "string", "description": "用于交叉核对的复合键（证件号码 + 校验位）。" } } }, "parsed_address": { "type": "object", "nullable": true, "description": "`address` 的结构化、经地理编码的细分。当证件未包含地址或无法解析时为 `null`。", "properties": { "street_1": { "type": "string", "nullable": true, "example": "Avenida el Cardonal 52" }, "street_2": { "type": "string", "nullable": true, "example": "b" }, "city": { "type": "string", "nullable": true, "example": "La Laguna" }, "region": { "type": "string", "nullable": true, "example": "Canarias" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 国家/地区代码。", "example": "ES" }, "postal_code": { "type": "string", "nullable": true, "example": "38108" }, "address_type": { "type": "string", "nullable": true, "example": "Avenida" }, "formatted_address": { "type": "string", "nullable": true, "description": "规范的地理编码地址字符串。", "example": "Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain" }, "raw_results": { "type": "object", "additionalProperties": true, "description": "供高级使用者使用的原始地理编码 payload（`address_components`、`geometry.location`、`place_id` 等）。" }, "document_location": { "type": "object", "nullable": true, "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "description": "证件地址的地理编码坐标。" }, "label": { "type": "string", "nullable": true, "description": "地址读取自证件的哪个字段。", "example": "Spain Identity Card Address" }, "is_verified": { "type": "boolean", "description": "地理编码是否确认了该地址的存在。" }, "category": { "type": "string", "nullable": true, "description": "地址类别（例如 `Residential`、`Commercial`）。", "example": "Residential" } } }, "warnings": { "type": "array", "description": "完全通过审核时为空。每个条目说明一项检测到的风险；包含 `log_type: \"error\"` 的条目会将 `status` 设置为 `Declined`，而 `DOCUMENT_LIVENESS_NOT_COMPUTED`（`log_type: \"warning\"`）会将其设置为 `In Review`。", "items": { "type": "object", "properties": { "risk": { "type": "string", "description": "机器可读的风险代码。始终拒绝的风险：`DOCUMENT_EXPIRED`、`MINIMUM_AGE_NOT_MET`、`PORTRAIT_IMAGE_NOT_DETECTED`、`SCREEN_CAPTURE_DETECTED`、`PRINTED_COPY_DETECTED`、`PORTRAIT_MANIPULATION_DETECTED`、`PUBLIC_DOCUMENT_IMAGE_DETECTED`、`INVALID_DATE`、`COULD_NOT_RECOGNIZE_DOCUMENT`（仅限 400，从不作为警告）、`DOCUMENT_NUMBER_NOT_DETECTED`、`COULD_NOT_DETECT_DOCUMENT_TYPE`、`NAME_NOT_DETECTED`、`DATE_OF_BIRTH_NOT_DETECTED`。由请求选项控制：`MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED`（`invalid_mrz_action`）、`DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`（`inconsistent_data_action`）、`EXPIRATION_DATE_NOT_DETECTED`（`expiration_date_not_detected_action`）。其他风险（例如 `POSSIBLE_DUPLICATED_USER`）仅供参考。当 `perform_document_liveness=true` 但伪造检测未返回可用分数时，会触发 `DOCUMENT_LIVENESS_NOT_COMPUTED`；它将 `status` 设置为 `In Review`。当证件正面无法以高置信度匹配已知的官方证件样式时（例如经过编辑或计算机生成的证件，或者尚未支持的样式），也会返回 `COULD_NOT_DETECT_DOCUMENT_TYPE`。", "example": "DOCUMENT_EXPIRED" }, "feature": { "type": "string", "enum": [ "ID_VERIFICATION" ], "description": "引发该警告的功能。在此 endpoint 上始终为 `ID_VERIFICATION`。" }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "某些风险的额外上下文信息（例如 `POSSIBLE_DUPLICATED_USER` 包含 `duplicated_session_id`）；对大多数风险为 `null`。" }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "严重程度。`error` 警告会导致 `status` 变为 `Declined`；`warning`（仅限 `DOCUMENT_LIVENESS_NOT_COMPUTED`，即所请求的防伪检查未生成可用分数时）会导致 `status` 变为 `In Review`；`information` 条目仅供参考，绝不会改变状态。" }, "short_description": { "type": "string", "description": "易于阅读的单行风险摘要。" }, "long_description": { "type": "string", "description": "风险的便于人类阅读的说明。" } } } }, "barcodes": { "type": "array", "description": "从证件解码出的条形码（PDF417、QR 码等）。当证件没有条形码或无法读取时为空。", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "条形码类型（例如 `PDF417`、`QR_CODE`、`UNKNOWN`）。" }, "position": { "type": "object", "nullable": true, "additionalProperties": true, "description": "图像中条形码的位置（如有）。" }, "data": { "type": "string", "description": "解码后的 payload。" }, "data_raw": { "type": "string", "description": "原始（未解码）payload（如果不同）。" }, "side": { "type": "string", "nullable": true, "description": "`front` 或 `back`。" } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，或 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 对象回显，或 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "响应生成时的 ISO 8601 时间戳（UTC）。" } } } } } }, "400": { "description": "验证或处理错误。字段级问题返回 DRF 的标准外层结构（每个出错字段对应一个消息数组）。加密 PDF 问题返回 `{\"detail\": ...}`。完全无法识别出证件的证件图像返回 `{\"error\": \"COULD_NOT_RECOGNIZE_DOCUMENT\"}`。上传 PDF 还可能因“提交的 PDF 文件已损坏或无效。”或无页面错误而失败。", "content": { "application/json": { "examples": { "Missing front image": { "summary": "表单数据中未包含 `front_image`", "value": { "front_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "文件扩展名不在 tiff/jpg/jpeg/png/webp/pdf 范围内", "value": { "front_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf." ] } }, "File too large": { "summary": "上传内容超过 10 MB 限制", "value": { "front_image": [ "File size should not exceed 10 MB" ] } }, "Invalid option value": { "summary": "选项仅接受 DECLINE 或 NO_ACTION", "value": { "invalid_mrz_action": [ "\"REVIEW\" is not a valid choice." ] } }, "Encrypted PDF": { "summary": "上传的 PDF 未提供所需密码", "value": { "detail": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Wrong PDF password": { "summary": "`front_image_password` / `back_image_password` 无法解密 PDF", "value": { "detail": "The PDF password is incorrect. Please provide the correct password." } }, "Document not recognized": { "summary": "图像中无法检测到身份证件", "value": { "error": "COULD_NOT_RECOGNIZE_DOCUMENT" } }, "PDF conversion failure": { "summary": "上传的 PDF 无法转换为图像", "value": { "error": "Failed to convert front image PDF." } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头，或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何图像处理之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/id-verification/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'front_image=@./id_front.jpg' \\\n -F 'back_image=@./id_back.jpg' \\\n -F 'perform_document_liveness=true' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_verification.verify(\n front_image=open(\"front_image.jpg\", \"rb\"),\n back_image=open(\"back_image.jpg\", \"rb\"),\n perform_document_liveness=True,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"onboarding\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idVerification.verify({\n front_image: await fileFromPath(\"front_image.jpg\"),\n back_image: await fileFromPath(\"back_image.jpg\"),\n perform_document_liveness: true,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"onboarding\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{\n\tFrontImage: didit.FileFromPath(\"front_image.jpg\"),\n\tBackImage: didit.Some(didit.FileFromPath(\"back_image.jpg\")),\n\tPerformDocumentLiveness: didit.Bool(true),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"onboarding\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.IdVerificationVerifyParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idVerification().verify(IdVerificationVerifyParams.builder()\n .frontImage(Path.of(\"front_image.jpg\"))\n .backImage(Path.of(\"back_image.jpg\"))\n .performDocumentLiveness(true)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"onboarding\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idVerification->verify([\n 'front_image' => File::fromPath('front_image.jpg'),\n 'back_image' => File::fromPath('back_image.jpg'),\n 'perform_document_liveness' => true,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'onboarding'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_verification.verify(\n front_image: Pathname(\"front_image.jpg\"),\n back_image: Pathname(\"back_image.jpg\"),\n perform_document_liveness: true,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"onboarding\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams\n{\n FrontImage = FileUpload.FromPath(\"front_image.jpg\"),\n BackImage = FileUpload.FromPath(\"back_image.jpg\"),\n PerformDocumentLiveness = true,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"onboarding\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/face-match/": { "post": { "summary": "人脸比对", "description": "比对两张人脸图像（1:1）并返回相似度 `score`（0–100）以及 `Approved`/`Declined` 状态 `status`。\n\n**工作原理。** 两张图像均由生物识别模型进行解码和分析（如果拍摄可能横向或倒置，请设置 `rotate_image=true`），随后计算两个人脸之间的相似度分数。分数**严格高于** `face_match_score_decline_threshold`（默认 `30`）返回 `status: \"Approved\"`；分数等于或低于该阈值返回 `Declined`，并带有 `LOW_FACE_MATCH_SIMILARITY` 警告。如果完全无法对任何人脸对进行评分，调用仍返回 `200`，状态为 `status: \"Declined\"`，并带有 `NO_REFERENCE_IMAGE` 警告：在默认保存路径下 `score` 为 `null`，设置 `save_api_request=false` 时为 `0`。为获得最佳结果，每张图像请提交一张清晰的正面人脸。\n\n**计费。** 每个 `200` 响应消耗一个人脸比对 API 额度（从您的套餐额度或充值余额中扣除）。当组织的余额不足以支付本次调用时，endpoint 会在进行任何图像处理之前返回 `403` 并提示额度不足错误。\n\n**会话持久化（`save_api_request`，默认 `true`）。** 当为 `true` 时，该调用将作为 API 类型会话持久化：它会显示在 Business Console 中，返回的 `request_id` 是一个真实的会话 ID，您可以将其传递给 `GET /v3/session/{sessionId}/decision/`，两张图像都会作为该会话的人脸比对源/目标图像进行存储，并且会向您配置的 Webhook endpoint 发送 `status.updated` Webhook。当为 `false` 时，不会存储任何内容，且 `request_id` 是一个一次性的关联 UUID，无法在后续进行查询。\n\n**人脸搜索索引。** 此 endpoint 绝不会将人脸录入到您的人脸搜索索引中，也绝不运行黑名单或重复筛查：如需这些功能，请使用 `POST /v3/passive-liveness/` 或 `POST /v3/face-search/`。\n\n**沙盒。** 沙盒 API 密钥会跳过所有处理和计费：在请求验证之后（格式错误的输入仍会返回 `400`），endpoint 会返回静态的 `Approved` 模拟 payload，不会持久化会话，也不会消耗额度。\n\n**身份验证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。缺失或无效的凭证将返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`）：此 API 绝不返回 `401`。\n\n**速率限制。** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 之间共享每分钟 300 次请求的写入预算；超出将返回 `429`。", "operationId": "post_v3face-match", "x-didit-sdk": { "resource": "face_match", "method": "compare", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image", "ref_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "待验证的真人或候选人脸图像（例如自拍照）。请提交一张主体面部清晰可见且光线充足的正脸照片。允许的扩展名：`tiff`、`jpg`、`jpeg`、`png`、`webp`。最大上传大小：**5 MB**（超出限制的文件将被拒绝并返回 `400`）。图像在处理前会自动压缩至约 0.5 MB，因此极高分辨率并不会提高准确度。" }, "ref_image": { "type": "string", "format": "binary", "description": "用于比对的参考人脸图像（例如身份证件人像照或先前登记的照片）。格式和大小限制与 `user_image` 相同。" }, "face_match_score_decline_threshold": { "type": "number", "format": "float", "default": 30, "minimum": 0, "maximum": 100, "description": "决定响应 `status` 的相似度阈值（0–100）。计算得出的分数**小于或等于**此值会将 `status` 设置为 `Declined` 并添加 `LOW_FACE_MATCH_SIMILARITY` 警告；严格高于此分数则返回 `Approved`。默认值 `30` 较为宽松，如需更严格的验证，可调高该值（例如 `50`–`60`）。超出 0–100 范围的值将返回 `400`。", "example": 50 }, "rotate_image": { "type": "boolean", "default": false, "description": "为 `true` 时，服务会按 90 度递增（0、90、180、270）尝试输入图像，并使用人脸检测效果最佳的方向，这对于缺少 EXIF 方向信息的移动设备拍摄非常有用。这会增加延迟，因此仅在您无法保证图像为正向时启用。", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "为 `true`（默认）时，将此次调用持久化为 API 类型的会话，在 Business Console 中可见，可使用返回的 `request_id` 通过 `GET /v3/session/{sessionId}/decision/` 检索，并通过 `status.updated` Webhook 发出通知。为 `false` 时，不存储任何内容，且 `request_id` 仅为用于关联响应的临时 UUID。", "example": true }, "vendor_data": { "type": "string", "description": "可选的不透明字符串（您的内部用户 ID、邮箱、UUID 等），存储在持久化会话中并在响应中回显。可用于将 API 调用与您自己的记录相关联，并在稍后筛选会话。", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "与会话一同存储（当 `save_api_request=true` 时）并在响应中原样返回的可选 JSON 对象。在 multipart 请求中，请将其作为 JSON 编码的字符串字段发送（例如 `metadata={\"flow\":\"login\"}`），它将被解析为对象。", "example": { "flow": "login", "device_id": "abc123" } } } }, "example": { "user_image": "(binary JPEG/PNG of the live selfie)", "ref_image": "(binary JPEG/PNG of the reference photo)", "face_match_score_decline_threshold": 50, "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "login" } } } } }, "responses": { "200": { "description": "人脸比对已计算。`face_match.score` 为 0–100 的浮点数（保留两位小数）；当分数严格高于 `face_match_score_decline_threshold` 时，`status` 为 `Approved`，否则为 `Declined` 并附带说明性警告。相似度较低或无法评分的人脸对仍会返回 `200`，请检查 `face_match.status` 和 `face_match.warnings`，而不仅仅是 HTTP 状态码。当 `save_api_request=true` 时，`request_id` 为持久化的会话 ID。", "content": { "application/json": { "examples": { "Approved": { "summary": "同一人：分数高于阈值", "value": { "request_id": "f9f5a777-8002-44c6-baaf-128bcfd6e226", "face_match": { "status": "Approved", "score": 99.41, "user_image": { "entities": [ { "bbox": [ 661, 728, 1688, 2188 ], "confidence": 0.732973, "age": 26.91, "gender": "male", "race": null } ], "best_angle": 0 }, "ref_image": { "entities": [ { "bbox": [ 653, 745, 1691, 2185 ], "confidence": 0.722082, "age": 27.0, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": "user-123", "metadata": { "flow": "login" }, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Declined - low similarity": { "summary": "等于或低于拒绝阈值的分数", "value": { "request_id": "7cdda24e-311a-46d3-a3bb-e5d9b564ce73", "face_match": { "status": "Declined", "score": 24.87, "user_image": { "entities": [ { "bbox": [ 661, 728, 1688, 2188 ], "confidence": 0.732973, "age": 26.91, "gender": "male", "race": null } ], "best_angle": 0 }, "ref_image": { "entities": [ { "bbox": [ 156, 234, 679, 898 ], "confidence": 0.717775, "age": 41.2, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [ { "risk": "LOW_FACE_MATCH_SIMILARITY", "feature": "FACEMATCH", "additional_data": null, "log_type": "error", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:08:19.859116+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。" }, "face_match": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "当相似度分数严格高于 `face_match_score_decline_threshold` 且能够计算出分数时为 `Approved`；否则为 `Declined`（会有警告说明原因）。" }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "相似度分数，范围为 0 到 100，即模型对两张图像代表同一人的置信度。仅在 `save_api_request` 为 true 时四舍五入保留两位小数；当 `save_api_request=false` 时返回原始浮点数。当无法对人脸对进行评分时为 `null`（在默认的 `save_api_request=true` 情况下）；当 `save_api_request=false` 时，相同情况可能表现为 `score: 0`。无论哪种情况，都会出现 `NO_REFERENCE_IMAGE` 警告且 `status` 为 `Declined`。", "example": 99.41 }, "user_image": { "type": "object", "description": "所分析图像的各项人脸检测结果。", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "检测到的人脸边界框，表示为处理后图像中的 `[x_min, y_min, x_max, y_max]` 像素坐标。", "example": [ 661, 728, 1688, 2188 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "人脸检测置信度（0–1）。", "example": 0.732973 }, "age": { "type": "number", "format": "float", "description": "检测到的人脸的模型估算年龄（以岁为单位）。仅供参考，不影响人脸比对决策。", "example": 26.91 }, "gender": { "type": "string", "description": "模型预测的检测人脸性别（`male` 或 `female`）。仅供参考。", "example": "male" }, "race": { "type": "string", "nullable": true, "description": "保留字段 — 在此 endpoint 的响应中始终为 `null`。", "example": null } } }, "description": "每张检测到的人脸对应一个条目。" }, "best_angle": { "type": "integer", "description": "产生最佳人脸检测结果的旋转角度（度：0、90、180 或 270）。仅当 `rotate_image=true` 纠正了方向时才为非零值。", "example": 0 } } }, "ref_image": { "type": "object", "description": "参考图像的人脸检测结果，结构与 `user_image` 相同。", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "检测到的人脸边界框，表示为处理后图像中的 `[x_min, y_min, x_max, y_max]` 像素坐标。", "example": [ 661, 728, 1688, 2188 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "人脸检测置信度（0–1）。", "example": 0.732973 }, "age": { "type": "number", "format": "float", "description": "检测到的人脸的模型估算年龄（以岁为单位）。仅供参考，不影响人脸比对决策。", "example": 26.91 }, "gender": { "type": "string", "description": "模型预测的检测人脸性别（`male` 或 `female`）。仅供参考。", "example": "male" }, "race": { "type": "string", "nullable": true, "description": "保留字段 — 在此 endpoint 的响应中始终为 `null`。", "example": null } } }, "description": "每张检测到的人脸对应一个条目。" }, "best_angle": { "type": "integer", "example": 0 } } }, "warnings": { "type": "array", "description": "完全通过审核时为空。`NO_REFERENCE_IMAGE`（`error`）— 无法对人脸对进行评分；`LOW_FACE_MATCH_SIMILARITY`（`error`）— 分数等于或低于拒绝阈值。其中任何一项都会将 `status` 设置为 `Declined`。", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "NO_REFERENCE_IMAGE", "LOW_FACE_MATCH_SIMILARITY" ], "description": "机器可读的风险代码。" }, "feature": { "type": "string", "enum": [ "FACEMATCH" ], "description": "引发该警告的功能。在此 endpoint 上始终为 `FACEMATCH`。" }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "对于人脸比对警告始终为 `null`。" }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "严重程度。`error` 警告会导致 `status` 变为 `Declined`；`warning` 和 `information` 条目仅供参考，本身绝不会导致拒绝。" }, "short_description": { "type": "string", "description": "易于阅读的单行风险摘要。" }, "long_description": { "type": "string", "description": "风险的便于人类阅读的说明。" } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，或 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 对象回显，或 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "响应生成时的 ISO 8601 时间戳（UTC），例如 `2026-06-12T01:04:42.763237+00:00`。" } } } } } }, "400": { "description": "验证错误。当必需的图像缺失、超过 5 MB、扩展名不受支持，或选项超出范围时返回。响应体为 DRF 的标准字段错误响应格式：每个有问题的字段对应一个消息数组。", "content": { "application/json": { "examples": { "Missing required image": { "summary": "表单数据中未包含 `ref_image`（或 `user_image`）", "value": { "ref_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "文件扩展名不在 tiff/jpg/jpeg/png/webp 范围内", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "上传内容超过 5 MB 限制", "value": { "user_image": [ "File size should not exceed 5 MB" ] } }, "Threshold out of range": { "summary": "`face_match_score_decline_threshold` 超出 0–100 范围", "value": { "face_match_score_decline_threshold": [ "Ensure this value is less than or equal to 100." ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头，或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何图像处理之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/face-match/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'ref_image=@./id_portrait.jpg' \\\n -F 'face_match_score_decline_threshold=50' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.face_match.compare(\n user_image=open(\"user_image.jpg\", \"rb\"),\n ref_image=open(\"ref_image.jpg\", \"rb\"),\n face_match_score_decline_threshold=50.0,\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"login\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.faceMatch.compare({\n user_image: await fileFromPath(\"user_image.jpg\"),\n ref_image: await fileFromPath(\"ref_image.jpg\"),\n face_match_score_decline_threshold: 50.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"login\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceMatch.Compare(ctx, didit.FaceMatchCompareParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tRefImage: didit.FileFromPath(\"ref_image.jpg\"),\n\tFaceMatchScoreDeclineThreshold: didit.Float(50.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"login\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.FaceMatchCompareParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.faceMatch().compare(FaceMatchCompareParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .refImage(Path.of(\"ref_image.jpg\"))\n .faceMatchScoreDeclineThreshold(50.0)\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"login\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "faceMatch->compare([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'ref_image' => File::fromPath('ref_image.jpg'),\n 'face_match_score_decline_threshold' => 50.0,\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'login'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.face_match.compare(\n user_image: Pathname(\"user_image.jpg\"),\n ref_image: Pathname(\"ref_image.jpg\"),\n face_match_score_decline_threshold: 50.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"login\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FaceMatch.CompareAsync(new FaceMatchCompareParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n RefImage = FileUpload.FromPath(\"ref_image.jpg\"),\n FaceMatchScoreDeclineThreshold = 50.0,\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"login\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/age-estimation/": { "post": { "summary": "年龄估算（人脸年龄 + 被动活体检测）", "description": "通过单张人脸照片估算人员年龄，并在同一次调用中执行被动活体检测：返回模型预测的 `age_estimation`（以岁为单位）、活体检测 `score`（0–100）以及 `Approved`/`Declined` 的 `status`。该年龄是**根据人脸由模型预测得出，而非通过证件核验**。可将其用于年龄门槛和低摩擦检查，但不能作为年龄的法律证明。\n\n**工作原理。**系统会分析图像中的人脸（如果拍摄的人脸可能是横向或倒置的，请设置 `rotate_image=true`）；检测到的每张人脸都会获得一个估算年龄，画面中最大的人脸决定 `age_estimation`。与此同时，被动活体检测模型会评估照片是否为真人（无需用户配合动作验证），并检测呈现攻击（翻拍照、屏幕、面具）。为获得最佳效果，每张图像请提交一张清晰、正面、光线充足的人脸。\n\n**决策逻辑。**出现任何警告都会导致拒绝：仅当 `warnings` 数组为空时，`status` 才为 `Approved`。活体检测 `score` 低于或等于 `face_liveness_score_decline_threshold`（默认 `30`）会添加 `LOW_LIVENESS_SCORE`；检测到攻击会添加 `LIVENESS_FACE_ATTACK`；活体检测模型未检测到人脸会添加 `NO_FACE_DETECTED`；无法估算人脸年龄会添加 `AGE_NOT_DETECTED`（`age_estimation` 为 `null`）；估算年龄低于 `age_estimation_decline_threshold`（默认 `18`）会添加 `AGE_BELOW_MINIMUM`。对于接近您阈值的临界年龄，建议回退到基于证件的验证，因为模型对接近边界的人脸误差会增加。\n\n**计费。**每次 `200` 响应将消耗一个年龄估算 API 额度（从您的套餐额度或充值余额中扣除）。当组织的余额不足以支付此次调用时，endpoint 会在进行任何图像处理之前返回 `403` 及额度不足错误。\n\n**会话持久化（`save_api_request`，默认 `true`）。**当为 `true` 时，该调用将作为 API 类型的会话进行持久化：它会显示在 Business Console 中，返回的 `request_id` 是真实的会话 ID，您可以将其传递给 `GET /v3/session/{sessionId}/decision/`（结果在其中的 `liveness_checks[]` 中公开，且带有 `features: [\"AGE_ESTIMATION\"]`），人脸裁剪图和参考图像将被存储，人脸特征向量会被添加到您应用的人脸索引中（供人脸搜索和重复项检测使用），并触发 `status.updated` Webhook。当为 `false` 时，不会存储任何内容，且 `request_id` 是一次性关联 UUID，后续无法查询。\n\n**沙盒。**沙盒 API 密钥会跳过所有处理和计费：在请求验证后（格式错误的输入仍会返回 `400`），endpoint 会返回静态的 `Approved` 模拟 payload（`age_estimation: 30`，无警告），不会持久化任何会话，也不会消耗任何额度。\n\n**认证。**在 `x-api-key` 请求头中发送您应用的 API 密钥。缺少或无效的凭据将返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`），此 API 从不返回 `401`。\n\n**速率限制。**所有 POST/PATCH/DELETE endpoint 共享每个 API 密钥 300 次请求/分钟的写入预算；超出将返回 `429`。", "operationId": "post_v3age-estimation", "x-didit-sdk": { "resource": "age_estimation", "method": "estimate", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "要分析的人脸照片（例如自拍照）。请提交一张拍摄对象面部清晰可见且光线充足的正面照片。允许的文件扩展名：`tiff`、`jpg`、`jpeg`、`png`、`webp`（不支持 PDF）。最大上传大小：**5 MB**（较大文件将被拒绝并返回 `400`）。图像在处理前会自动压缩至约 0.3 MB，因此极高的分辨率并不会提高准确性。" }, "face_liveness_score_decline_threshold": { "type": "number", "format": "float", "default": 30, "minimum": 0, "maximum": 100, "description": "活体阈值（0–100）。活体 `score` **达到或低于**此值将添加 `LOW_LIVENESS_SCORE` 警告并予以拒绝。调高此值可实施更严格的防欺骗攻击策略；超出 0–100 范围的值将返回 `400`。", "example": 30 }, "age_estimation_decline_threshold": { "type": "integer", "default": 18, "minimum": 0, "maximum": 100, "description": "可接受的最低估算年龄（周岁）。估算年龄**低于**该值将添加 `AGE_BELOW_MINIMUM` 警告并予以拒绝。设为 `0` 可禁用年龄检查（此时调用仅执行活体检测 + 年龄估算，不做出基于年龄的决策）。", "example": 18 }, "rotate_image": { "type": "boolean", "default": false, "description": "为 `true` 时，服务会按 90 度递增（0、90、180、270）尝试输入图像，并使用人脸检测效果最佳的方向，这对于缺少 EXIF 方向信息的移动端拍摄非常有用。会增加延迟，因此仅在您无法保证图像为正向时启用。", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "为 `true`（默认）时，将此次调用持久化为 API 类型的会话，在 Business Console 中可见，可使用返回的 `request_id` 通过 `GET /v3/session/{sessionId}/decision/` 检索，通过 `status.updated` Webhook 发出通知，并将检测到的人脸添加到您应用的人脸索引中。为 `false` 时，不存储任何内容，且 `request_id` 仅为用于关联响应的临时 UUID。", "example": true }, "vendor_data": { "type": "string", "description": "可选的不透明字符串（您的内部用户 ID、邮箱、UUID 等），存储在持久化会话中并在响应中回显。可用于将 API 调用与您自己的记录相关联，并在稍后筛选会话。", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "与会话一同存储（当 `save_api_request=true` 时）并在响应中原样返回的可选 JSON 对象。在 multipart 请求中，请将其作为 JSON 编码的字符串字段发送（例如 `metadata={\"flow\":\"age-gate\"}`），它会被解析为对象。", "example": { "flow": "age-gate" } } } }, "example": { "user_image": "(binary JPEG/PNG of the selfie)", "face_liveness_score_decline_threshold": 30, "age_estimation_decline_threshold": 18, "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "age-gate" } } } } }, "responses": { "200": { "description": "年龄估算和被动活体检测已完成。`age_estimation.age_estimation` 是模型预测的最大检测人脸年龄（以岁为单位，未检测到则为 `null`）；`age_estimation.score` 是被动活体检测分数（0–100）；仅当 `warnings` 为空时，`status` 才为 `Approved`。未成年或欺骗攻击的抓拍仍会返回 `200` 及 `status: \"Declined\"`，请检查响应体，而不仅仅是 HTTP 状态码。当 `save_api_request=true` 时，`request_id` 为持久化的会话 ID。", "content": { "application/json": { "examples": { "Approved": { "summary": "活体成人面部 — 两项检查均已通过", "value": { "request_id": "0c40ba43-64ab-4e2e-b4b8-7d1f12f81bc1", "age_estimation": { "status": "Approved", "method": "PASSIVE", "score": 97.5, "user_image": { "entities": [ { "age": 27.33, "bbox": [ 40, 40, 100, 100 ], "confidence": 0.7177750468254089, "gender": "male" } ], "best_angle": 0 }, "age_estimation": 27.33, "warnings": [] }, "vendor_data": "user-123", "metadata": { "flow": "age-gate" }, "created_at": "2026-06-12T02:24:11.512941+00:00" } }, "Declined - age below threshold": { "summary": "估算年龄低于 `age_estimation_decline_threshold`", "value": { "request_id": "9be41a6f-2f4e-4f57-92f4-b3a4f6f0a1c2", "age_estimation": { "status": "Declined", "method": "PASSIVE", "score": 95.0, "user_image": { "entities": [ { "age": 16.5, "bbox": [ 40, 40, 100, 100 ], "confidence": 0.7177750468254089, "gender": "female" } ], "best_angle": 0 }, "age_estimation": 16.5, "warnings": [ { "risk": "AGE_BELOW_MINIMUM", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Age below minimum", "long_description": "The age of the face is below the minimum age threshold for the application." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:26:40.118332+00:00" } }, "Declined - liveness too low": { "summary": "活体评分达到或低于拒绝阈值（疑似欺骗攻击）", "value": { "request_id": "5f6f2f1f-7c4f-43b9-8d62-0a8f4c2d9e77", "age_estimation": { "status": "Declined", "method": "PASSIVE", "score": 5.0, "user_image": { "entities": [ { "age": 25.0, "bbox": [ 40, 40, 100, 100 ], "confidence": 0.7177750468254089, "gender": "male" } ], "best_angle": 0 }, "age_estimation": 25.0, "warnings": [ { "risk": "LOW_LIVENESS_SCORE", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Low liveness score", "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:27:02.901547+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。" }, "age_estimation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "未触发任何警告时为 `Approved`；否则为 `Declined`（该 endpoint 产生的所有警告均会导致拒绝）。" }, "method": { "type": "string", "enum": [ "PASSIVE" ], "description": "活体检测方法。在此 endpoint 上始终为 `PASSIVE`（单张图像，无用户挑战）。" }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "0 到 100 之间的静默活体评分，即模型对照片显示为活人的置信度。与 `face_liveness_score_decline_threshold` 进行比对；等于或低于该阈值时调用将被拒绝，并提示 `LOW_LIVENESS_SCORE`。当活体模型未返回置信度时为 `null`；由于在阈值比对中 null 被视作 0，调用仍会被拒绝并提示 `LOW_LIVENESS_SCORE`。", "example": 97.5 }, "user_image": { "type": "object", "description": "所分析图像的人脸检测结果。", "properties": { "entities": { "type": "array", "description": "每张检测到的人脸对应一个条目。未检测到人脸时为空（此时 `age_estimation` 为 `null` 并添加 `AGE_NOT_DETECTED` 警告）。", "items": { "type": "object", "properties": { "age": { "type": "number", "format": "float", "description": "模型估算的人脸年龄（以岁为单位）。", "example": 27.33 }, "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "检测到的人脸边界框，表示为处理后图像中的 `[x_min, y_min, x_max, y_max]` 像素坐标。", "example": [ 40, 40, 100, 100 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "人脸检测置信度（0–1）。", "example": 0.7177750468254089 }, "gender": { "type": "string", "description": "模型预测的检测人脸性别（`male` 或 `female`）。仅供参考。", "example": "male" } } } }, "best_angle": { "type": "integer", "nullable": true, "description": "产生最佳人脸检测结果的旋转角度（度：0、90、180 或 270）。仅当 `rotate_image=true` 纠正了方向时才为非零值。", "example": 0 } } }, "age_estimation": { "type": "number", "format": "float", "nullable": true, "description": "模型预测的检测到的**最大**人脸的年龄（以岁为单位）。当无法估算人脸年龄时为 `null`（会添加 `AGE_NOT_DETECTED` 警告且调用被拒绝）。", "example": 27.33 }, "warnings": { "type": "array", "description": "完全通过审核时为空。任何条目都会将 `status` 设置为 `Declined`。", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "NO_FACE_DETECTED", "LOW_LIVENESS_SCORE", "LIVENESS_FACE_ATTACK", "AGE_NOT_DETECTED", "AGE_BELOW_MINIMUM" ], "description": "机器可读的风险代码。`NO_FACE_DETECTED`：活体检测模型未发现人脸；`LOW_LIVENESS_SCORE`：活体检测 `score` 低于或等于 `face_liveness_score_decline_threshold`；`LIVENESS_FACE_ATTACK`：检测到呈现攻击（照片/屏幕/面具）；`AGE_NOT_DETECTED`：无法估算人脸年龄；`AGE_BELOW_MINIMUM`：估算年龄低于 `age_estimation_decline_threshold`。`NO_FACE_DETECTED` 与 `LOW_LIVENESS_SCORE` 互斥，未检测到人脸时仅返回 `NO_FACE_DETECTED`。" }, "feature": { "type": "string", "enum": [ "LIVENESS" ], "description": "引发该警告的功能。在此 endpoint 上始终为 `LIVENESS`。" }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "对于年龄估算警告始终为 `null`。" }, "log_type": { "type": "string", "enum": [ "error" ], "description": "严重程度。此 endpoint 生成的每个警告均为 `error`，并将 `status` 设置为 `Declined`。" }, "short_description": { "type": "string", "description": "易于阅读的单行风险摘要。" }, "long_description": { "type": "string", "description": "风险的便于人类阅读的说明。" } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，或 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 对象回显，或 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "响应生成时的 ISO 8601 时间戳（UTC）。" } } } } } }, "400": { "description": "验证错误。当 `user_image` 缺失、超过 5 MB、扩展名不受支持，或阈值超出范围时返回。响应体为 DRF 的标准字段错误响应格式：每个有问题的字段对应一个消息数组。", "content": { "application/json": { "examples": { "Missing user image": { "summary": "表单数据中未包含 `user_image`", "value": { "user_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "文件扩展名不在 tiff/jpg/jpeg/png/webp 范围内", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "上传内容超过 5 MB 限制", "value": { "user_image": [ "File size should not exceed 5 MB" ] } }, "Threshold out of range": { "summary": "`face_liveness_score_decline_threshold` 超出 0–100 范围", "value": { "face_liveness_score_decline_threshold": [ "Ensure this value is less than or equal to 100." ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头，或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何图像处理之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/age-estimation/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'age_estimation_decline_threshold=18' \\\n -F 'face_liveness_score_decline_threshold=30' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.age_estimation.estimate(\n user_image=open(\"user_image.jpg\", \"rb\"),\n face_liveness_score_decline_threshold=30.0,\n age_estimation_decline_threshold=18,\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"age-gate\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.ageEstimation.estimate({\n user_image: await fileFromPath(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n age_estimation_decline_threshold: 18,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"age-gate\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AgeEstimation.Estimate(ctx, didit.AgeEstimationEstimateParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tAgeEstimationDeclineThreshold: didit.Int(18),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"age-gate\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.AgeEstimationEstimateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.ageEstimation().estimate(AgeEstimationEstimateParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .faceLivenessScoreDeclineThreshold(30.0)\n .ageEstimationDeclineThreshold(18L)\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"age-gate\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "ageEstimation->estimate([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'face_liveness_score_decline_threshold' => 30.0,\n 'age_estimation_decline_threshold' => 18,\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'age-gate'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.age_estimation.estimate(\n user_image: Pathname(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n age_estimation_decline_threshold: 18,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"age-gate\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.AgeEstimation.EstimateAsync(new AgeEstimationEstimateParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n FaceLivenessScoreDeclineThreshold = 30.0,\n AgeEstimationDeclineThreshold = 18,\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"age-gate\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/poa/": { "post": { "summary": "地址证明（证件 OCR + 地址核验）", "description": "单次调用即可提取并验证地址证明文件（公用事业账单、银行对账单以及政府签发的文件）。返回签发方、签发/到期日期、持有人姓名、原始地址与解析/地理编码后的地址、`Approved`/`Declined` `status`，以及解释所发现每项问题的 `warnings` 列表。\n\n**延迟。**提取基于大语言模型（LLM）：典型调用耗时 **5–15 秒**，多页 PDF 最长约为 **30 秒**。请配置**至少 45 秒**的客户端超时时间，切勿在调用完成前重试。\n\n**工作原理。**证件（图像或 PDF，最大 15 MB；加密 PDF 需要 `document_password`）将被分类为特定证件类型和子类型（例如 `UTILITY_BILL` / `WATER_BILL`），并利用基于 LLM 的提取技术提取签发方、日期、持有人姓名和地址。地址会被解析并进行地理编码存入 `poa_parsed_address`。PDF/EXIF 取证功能会筛查篡改情况（例如数字签名后的修改、已知的 PDF 编辑器、覆盖文本操作、可疑的重新导出），并提示 `SUSPECTED_DOCUMENT_MANIPULATION` 或 `DOCUMENT_METADATA_MISMATCH`。如果某个文本字段被清空并以另一种字体重新输入，而文件本身没有保留其内容是否发生更改的证据，则会提示 `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`。证件时效将根据 `poa_document_age_months` 进行核验，语言将根据 `poa_languages_allowed` 进行核验。如果您传入了 `expected_address`、`expected_country` 或 `expected_first_name`/`expected_last_name`，系统将交叉比对提取的值并标记不匹配项。\n\n**决策逻辑。**除非至少有一个警告导致拒绝，否则 `status` 为 `Approved`。硬性失败始终会导致拒绝：`MISSING_ADDRESS_INFORMATION`、`POA_DOCUMENT_EXPIRED`、`INVALID_DOCUMENT_TYPE`、`UNABLE_TO_VALIDATE_DOCUMENT_AGE`，以及 `UNABLE_TO_EXTRACT_ISSUE_DATE` 和 `POA_NAME_NOT_DETECTED`（在此 endpoint 上不可配置）。五个风险组可通过 `poa_*_action` 选项针对每次请求单独配置（`DECLINE` 或 `NO_ACTION`，默认均为 `DECLINE`）。`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` 和 `UNPARSABLE_OR_INVALID_ADDRESS` 在此 endpoint 上仅作为信息提示，绝不会导致拒绝。完全无法处理的证件返回 `400`；可读取但存在问题的证件返回 `200` 并附带 `status: \"Declined\"`：请务必检查 `poa.status` 和 `poa.warnings`，而不仅仅是 HTTP 状态码。\n\n**计费。**每次 `200` 响应消耗一个地址证明 API 额度（从您的套餐额度或充值余额中扣除）。当组织的余额不足以支付该调用时，endpoint 会在进行任何证件处理之前返回 `403` 及额度不足错误。\n\n**会话持久化（`save_api_request`，默认为 `true`）。**当为 `true` 时，调用将作为 API 类型的会话持久化保存：它会显示在 Business Console 中，上传的证件会被存储，返回的 `request_id` 是真实的会话 ID，您可以将其传递给 `GET /v3/session/{sessionId}/decision/`（该决策还会额外展示此响应中省略的 `document_file` 和 `document_metadata` 取证信息），并触发 `status.updated` Webhook 事件。当为 `false` 时，不会存储任何内容，且 `request_id` 是一次性关联 UUID，后续无法查询。\n\n**沙盒。**沙盒 API 密钥会跳过所有处理和计费：在请求验证通过后（格式错误的输入仍返回 `400`），endpoint 返回静态的 `Approved` 模拟 payload（虚构的“Sandbox Power Co.”电费账单），不会持久化保存会话，也不消耗任何额度。\n\n**认证。**在 `x-api-key` 请求头中发送您应用的 API 密钥。缺失或无效的凭据返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`），此 API 绝不返回 `401`。\n\n**速率限制。**所有 POST/PATCH/DELETE endpoint 共享每个 API 密钥 300 次请求/分钟的写入预算；超出将返回 `429`。\n\n注意：`FUTURE_ISSUE_DATE` 和 `POOR_DOCUMENT_QUALITY` 存在于工作流会话中，但此独立 endpoint 绝不会产生这两项警告：在此处，签发日期为未来的证件不会被自动拒绝。", "operationId": "post_v3poa", "x-didit-sdk": { "resource": "proof_of_address", "method": "verify", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "document" ], "properties": { "document": { "type": "string", "format": "binary", "description": "地址证明文件。允许的扩展名：`tiff`、`jpg`、`jpeg`、`png`、`pdf`、`webp`。最大上传大小：**15 MB**（超出将返回 `400` 拒绝）。支持多页 PDF（延迟可能更高）；加密的 PDF 需要提供 `document_password`。图片在处理前会自动压缩。" }, "document_password": { "type": "string", "description": "当 `document` 为加密 PDF 时用于解密的密码。发送未附带（或附带错误）密码的加密 PDF 将返回 `400`。", "writeOnly": true }, "expected_address": { "type": "string", "description": "用于与证件核对的地址。系统会对该地址进行地理编码并与提取出的地址进行比对；不匹配（或预期地址无法进行地理编码/验证）将添加 `ADDRESS_MISMATCH_WITH_PROVIDED`，受 `poa_address_mismatch_action` 控制。地理编码后的形式将在 `expected_details_formatted_address` / `expected_details_parsed_address` 中回显。", "example": "Av. Monseñor Tavella 1291, Salta, Argentina" }, "expected_country": { "type": "string", "description": "用于与证件核验的国家/地区（ISO 3166-1 代码，例如 `ARG` 或 `AR`）。与证件国家/地区不匹配会添加 `POA_COUNTRY_MISMATCH_WITH_PROVIDED`，受 `poa_address_mismatch_action` 控制。", "example": "ARG" }, "expected_first_name": { "type": "string", "description": "用于与 `name_on_document` 进行核验的名（支持音译的模糊匹配）。低于匹配阈值的分数会添加 `NAME_MISMATCH_WITH_PROVIDED`，受 `poa_address_mismatch_action` 管控。", "example": "Sophia" }, "expected_last_name": { "type": "string", "description": "用于与 `name_on_document` 比对的姓氏，与 `expected_first_name` 结合以计算匹配分数。", "example": "Martinez" }, "poa_languages_allowed": { "type": "string", "description": "以逗号分隔的所接受证件语言的 ISO 639-1 代码列表（例如 `en,es,fr`）。省略或为空时，接受**所有 51 种受支持的语言**。使用列表之外语言的证件会添加 `UNSUPPORTED_DOCUMENT_LANGUAGE`（由 `poa_unsupported_language_action` 控制）；列表中包含未知代码将返回 `400` 以及完整的受支持代码集。", "example": "en,es" }, "poa_document_age_months": { "type": "string", "description": "以逗号分隔的 `key:value` 对，用于按证件类型设置最大证件月龄 — 键：`utility_bill`、`bank_statement`、`government_issued_document`、`other_poa_document`；值：`1`–`120`，或 `-1` 表示无限制（不进行时效检查）。缺省时的默认值：`utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`。超出期限的证件将以 `POA_DOCUMENT_EXPIRED` 拒绝。**注意：**提供此字段时，请列出您接受的*所有*类型 — 未列出的类型将被视为不接受（提示信息 `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`），并跳过其时效检查。", "example": "utility_bill:3,bank_statement:6" }, "poa_name_mismatch_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "已接受但**目前未应用**：姓名不匹配警告（`NAME_MISMATCH_WITH_PROVIDED`）将转而遵循 `poa_address_mismatch_action`。请设置 `poa_address_mismatch_action` 以同时控制姓名和地址的不匹配行为。" }, "poa_document_issues_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "遇到文件完整性问题时的处理操作：实际上该 endpoint 仅生成 `DOCUMENT_METADATA_MISMATCH`。" }, "poa_document_authenticity_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "当怀疑证件被篡改（`SUSPECTED_DOCUMENT_MANIPULATION`）时的处理操作，例如 PDF 在数字签名后被修改、经由已知 PDF 编辑器处理、存在覆盖文本篡改或 EXIF 日期不一致。同时控制 `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`（文件无法证明其是否发生过更改的重新录入文本字段）：`DECLINE` 同样予以拒绝，`NO_ACTION` 将其保留为警告。" }, "poa_unsupported_language_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "当证件语言不在 `poa_languages_allowed` 范围内（`UNSUPPORTED_DOCUMENT_LANGUAGE`）时采取的操作。" }, "poa_address_mismatch_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "当提取的详细信息与 `expected_*` 字段不一致时采取的操作：`ADDRESS_MISMATCH_WITH_PROVIDED`、`NAME_MISMATCH_WITH_PROVIDED` 和 `POA_COUNTRY_MISMATCH_WITH_PROVIDED` 均遵循此操作。" }, "poa_issuer_not_identified_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "当无法在证件上识别出签发公司/组织时的处理操作（`ISSUER_NOT_IDENTIFIED`）。" }, "save_api_request": { "type": "boolean", "default": true, "description": "为 `true`（默认）时，将此次调用持久化为 API 类型的会话：在 Business Console 中可见，可使用返回的 `request_id` 通过 `GET /v3/session/{sessionId}/decision/` 检索，通过 `status.updated` Webhook 发出通知，并存储上传的证件。为 `false` 时，不存储任何内容，且 `request_id` 仅为用于关联响应的临时 UUID。", "example": true }, "vendor_data": { "type": "string", "description": "可选的不透明字符串（您的内部用户 ID、邮箱、UUID 等），存储在持久化会话中并在响应中回显。可用于将 API 调用与您自己的记录相关联，并在稍后筛选会话。", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "与会话一同存储（当 `save_api_request=true` 时）并在响应中原样返回的可选 JSON 对象。在 multipart 请求中，请将其作为 JSON 编码的字符串字段发送（例如 `metadata={\"flow\":\"onboarding\"}`），它将被解析为对象。", "example": { "flow": "onboarding" } } } }, "example": { "document": "(binary JPEG/PNG/PDF of the utility bill or bank statement)", "expected_address": "Av. Monseñor Tavella 1291, Salta, Argentina", "expected_country": "ARG", "expected_first_name": "Sophia", "expected_last_name": "Martinez", "poa_languages_allowed": "en,es", "save_api_request": true, "vendor_data": "user-123" } } } }, "responses": { "200": { "description": "证件已处理。`poa.status` 为 `Approved` 或 `Declined`；检测到的每个问题都在 `poa.warnings` 中逐项列出。过期、不匹配或可疑的证件仍会返回 `200` 并附带 `status: \"Declined\"` — 请检查响应体，而不仅仅是 HTTP 状态码。当 `save_api_request=true` 时，`request_id` 为持久化的会话 ID。", "content": { "application/json": { "examples": { "Approved": { "summary": "水电费账单已清晰读取，不进行预期详细信息检查", "value": { "request_id": "4b523a8d-ed32-45e4-8aa8-a89eda459d88", "poa": { "issuing_state": "ARG", "document_type": "UTILITY_BILL", "document_subtype": "WATER_BILL", "document_language": "es", "issuer": "Aguas del Norte", "issue_date": "2026-04-10", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA", "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina", "poa_parsed_address": { "street_1": "Avenida Monseñor Tavella 1291", "street_2": "b", "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208682, "longitude": -65.4130954 } }, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "name_on_document": "OESTE EMBOTELLADORA S.A.", "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "LA EMBOTELLADORA DEL NORTE SA" ] }, "detected_codes": [ { "type": "QR_CODE", "page_number": 1, "position": [ [ 820, 1120 ], [ 1002, 1120 ], [ 1002, 1302 ], [ 820, 1302 ] ], "x": 820, "y": 1120, "width": 182, "height": 182, "page_width": 1190, "page_height": 1684, "raw_payload": "aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ==", "parsed_payload": "https://aguasdelnorte.com/factura/998811" }, { "type": "CODE_128", "page_number": 1, "position": [ [ 112, 1480 ], [ 560, 1480 ], [ 560, 1540 ], [ 112, 1540 ] ], "x": 112, "y": 1480, "width": 448, "height": 60, "page_width": 1190, "page_height": 1684, "raw_payload": "MDA5OTg4MTEwMDA0Mg==", "parsed_payload": "0099881100042" } ], "status": "Approved", "warnings": [] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:29:02.439655+00:00" } }, "Declined - document too old": { "summary": "签发日期早于允许的 `poa_document_age_months`", "value": { "request_id": "f61681b8-9422-4378-ac3e-04c6a247fb45", "poa": { "issuing_state": "ARG", "document_type": "UTILITY_BILL", "document_subtype": "WATER_BILL", "document_language": "es", "issuer": "Aguas del Norte", "issue_date": "2021-02-10", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA", "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina", "poa_parsed_address": { "street_1": "Avenida Monseñor Tavella 1291", "street_2": "b", "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208682, "longitude": -65.4130954 } }, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "name_on_document": "OESTE EMBOTELLADORA S.A.", "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "LA EMBOTELLADORA DEL NORTE SA" ] }, "status": "Declined", "warnings": [ { "risk": "POA_DOCUMENT_EXPIRED", "feature": "PROOF_OF_ADDRESS", "additional_data": { "expiration_reason": "age_window", "max_age_months": 3, "document_subtype": "WATER_BILL", "document_type": "UTILITY_BILL", "issue_date": "2021-02-10" }, "log_type": "error", "short_description": "Document expired", "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:23:02.165493+00:00" } }, "Declined - name mismatch": { "summary": "`expected_first_name`/`expected_last_name` 与 `name_on_document` 不匹配", "value": { "request_id": "0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21", "poa": { "issuing_state": "ARG", "document_type": "UTILITY_BILL", "document_subtype": "WATER_BILL", "document_language": "es", "issuer": "Aguas del Norte", "issue_date": "2021-02-10", "expiration_date": null, "poa_address": "AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA", "poa_formatted_address": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina", "poa_parsed_address": { "street_1": "Avenida Monseñor Tavella 1291", "street_2": "b", "city": "Salta", "region": "Salta", "country": "AR", "postal_code": "A4400", "document_location": { "latitude": -24.8208682, "longitude": -65.4130954 } }, "expected_details_address": null, "expected_details_formatted_address": null, "expected_details_parsed_address": null, "name_on_document": "OESTE EMBOTELLADORA S.A.", "extra_fields": { "bank_account_number": null, "bank_iban": null, "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "LA EMBOTELLADORA DEL NORTE SA" ] }, "status": "Declined", "warnings": [ { "risk": "NAME_MISMATCH_WITH_PROVIDED", "feature": "PROOF_OF_ADDRESS", "additional_data": null, "log_type": "error", "short_description": "Name mismatch with provided information", "long_description": "The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T02:27:21.330172+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。" }, "poa": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "没有警告判定为拒绝时为 `Approved`；否则为 `Declined`，`warnings` 列表说明了具体原因。" }, "issuing_state": { "type": "string", "nullable": true, "description": "从证件中提取的证件签发国家/地区 — 通常为 ISO 3166-1 alpha-3（例如 `ARG`）。", "example": "ARG" }, "document_type": { "type": "string", "enum": [ "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" ], "description": "检测到的证件类别。`UNKNOWN` 表示该证件无法归类为可接受的地址证明，并会自动拒绝并附带 `INVALID_DOCUMENT_TYPE`。绝不为 null，分类失败将回退为 `UNKNOWN`。" }, "document_subtype": { "type": "string", "description": "`document_type` 内更细粒度的分类，例如 `ELECTRICITY_BILL`、`WATER_BILL`、`GAS_BILL`、`INTERNET_BILL`、`PHONE_BILL`（公共事业账单）；`ACCOUNT_STATEMENT`、`CREDIT_CARD_STATEMENT`（银行对账单）；`TAX_ASSESSMENT`、`RESIDENCY_CERTIFICATE`（政府证件）。无法确定子类型时为 `UNKNOWN`。绝不为 null，分类失败时回退到 `UNKNOWN`。", "example": "WATER_BILL" }, "document_language": { "type": "string", "nullable": true, "description": "检测到的证件语言（ISO 639-1）。", "example": "es" }, "issuer": { "type": "string", "nullable": true, "description": "签发证件的企业或机构。若为 `null` 则会添加 `ISSUER_NOT_IDENTIFIED`。", "example": "Aguas del Norte" }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "证件签发日期（`YYYY-MM-DD`）。无法提取时为 `null` — 在该 endpoint 上会以 `UNABLE_TO_EXTRACT_ISSUE_DATE` 拒绝。", "example": "2021-02-10" }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "证件上印刷的明确到期/有效日期（如存在）。独立于 `poa_document_age_months` 年限检查。" }, "poa_address": { "type": "string", "nullable": true, "description": "与证件上印刷完全一致的地址。`null` 会自动拒绝并提示 `MISSING_ADDRESS_INFORMATION`。" }, "poa_formatted_address": { "type": "string", "nullable": true, "description": "`poa_address` 经过地理编码与规范化后的版本。", "example": "Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina" }, "poa_parsed_address": { "type": "object", "nullable": true, "description": "证件地址的结构化、经地理编码的细分。当地址无法解析时为 `null`。", "properties": { "street_1": { "type": "string", "nullable": true, "example": "Avenida Monseñor Tavella 1291" }, "street_2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true, "example": "Salta" }, "region": { "type": "string", "nullable": true, "example": "Salta" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 国家/地区代码。", "example": "AR" }, "postal_code": { "type": "string", "nullable": true, "example": "A4400" }, "document_location": { "type": "object", "nullable": true, "properties": { "latitude": { "type": "number" }, "longitude": { "type": "number" } }, "description": "证件地址的地理编码坐标。" } } }, "expected_details_address": { "type": "string", "nullable": true, "description": "您发送的 `expected_address` 回显，或 `null`。" }, "expected_details_formatted_address": { "type": "string", "nullable": true, "description": "`expected_address` 的地理编码规范化版本；未提供或无法进行地理编码时为 `null`。" }, "expected_details_parsed_address": { "type": "object", "nullable": true, "additionalProperties": true, "description": "`expected_address` 的完整地理编码结果（街道/城市/地区/国家/地区/邮政编码加上原始地理编码器输出以及 `is_verified` 标志）。未提供 `expected_address` 时为 `null`。" }, "name_on_document": { "type": "string", "nullable": true, "description": "从证件中提取的主要持有人姓名；若提供了 `expected_first_name`/`expected_last_name`，则会与其进行比对。在此 endpoint 上，为 `null` 时会因 `POA_NAME_NOT_DETECTED` 而拒绝。", "example": "OESTE EMBOTELLADORA S.A." }, "extra_fields": { "type": "object", "description": "证件特定的附加信息。银行字段在银行对账单上印有相应信息时填充；否则为 `null`。", "properties": { "bank_account_number": { "type": "string", "nullable": true }, "bank_iban": { "type": "string", "nullable": true }, "bank_sort_code": { "type": "string", "nullable": true }, "bank_routing_number": { "type": "string", "nullable": true }, "bank_swift_bic": { "type": "string", "nullable": true }, "bank_branch_name": { "type": "string", "nullable": true }, "bank_branch_address": { "type": "string", "nullable": true }, "document_phone_number": { "type": "string", "nullable": true, "description": "证件上印有的联系电话号码。" }, "additional_names": { "type": "array", "items": { "type": "string" }, "description": "在证件上找到的其他持有人姓名（例如联名账户持有人、原账户名称）。" } } }, "warnings": { "type": "array", "description": "完全通过审核时为空。每个条目说明一项检测到的风险；包含 `log_type: \"error\"` 的条目会将 `status` 设置为 `Declined`。", "items": { "type": "object", "properties": { "risk": { "type": "string", "description": "机器可读的风险代码。始终拒绝：`MISSING_ADDRESS_INFORMATION`、`POA_DOCUMENT_EXPIRED`、`INVALID_DOCUMENT_TYPE`、`UNABLE_TO_VALIDATE_DOCUMENT_AGE`，以及 `UNABLE_TO_EXTRACT_ISSUE_DATE` 和 `POA_NAME_NOT_DETECTED`（在此 endpoint 上固定为拒绝）。由请求选项控制：`NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED`（`poa_address_mismatch_action`）、`POOR_DOCUMENT_QUALITY`（此 endpoint 从不生成）/ `DOCUMENT_METADATA_MISMATCH`（`poa_document_issues_action`）、`SUSPECTED_DOCUMENT_MANIPULATION` 和 `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`（`poa_document_authenticity_action`）、`UNSUPPORTED_DOCUMENT_LANGUAGE`（`poa_unsupported_language_action`）、`ISSUER_NOT_IDENTIFIED`（`poa_issuer_not_identified_action`）。在此 endpoint 上仅供参考：`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`、`UNPARSABLE_OR_INVALID_ADDRESS`。", "example": "POA_DOCUMENT_EXPIRED" }, "feature": { "type": "string", "enum": [ "PROOF_OF_ADDRESS" ], "description": "引发该警告的功能。在此 endpoint 上始终为 `PROOF_OF_ADDRESS`。" }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "某些风险的额外上下文信息，例如 `POA_DOCUMENT_EXPIRED` 包含 `expiration_reason`（`printed_expiration` 或 `age_window`）、`document_type`、`document_subtype` 和 `issue_date`，此外在 `printed_expiration` 路径下包含 `expiration_date`，在 `age_window` 路径下包含 `max_age_months`；`SUSPECTED_DOCUMENT_MANIPULATION` 包含 `reason` 和 `detection_method`；`POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` 包含 `reason`、`detection_method`（`unproven_text_replacement`）、`replaced_text`、`manipulated_regions` 和 `manipulated_blocks`。对大多数风险为 `null`。" }, "log_type": { "type": "string", "enum": [ "error", "information" ], "description": "严重程度。`error` 警告会导致 `status` 变为 `Declined`；`information` 条目仅供参考，本身绝不会导致拒绝。（此 endpoint 不会产生 `warning`，其选项仅接受 `DECLINE` 或 `NO_ACTION`。）" }, "short_description": { "type": "string", "description": "易于阅读的单行风险摘要。" }, "long_description": { "type": "string", "description": "风险的便于人类阅读的说明。" } } } }, "detected_codes": { "type": "array", "description": "在证件的所有已处理页面中检测到的二维码和条形码。如果未找到任何码则为空。已定位但无法解码的二维码其 `parsed_payload: null`。", "items": { "$ref": "#/components/schemas/DocumentAIDetectedCode" } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，或 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 对象回显，或 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "响应生成时的 ISO 8601 时间戳（UTC）。" } } } } } }, "400": { "description": "验证或处理错误。字段级问题返回 DRF 的标准外层结构（每个出错字段对应一个消息数组）。加密 PDF 问题返回 `{\"detail\": ...}`。提取流水线无法处理的证件返回 `{\"error\": [\"Error extracting POA information\"]}`。", "content": { "application/json": { "examples": { "Missing document": { "summary": "表单数据中未包含 `document`", "value": { "document": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "文件扩展名不在 tiff/jpg/jpeg/png/pdf/webp 范围内", "value": { "document": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp." ] } }, "File too large": { "summary": "上传内容超过 15 MB 限制", "value": { "document": [ "File size should not exceed 15 MB" ] } }, "Encrypted PDF": { "summary": "上传的 PDF 未提供所需密码", "value": { "detail": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Wrong PDF password": { "summary": "`document_password` 无法解密 PDF", "value": { "detail": "The PDF password is incorrect. Please provide the correct password." } }, "Invalid language code": { "summary": "`poa_languages_allowed` 包含不受支持的代码", "value": { "poa_languages_allowed": [ "Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']." ] } }, "Invalid document age value": { "summary": "`poa_document_age_months` 的值超出 1–120 / -1 范围", "value": { "poa_document_age_months": [ "Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120." ] } }, "Extraction failure": { "summary": "提取流水线无法处理该证件", "value": { "error": [ "Error extracting POA information" ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何证件处理之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/poa/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'document=@./utility-bill.pdf' \\\n -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \\\n -F 'expected_country=ARG' \\\n -F 'expected_first_name=Sophia' \\\n -F 'expected_last_name=Martinez' \\\n -F 'poa_languages_allowed=en,es' \\\n -F 'vendor_data=user-123' \\\n --max-time 45" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.proof_of_address.verify(\n document=open(\"document.pdf\", \"rb\"),\n expected_address=\"Av. Monseñor Tavella 1291, Salta, Argentina\",\n expected_country=\"ARG\",\n expected_first_name=\"Sophia\",\n expected_last_name=\"Martinez\",\n poa_languages_allowed=\"en,es\",\n save_api_request=True,\n vendor_data=\"user-123\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.proofOfAddress.verify({\n document: await fileFromPath(\"document.pdf\"),\n expected_address: \"Av. Monseñor Tavella 1291, Salta, Argentina\",\n expected_country: \"ARG\",\n expected_first_name: \"Sophia\",\n expected_last_name: \"Martinez\",\n poa_languages_allowed: \"en,es\",\n save_api_request: true,\n vendor_data: \"user-123\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.ProofOfAddressVerifyParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder()\n .document(Path.of(\"document.pdf\"))\n .expectedAddress(\"Av. Monseñor Tavella 1291, Salta, Argentina\")\n .expectedCountry(\"ARG\")\n .expectedFirstName(\"Sophia\")\n .expectedLastName(\"Martinez\")\n .poaLanguagesAllowed(\"en,es\")\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "proofOfAddress->verify([\n 'document' => File::fromPath('document.pdf'),\n 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina',\n 'expected_country' => 'ARG',\n 'expected_first_name' => 'Sophia',\n 'expected_last_name' => 'Martinez',\n 'poa_languages_allowed' => 'en,es',\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.proof_of_address.verify(\n document: Pathname(\"document.pdf\"),\n expected_address: \"Av. Monseñor Tavella 1291, Salta, Argentina\",\n expected_country: \"ARG\",\n expected_first_name: \"Sophia\",\n expected_last_name: \"Martinez\",\n poa_languages_allowed: \"en,es\",\n save_api_request: true,\n vendor_data: \"user-123\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams\n{\n Document = FileUpload.FromPath(\"document.pdf\"),\n ExpectedAddress = \"Av. Monseñor Tavella 1291, Salta, Argentina\",\n ExpectedCountry = \"ARG\",\n ExpectedFirstName = \"Sophia\",\n ExpectedLastName = \"Martinez\",\n PoaLanguagesAllowed = \"en,es\",\n SaveApiRequest = true,\n VendorData = \"user-123\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/document-ai/": { "post": { "summary": "Document AI（自定义字段提取 + 防篡改检查）", "description": "只需一次调用，即可从任何证明文件（工资单、资金证明、财富来源信函、税单、合同、发票）中提取**您**定义的字段。发送文件以及 `fields` 定义（键、名称、提取指令、类型），即可返回类型化值（`text`、`number`、以 `YYYY-MM-DD` 格式呈现的 `date`）、与预期个人或公司比对的可选的姓名匹配分数、PDF/EXIF 篡改信号、`Approved`/`Declined`/`In Review` `status`，以及说明所发现全部问题的 `warnings` 列表。这是托管 Document AI 工作流步骤（参见 `/core-technology/document-ai/overview`）的服务端对服务端对应功能；它使用 Didit 的默认提取模型，且不提供供应商选择。\n\n**延迟。** 提取基于 LLM：典型调用耗时 **5–15 秒**，多页 PDF 最长可达 **约 30 秒**。请配置**至少 45 秒**的客户端超时，且在调用完成前不要重试。\n\n**请求格式。** 仅限 `multipart/form-data`。`fields` 为**一个经过 JSON 编码的数组字符串**（1–30 项，最多 16 KB）；括号风格的表单数组将被拒绝并返回 `400`。每项均为 `{key, name, instruction, type, required, is_full_name}`，其中 `key` 是返回的 JSON 键（`^[a-z0-9_]{1,64}$`，唯一），`instruction` 指示模型读取什么内容，`type` 为 `text`（默认）| `number` | `date`，当无法读取值时 `required` 会引发 `DOCUMENT_AI_MISSING_REQUIRED_FIELDS`，且最多只能有一个字段设置 `is_full_name: true` 以标记与预期姓名进行比对的值。\n\n**姓名匹配。** 传入 `expected_first_name` + `expected_last_name`（个人）**或** `expected_company_name`（+ 可选的 `expected_company_country`），两者不可同时传入。标记了 `is_full_name` 的字段的值（或者在未标记任何字段时，键名看起来像姓名的第一个文本字段）将进行模糊比对；当双方均存在时，始终返回 `name_match_score`（0–100）和 `name_on_document`，低于 `document_ai_name_match_score_threshold`（默认 80）的分数会添加 `DOCUMENT_AI_NAME_MISMATCH`，受 `document_ai_name_mismatch_action` 控制。\n\n**决策逻辑。** 每种风险对应一个可配置的操作：`DECLINE` → `status: \"Declined\"`，`REVIEW` → `status: \"In Review\"`，`NO_ACTION` → 仅供参考。默认值与工作流步骤一致：无法读取的证件 `REVIEW`、缺失必填字段 `REVIEW`、疑似篡改 `DECLINE`、姓名不匹配 `NO_ACTION`、不支持的文件 `REVIEW`。完全无法处理的证件返回 `400`；可读但存在问题的证件返回带有 `Declined`/`In Review` 的 `200`，请务必检查 `document_ai.status` 和 `document_ai.warnings`，而不仅仅是 HTTP 状态码。\n\n**计费。** 每个 `200` 响应消耗一个 Document AI API 额度，标价为**每份证件 $0.20**，从您的套餐额度或充值余额中扣除。当组织的余额无法支付调用时，endpoint 在进行任何处理之前返回 `403`。沙盒 API 密钥返回确定性的模拟响应且不计费。\n\n**持久化。** 在 `save_api_request=true`（默认）时，调用将作为 API 类型的会话存储：证件、提取的值、字段定义和姓名匹配快照均予以保留，会话显示在 Business Console 中，并且 `request_id` 可用于 `GET /v3/session/{sessionId}/decision/`。", "operationId": "post_v3document-ai", "x-didit-sdk": { "resource": "document_ai", "method": "analyze", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "document", "fields" ], "properties": { "document": { "type": "string", "format": "binary", "description": "要读取的证件。允许的扩展名：`tiff`、`jpg`、`jpeg`、`png`、`pdf`、`webp`、`zip`。最大上传大小：**30 MB**（超出限制的文件将被拒绝并返回 `400`）。支持多页 PDF（延迟可能会更高）；加密的 PDF 将被拒绝并返回 `400`。图像在处理前会自动压缩。" }, "fields": { "type": "string", "description": "包含 **1–30** 个字段定义的单个 JSON 编码数组字符串（最大 16 KB）。每个项目：`key`（必填，`^[a-z0-9_]{1,64}$`，唯一：在 `extracted_data` 中返回的键）、`name`（≤100 个字符，在消息中显示）、`instruction`（≤500 个字符，模型应读取的内容）、`type`（默认 `text` | `number` | `date`）、`required`（布尔值，默认 `false`）、`is_full_name`（布尔值，默认 `false`，每个请求最多一个）。括号风格的表单数组、无效 JSON、重复键或多个 `is_full_name` 将在任何处理或计费之前返回 `400`。", "example": "[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]" }, "expected_first_name": { "type": "string", "description": "用于与证件的姓名字段进行核验的名（支持音译的模糊匹配）。与 `expected_last_name` 一起使用；不能与 `expected_company_name` 组合。", "example": "Sophia" }, "expected_last_name": { "type": "string", "description": "用于与证件的姓名字段比对的姓氏，与 `expected_first_name` 结合以计算 `name_match_score`。", "example": "Martinez" }, "expected_company_name": { "type": "string", "description": "要与证件上的名称字段进行核验的企业名称（适用于企业证件）。不能与 `expected_first_name` / `expected_last_name` 同时使用（特意未提供示例值，生成的请求示例使用个人字段；核验企业证件时请将其替换为本字段）。" }, "expected_company_country": { "type": "string", "description": "可选的 ISO 3166-1 alpha-2 国家/地区代码（两个 ASCII 字母，例如 `FR`），用于针对 `expected_company_name` 调整公司名称规范化。仅与 `expected_company_name` 一同使用。" }, "document_ai_name_match_score_threshold": { "type": "integer", "minimum": 0, "maximum": 100, "default": 80, "description": "认定姓名匹配的最低 `name_match_score`（0–100）。低于此分值将添加 `DOCUMENT_AI_NAME_MISMATCH`，受 `document_ai_name_mismatch_action` 控制。", "example": 80 }, "document_ai_unreadable_document_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "REVIEW", "description": "当无法从证件中读取任何字段时的处理操作（`DOCUMENT_AI_UNREADABLE_DOCUMENT`）。" }, "document_ai_missing_required_fields_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "REVIEW", "description": "当至少有一个 `required` 字段无法读取时的处理操作（`DOCUMENT_AI_MISSING_REQUIRED_FIELDS`；`additional_data.missing_fields` 列出了这些字段）。" }, "document_ai_document_tampering_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "DECLINE", "description": "当 PDF/EXIF 取证怀疑存在篡改（数字签名后被修改、已知的 PDF 编辑器、覆盖文本篡改、可疑的重新导出、图像异常）时的处理操作（`DOCUMENT_AI_SUSPECTED_MANIPULATION`）。" }, "document_ai_name_mismatch_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "NO_ACTION", "description": "当 `name_match_score` 低于阈值时的处理操作（`DOCUMENT_AI_NAME_MISMATCH`）。" }, "document_ai_unsupported_file_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ], "default": "REVIEW", "description": "当上传内容为空或不是可处理的文件（`DOCUMENT_AI_UNSUPPORTED_FILE`）时采取的操作。" }, "save_api_request": { "type": "boolean", "default": true, "description": "为 `true`（默认）时，将此次调用持久化为 API 类型的会话，在 Business Console 中可见，可使用返回的 `request_id` 通过 `GET /v3/session/{sessionId}/decision/` 检索，并存储上传的证件、提取的值、字段定义以及姓名比对快照。为 `false` 时，不存储任何内容，`request_id` 仅为用于关联响应的临时 UUID；该调用仍会计费。", "example": true }, "vendor_data": { "type": "string", "description": "可选的不透明字符串（您的内部用户 ID、邮箱、UUID 等），存储在持久化会话中并在响应中回显。可用于将 API 调用与您自己的记录相关联，并在稍后筛选会话。", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "与会话一同存储（当 `save_api_request=true` 时）并在响应中原样返回的可选 JSON 对象。在 multipart 请求中，请将其作为 JSON 编码的字符串字段发送（例如 `metadata={\"flow\":\"onboarding\"}`），它将被解析为对象。", "example": { "flow": "onboarding" } } } } } } }, "responses": { "200": { "description": "证件已处理。`document_ai.status` 为 `Approved`、`Declined` 或 `In Review`；检测到的每个问题都在 `document_ai.warnings` 中逐项列出。有问题的证件仍会返回 `200` — 请检查响应体，而不仅仅是 HTTP 状态码。当 `save_api_request=true` 时，`request_id` 为持久化的会话 ID。", "content": { "application/json": { "examples": { "Approved": { "summary": "工资单读取无误，姓名已匹配", "value": { "request_id": "9d6a3b1e-2f0c-4a8e-9b7d-1c2e3f4a5b6c", "document_ai": { "status": "Approved", "extracted_data": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": 3120.5, "pay_date": "2026-07-31" }, "detected_codes": [ { "type": "CODE_128", "page_number": 1, "position": [ [ 96, 456 ], [ 96, 616 ], [ 1012, 611 ], [ 1015, 456 ] ], "x": 96, "y": 456, "width": 919, "height": 160, "page_width": 1200, "page_height": 1700, "raw_payload": "SU5WLTIwMjYtMDA0Mg==", "parsed_payload": "INV-2026-0042" } ], "fields": [ { "key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false }, { "key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true }, { "key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false }, { "key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false } ], "name_match_score": 100.0, "name_on_document": "Sophia Martinez", "warnings": [] }, "vendor_data": "user-123", "metadata": { "flow": "onboarding" }, "created_at": "2026-08-19T16:40:12.318Z" } }, "In Review — missing required field": { "summary": "无法读取 `net_pay`；默认操作为 REVIEW", "value": { "request_id": "3f2a9c7b-5d4e-4b1a-8c6f-0e9d8c7b6a5f", "document_ai": { "status": "In Review", "extracted_data": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": null, "pay_date": "2026-07-31" }, "detected_codes": [], "fields": [ { "key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false }, { "key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true }, { "key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false }, { "key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false } ], "name_match_score": 100.0, "name_on_document": "Sophia Martinez", "warnings": [ { "risk": "DOCUMENT_AI_MISSING_REQUIRED_FIELDS", "feature": "DOCUMENT_AI", "additional_data": { "missing_fields": [ "Net pay" ] }, "log_type": "warning", "short_description": "Required fields could not be extracted", "long_description": "One or more fields configured as required could not be extracted from the uploaded document." } ] }, "vendor_data": null, "metadata": null, "created_at": "2026-08-19T16:41:05.002Z" } }, "Declined — suspected manipulation": { "summary": "PDF 取证标记了已知的编辑器；默认操作 DECLINE", "value": { "request_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "document_ai": { "status": "Declined", "extracted_data": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": 3120.5, "pay_date": "2026-07-31" }, "detected_codes": [], "fields": [ { "key": "employer_name", "name": "Employer name", "instruction": "The employer or company issuing the payslip.", "type": "text", "required": true, "is_full_name": false }, { "key": "employee_name", "name": "Employee name", "instruction": "The full name of the employee as printed on the payslip.", "type": "text", "required": true, "is_full_name": true }, { "key": "net_pay", "name": "Net pay", "instruction": "The net amount paid to the employee for the period.", "type": "number", "required": true, "is_full_name": false }, { "key": "pay_date", "name": "Pay date", "instruction": "The payment date shown on the payslip.", "type": "date", "required": false, "is_full_name": false } ], "name_match_score": null, "name_on_document": "Sophia Martinez", "warnings": [ { "risk": "DOCUMENT_AI_SUSPECTED_MANIPULATION", "feature": "DOCUMENT_AI", "additional_data": { "detection_method": "known_editor", "processed_by_known_editor": "ilovepdf" }, "log_type": "error", "short_description": "Suspected document manipulation", "long_description": "The system detected signs of potential manipulation or editing in the uploaded document." } ] }, "vendor_data": null, "metadata": null, "created_at": "2026-08-19T16:42:40.771Z" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。" }, "document_ai": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "没有警告判定为拒绝或审核时为 `Approved`；至少有一个风险映射到 `DECLINE` 时为 `Declined`；否则当至少有一个映射到 `REVIEW` 时为 `In Review`。`warnings` 列表说明了具体原因。" }, "extracted_data": { "type": "object", "additionalProperties": true, "description": "每个请求的字段键对应一个条目。值根据字段 `type` 确定类型（`text` 为字符串，`number` 为数字，`date` 为 `YYYY-MM-DD` 格式的字符串），当无法读取值时为 `null`。", "example": { "employer_name": "Acme Payments Ltd", "employee_name": "Sophia Martinez", "net_pay": 3120.5, "pay_date": "2026-07-31" } }, "detected_codes": { "type": "array", "description": "在所有已处理页面中检测到的二维码和条形码。未找到时为空。已定位但无法解码的二维码其 `parsed_payload: null`。", "items": { "$ref": "#/components/schemas/DocumentAIDetectedCode" } }, "fields": { "type": "array", "description": "本次提取所使用的标准化字段定义，原样返回（当 `save_api_request=true` 时也会随会话一同存储）。", "items": { "type": "object", "properties": { "key": { "type": "string" }, "name": { "type": "string" }, "instruction": { "type": "string" }, "type": { "type": "string", "enum": [ "text", "number", "date" ] }, "required": { "type": "boolean" }, "is_full_name": { "type": "boolean" } } } }, "name_match_score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 100, "description": "`name_on_document` 与预期的个人/企业名称之间的模糊相似度（0–100）。只要名称值与预期名称均存在即会返回，无论匹配**还是**不匹配；否则为 `null`。", "example": 96.0 }, "name_on_document": { "type": "string", "nullable": true, "description": "从证件中提取并与预期姓名进行比对的姓名值（`is_full_name` 字段，或首个类似姓名的文本字段）。无可用的姓名值时为 `null`。", "example": "Sophia Martinez" }, "warnings": { "type": "array", "description": "完全通过审核时为空。每个条目说明一项检测到的风险；包含 `log_type: \"error\"` 的条目会将 `status` 设置为 `Declined`，包含 `log_type: \"warning\"` 的条目会将其设置为 `In Review`。", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "DOCUMENT_AI_UNREADABLE_DOCUMENT", "DOCUMENT_AI_MISSING_REQUIRED_FIELDS", "DOCUMENT_AI_SUSPECTED_MANIPULATION", "DOCUMENT_AI_NAME_MISMATCH", "DOCUMENT_AI_UNSUPPORTED_FILE" ], "description": "机器可读的风险代码。每一项均由匹配的 `document_ai_*_action` 请求选项控制。", "example": "DOCUMENT_AI_MISSING_REQUIRED_FIELDS" }, "feature": { "type": "string", "enum": [ "DOCUMENT_AI" ], "description": "引发该警告的功能。在此 endpoint 上始终为 `DOCUMENT_AI`。" }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "风险的额外上下文：缺少必填字段时为 `{\"missing_fields\": [\"Net pay\"]}`，姓名不匹配时为 `{\"name_on_document\", \"score\", \"threshold\"}`，涉嫌篡改时为鉴伪检测结果（`detection_method`、制作软件/编辑者详情）。无可补充内容时为 `null`。", "example": { "missing_fields": [ "Net pay" ] } }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "根据配置的操作派生的严重程度：`error`（DECLINE）、`warning`（REVIEW）、`information`（NO_ACTION）。" }, "short_description": { "type": "string", "description": "易于阅读的单行风险概述。", "example": "Required fields could not be extracted" }, "long_description": { "type": "string", "description": "便于人类阅读的说明，在相关位置插入 `additional_data`。" } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，或 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 对象回显，或 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "请求处理的时间（UTC，ISO 8601）。" } } } } } }, "400": { "description": "验证或处理错误。字段级问题返回 DRF 的标准外层结构（每个出错字段对应一个消息数组）。加密或无法读取的证件以及提取失败返回 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing document": { "summary": "表单数据中未包含 `document`", "value": { "document": [ "No file was submitted." ] } }, "Invalid fields payload": { "summary": "`fields` 不是一个 JSON 编码的数组字符串", "value": { "fields": [ "fields must be a valid JSON array string." ] } }, "Duplicate field keys": { "summary": "两个项目共享相同的 `key`", "value": { "fields": [ "Every fields item must have a unique key." ] } }, "Conflicting expectations": { "summary": "个人与企业预期信息一同发送", "value": { "non_field_errors": [ "Provide either person expected-name fields or expected_company_name, not both." ] } }, "Invalid metadata": { "summary": "`metadata` 不是 JSON 对象（或包含 NUL 字符）", "value": { "metadata": [ "Metadata must be a JSON object." ] } }, "Oversized vendor_data": { "summary": "`vendor_data` 超过 2,000 字节上限", "value": { "vendor_data": [ "vendor_data is too long (maximum 2000 bytes)." ] } }, "Encrypted PDF": { "summary": "受密码保护的 PDF", "value": { "error": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Extraction failed": { "summary": "提取流水线无法处理该证件", "value": { "error": [ "Error extracting Document AI information" ] } } }, "schema": { "type": "object", "additionalProperties": true } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足，以及费率表中未包含 Document AI API 条目的合同计费组织，均会在进行任何证件处理之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } }, "Contract rate missing": { "summary": "按合同计费的组织，其费率表中没有 Document AI API 条目", "value": { "error": "Document AI API is not included in your contract rate card. Contact support@didit.me to enable it." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "error": { "type": "string" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.document_ai.analyze(\n document=open(\"document.pdf\", \"rb\"),\n fields=\"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.documentAi.analyze({\n document: await fileFromPath(\"document.pdf\"),\n fields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DocumentAi.Analyze(ctx, didit.DocumentAiAnalyzeParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tFields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.DocumentAiAnalyzeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.documentAi().analyze(DocumentAiAnalyzeParams.builder()\n .document(Path.of(\"document.pdf\"))\n .fields(\"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "documentAi->analyze([\n 'document' => File::fromPath('document.pdf'),\n 'fields' => '[{\"key\": \"employer_name\", \"name\": \"Employer name\", \"instruction\": \"The employer or company issuing the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": false}, {\"key\": \"employee_name\", \"name\": \"Employee name\", \"instruction\": \"The full name of the employee as printed on the payslip.\", \"type\": \"text\", \"required\": true, \"is_full_name\": true}, {\"key\": \"net_pay\", \"name\": \"Net pay\", \"instruction\": \"The net amount paid to the employee for the period.\", \"type\": \"number\", \"required\": true, \"is_full_name\": false}, {\"key\": \"pay_date\", \"name\": \"Pay date\", \"instruction\": \"The payment date shown on the payslip.\", \"type\": \"date\", \"required\": false, \"is_full_name\": false}]',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.document_ai.analyze(\n document: Pathname(\"document.pdf\"),\n fields: \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.DocumentAi.AnalyzeAsync(new DocumentAiAnalyzeParams\n{\n Document = FileUpload.FromPath(\"document.pdf\"),\n Fields = \"[{\\\"key\\\": \\\"employer_name\\\", \\\"name\\\": \\\"Employer name\\\", \\\"instruction\\\": \\\"The employer or company issuing the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"employee_name\\\", \\\"name\\\": \\\"Employee name\\\", \\\"instruction\\\": \\\"The full name of the employee as printed on the payslip.\\\", \\\"type\\\": \\\"text\\\", \\\"required\\\": true, \\\"is_full_name\\\": true}, {\\\"key\\\": \\\"net_pay\\\", \\\"name\\\": \\\"Net pay\\\", \\\"instruction\\\": \\\"The net amount paid to the employee for the period.\\\", \\\"type\\\": \\\"number\\\", \\\"required\\\": true, \\\"is_full_name\\\": false}, {\\\"key\\\": \\\"pay_date\\\", \\\"name\\\": \\\"Pay date\\\", \\\"instruction\\\": \\\"The payment date shown on the payslip.\\\", \\\"type\\\": \\\"date\\\", \\\"required\\\": false, \\\"is_full_name\\\": false}]\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/aml/": { "post": { "summary": "AML 筛查（独立）", "operationId": "post_v3aml", "x-didit-sdk": { "resource": "aml", "method": "screen", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "可选的重试安全密钥，最多 255 个字符。使用相同的请求体复用同一密钥将返回原始响应，而不会执行第二次筛查或重复计费。使用不同的请求体复用该密钥将返回 `409`。", "schema": { "type": "string", "maxLength": 255 } } ], "description": "通过单次调用筛查个人或企业是否属于 PEP，以及是否列入制裁、警告/观察名单和负面新闻数据集。\n\n**双分数模型。** 每个命中结果均包含一个 `match_score`（0-100，身份置信度）和一个 `risk_score`（0-100，实体风险）。`match_score` 低于 `aml_match_score_threshold`（默认 **93**）的命中项会被标记为 `review_status: \"False Positive\"` 并在计算风险时予以忽略；其余命中项中的最高 `risk_score` 将作为 `aml.score`。最终的 `aml.status` 取决于您的阈值配置：`score` > `aml_score_review_threshold`（默认 **100**）→ `Declined`；`score` > `aml_score_approve_threshold`（默认 **80**）→ `In Review`；否则为 `Approved`。每当 `score` 非零且 ≥ 通过阈值时，系统会添加 `POSSIBLE_MATCH_FOUND` 警告（分值恰好为 0 时绝不触发警告）。\n\n**匹配分数权重。** `aml_name_weight` + `aml_dob_weight` + `aml_country_weight` 的总和必须恰好为 100（默认分别为 60/25/15）。请求中缺失的组成部分将被排除，并对剩余组成部分的权重重新归一化；匹配的 `document_number` 将作为金钥，直接将 `match_score` 覆盖为 100。\n\n**延迟。** 普通筛查通常在几秒钟内完成。如果设置了 `include_adverse_media=true`，API 会等待负面新闻丰富化（初始暂停约 5 秒，外加最长约 25 秒的轮询），请将客户端超时时间配置为**至少 60 秒**。\n\n**持久化。** `save_api_request` 默认为 **true**：筛查结果将作为会话存储（`request_id` 可用于 `GET /v3/session/{sessionId}/decision/`），该记录会显示在控制台中，触发 `status.updated` Webhook，且后续可以更新命中项的审核状态。若 `save_api_request=false`，则不存储任何内容，`request_id` 仅作为临时关联 ID。`include_ongoing_monitoring=true` 会对该档案持续进行重新筛查，且必须设置 `save_api_request=true`（否则强制返回 `400`）。\n\n**幂等性。** 在发生超时或暂时性错误后重试时，请发送 `Idempotency-Key` 请求头。该密钥的作用域限定在您的应用和完全相同的请求体。首个完成的请求会存储其响应；后续相同的重试将返回相同的响应，不会执行也不会对另一笔 AML 筛查计费。如果原始请求仍在运行，请稍后使用相同的密钥重试。如果相同的密钥与不同的请求体一起重复使用，API 将返回 `409`。\n\n**计费。** 首次成功筛查后将扣除一个 AML API 额度。重放的幂等响应不会再次扣费；余额不足时，系统会在执行任何新筛查之前返回 `403`。\n\n**沙盒。** 沙盒应用的密钥会完全跳过筛查和计费，并返回模拟结果：除非您传入 `sandbox_scenario`，否则均为 0 个命中项的 `Approved`。`save_api_request` 在沙盒密钥上的表现与生产环境密钥相同，因此保存的沙盒筛查可以通过 `GET /v3/session/{sessionId}/decision/` 和 `GET /v3/session/{sessionId}/generate-pdf/` 检索。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "full_name" ], "properties": { "full_name": { "type": "string", "minLength": 2, "description": "待筛查个人或企业的姓名。最少 **2 个字符**，此为筛查服务商自身的最低限制。在执行任何筛查之前，较短或空白的名称会使该字段返回 `400`，因此不会产生任何计费。", "example": "Antonio Ejemplo Modelo" }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "default": "person", "description": "要筛查的实体类型。默认为 `person`。" }, "date_of_birth": { "type": "string", "format": "date", "description": "出生日期（自然人）或成立日期（企业），`YYYY-MM-DD`。通过出生日期权重提高匹配精度。", "example": "1972-02-29" }, "nationality": { "type": "string", "description": "ISO 3166-1 **alpha-2** 国家/地区代码（例如 `ES`）。无效代码返回 `400`。通过国家/地区权重提高匹配精度。", "example": "ES" }, "document_number": { "type": "string", "description": "身份证件号码。不设权重 — 充当黄金密钥：完全匹配会将命中的 `match_score` 覆盖为 100，严重不匹配则会对其进行惩罚扣分。仅当长度为 **2-50 个字符**时，才会作为搜索过滤器发送给筛查提供商；超出该范围的值会被接受并存储，筛查仍会运行并计费，只是不会按证件号码缩小范围。" }, "aml_score_approve_threshold": { "type": "number", "minimum": 0, "maximum": 100, "default": 80, "description": "判定结果为 `Approved` 的风险评分阈值（小于或等于该值）。必须 ≤ `aml_score_review_threshold`（否则返回 `400`）。" }, "aml_score_review_threshold": { "type": "number", "minimum": 0, "maximum": 100, "default": 100, "description": "判定结果为 `Declined` 的风险评分阈值上限。介于两个阈值之间的分数将产生 `In Review`。" }, "aml_name_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 60, "description": "姓名相似度在单次命中匹配分数中的权重。这三个权重相加必须正好为 100（否则返回 `400`）。" }, "aml_dob_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 25, "description": "出生日期在单次命中匹配分数中的权重。" }, "aml_country_weight": { "type": "integer", "minimum": 0, "maximum": 100, "default": 15, "description": "国家/地区/国籍在单次命中匹配分数中的权重。" }, "aml_match_score_threshold": { "type": "integer", "minimum": 0, "maximum": 100, "default": 93, "description": "逐条命中的截断阈值：`match_score` 低于此值的命中标注为 `False Positive`（不计入风险评估）；等于或高于此值的为 `Unreviewed` 疑似匹配项。" }, "include_adverse_media": { "type": "boolean", "default": false, "description": "同时在新闻媒体中搜索负面报道。汇总结果时最多增加约 30 秒延迟 — 请使用 ≥60 秒的客户端超时时间。" }, "include_ongoing_monitoring": { "type": "boolean", "default": false, "description": "持续对此档案重新筛查并通过 Webhook 推送变更。需要 `save_api_request=true`（否则返回 `400`）。" }, "save_api_request": { "type": "boolean", "default": true, "description": "将筛查持久化为会话（控制台可见性、决策 endpoint、Webhook、命中审核）。设为 `false` 则执行无状态检查。" }, "vendor_data": { "type": "string", "description": "您为被筛查用户指定的标识符；将原样返回并与会话一起存储。" }, "metadata": { "type": "object", "nullable": true, "description": "随请求一同存储并回显的自由格式 JSON。" }, "sandbox_scenario": { "type": "string", "description": "仅限沙盒的场景标识（slug）。仅在 API 密钥属于沙盒模式应用时被接受；在生产环境应用上会被拒绝。独立筛查没有需要配置的会话，因此 slug 直接置于筛查请求本身：`decline_aml_hit` 返回一个具有生产环境格式的命中并将筛查判定为 `Declined`，`review_aml_possible_match` 将其判定为 `In Review`，而不触发 AML 结果的场景将使筛查保持无命中。请参阅 GET /v1/sandbox/scenarios/ 中的场景目录或[沙盒与测试数据](/zh/integration/sandbox-testing)。", "example": "decline_aml_hit" } } }, "example": { "full_name": "Antonio Ejemplo Modelo", "entity_type": "person", "date_of_birth": "1972-02-29", "nationality": "ES", "include_adverse_media": false, "vendor_data": "user-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/aml/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -H 'Idempotency-Key: aml-user-1234-2026-08-20' \\\n -d '{\n \"full_name\": \"Antonio Ejemplo Modelo\",\n \"entity_type\": \"person\",\n \"date_of_birth\": \"1972-02-29\",\n \"nationality\": \"ES\",\n \"include_adverse_media\": false,\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.aml.screen(\n full_name=\"Antonio Ejemplo Modelo\",\n entity_type=\"person\",\n date_of_birth=\"1972-02-29\",\n nationality=\"ES\",\n include_adverse_media=False,\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.aml.screen({\n full_name: \"Antonio Ejemplo Modelo\",\n entity_type: \"person\",\n date_of_birth: \"1972-02-29\",\n nationality: \"ES\",\n include_adverse_media: false,\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AML.Screen(ctx, didit.AMLScreenParams{\n\tFullName: \"Antonio Ejemplo Modelo\",\n\tEntityType: didit.Some(didit.AMLScreenParamsEntityType(\"person\")),\n\tDateOfBirth: didit.String(\"1972-02-29\"),\n\tNationality: didit.String(\"ES\"),\n\tIncludeAdverseMedia: didit.Bool(false),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport me.didit.Didit;\nimport me.didit.types.AmlScreenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.aml().screen(AmlScreenParams.builder()\n .fullName(\"Antonio Ejemplo Modelo\")\n .entityType(AmlScreenParams.EntityType.of(\"person\"))\n .dateOfBirth(LocalDate.parse(\"1972-02-29\"))\n .nationality(\"ES\")\n .includeAdverseMedia(false)\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "aml->screen([\n 'full_name' => 'Antonio Ejemplo Modelo',\n 'entity_type' => 'person',\n 'date_of_birth' => '1972-02-29',\n 'nationality' => 'ES',\n 'include_adverse_media' => false,\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.aml.screen(\n full_name: \"Antonio Ejemplo Modelo\",\n entity_type: \"person\",\n date_of_birth: \"1972-02-29\",\n nationality: \"ES\",\n include_adverse_media: false,\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Aml.ScreenAsync(new AmlScreenParams\n{\n FullName = \"Antonio Ejemplo Modelo\",\n EntityType = new AmlScreenParamsEntityType(\"person\"),\n DateOfBirth = \"1972-02-29\",\n Nationality = \"ES\",\n IncludeAdverseMedia = false,\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "筛查已完成。`aml.status` 反映您的阈值设置；达到或高于内部收录下限的每个命中项都会列在 `aml.hits` 中，并带有其身份 `match_score`、实体 `risk_score` 以及解释匹配原因的 `score_breakdown`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。" }, "aml": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "当 `score` > `aml_score_review_threshold` 时为 `Declined`；当 `score` > `aml_score_approve_threshold` 时为 `In Review`；否则为 `Approved`（包括没有可用分数的情况）。" }, "total_hits": { "type": "integer", "description": "`hits` 中的条目数量。" }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "回显筛查的实体类型。" }, "hits": { "type": "array", "items": { "type": "object", "description": "一个筛查命中项。`match_score` (0–100) 用于衡量身份置信度：低于 `aml_match_score_threshold` 的命中项会被标记为 `review_status: \"False Positive\"` 并从风险评估中排除；等于或高于该阈值的命中项则为 `\"Unreviewed\"` 的可能匹配。`risk_score` (0–100) 用于衡量匹配实体的风险程度，并决定顶层的 `aml.score`。", "properties": { "id": { "type": "string", "nullable": true, "description": "Didit 对命中的稳定标识符：`hit_` 后跟 24 个十六进制字符。再次对主体进行筛查时，相同的匹配实体保留相同的 `id`。在调用 AML 命中审核 endpoint 时作为 `hit_id` 传递。" }, "url": { "type": "string", "nullable": true, "description": "匹配实体的来源 URL（如有）。" }, "match": { "type": "boolean", "nullable": true, "description": "旧版精确匹配标志。建议优先使用 `match_score` + `review_status`。" }, "score": { "type": "number", "nullable": true, "description": "已弃用的加权匹配分数，范围为 0–1。请改用 `match_score`。" }, "match_score": { "type": "number", "nullable": true, "description": "身份置信度（0–100）。与 `aml_match_score_threshold` 进行比对，以区分误报与可能匹配。" }, "risk_score": { "type": "number", "nullable": true, "description": "主体风险评分（0–100）。非误报命中项中的最高 `risk_score` 将成为顶层的 `aml.score`。" }, "target": { "type": "boolean", "nullable": true }, "caption": { "type": "string", "nullable": true, "description": "匹配实体的显示名称。" }, "datasets": { "type": "array", "nullable": true, "items": { "type": "string", "enum": [ "PEP", "PEP Level 1", "PEP Level 2", "PEP Level 3", "PEP Level 4", "Sanctions", "Adverse Media", "Warnings and Regulatory Enforcement", "Fitness and Probity", "SIP", "SIE", "Insolvency", "Other Lists" ] }, "description": "实体被列入的风险类别：`PEP`（及其级别，`PEP Level 1` 至 `PEP Level 4`）、`Sanctions`、`Adverse Media`、`Warnings and Regulatory Enforcement`、`Fitness and Probity`、`SIP`、`SIE` 或 `Insolvency`。当实体的数据来源未指明上述任何类别时，为 `Other Lists`。" }, "features": { "type": "object", "nullable": true }, "properties": { "type": "object", "nullable": true, "description": "主体档案：`name`、`alias`、`notes`、`gender`、`birthDate`、`birthPlace`、`nationality`、`position` 以及其他传记信息数组（均可为空）。" }, "rca_name": { "type": "string", "nullable": true, "description": "当命中为 RCA 时，用于匹配该实体的相关密切关联人姓名。" }, "pep_matches": { "type": "array", "description": "作为此命中依据的政治公众人物名单条目。", "items": { "type": "object", "properties": { "list_name": { "type": "string" }, "publisher": { "type": "string" }, "source_url": { "type": "string" }, "description": { "type": "string" }, "matched_name": { "type": "string" }, "pep_position": { "type": "string" }, "date_of_birth": { "type": "string" }, "place_of_birth": { "type": "string" }, "aliases": { "type": "array", "items": { "type": "string" } }, "education": { "type": "array", "items": { "type": "string" } }, "other_sources": { "type": "array", "items": { "type": "string" } } } } }, "sanction_matches": { "type": "array", "items": { "type": "object" }, "description": "支持此命中的制裁名单条目（底层名单结构与 `pep_matches` 相同，外加制裁专有字段）。" }, "warning_matches": { "type": "array", "items": { "type": "object" }, "description": "支持此命中的警告/观察名单条目。" }, "adverse_media_matches": { "type": "array", "description": "负面新闻报道。仅在 `include_adverse_media=true` 时填充。", "items": { "type": "object", "properties": { "headline": { "type": "string" }, "summary": { "type": "string" }, "sentiment": { "type": "string" }, "sentiment_score": { "type": "number" }, "source_url": { "type": "string" }, "thumbnail": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "author_name": { "type": "string", "nullable": true }, "publication_date": { "type": "string", "nullable": true }, "adverse_keywords": { "type": "array", "items": { "type": "string" } }, "other_sources": { "type": "array", "items": { "type": "string" } } } } }, "adverse_media_details": { "type": "object", "nullable": true, "description": "实体的负面新闻情感汇总（`sentiment`、`sentiment_score`、`adverse_keywords` 频率映射）。仅在 `include_adverse_media=true` 时填充。" }, "first_seen": { "type": "string", "format": "date-time", "nullable": true, "description": "实体首次出现在数据集中的时间。" }, "last_seen": { "type": "string", "format": "date-time", "nullable": true, "description": "包含该实体的最新数据集刷新。" }, "linked_entities": { "type": "array", "description": "匹配实体的已知关联关系（家族、关联人、关联公司）。", "items": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string" } }, "relation": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "details": { "type": "array", "items": { "type": "string" } }, "active": { "type": "array", "items": { "type": "string" } } } } }, "risk_view": { "type": "object", "nullable": true, "description": "按维度划分的风险明细（`crimes`、`countries`、`categories`、`custom_list`），每个维度均包含 `score`、`weightage`、`risk_level` 以及一个 `risk_scores` 映射。" }, "additional_information": { "type": "object", "nullable": true, "description": "自由格式的额外上下文，例如解释实体为何被标记的 `flag_summary` 数组。" }, "review_status": { "type": "string", "nullable": true, "enum": [ "False Positive", "Unreviewed", "Confirmed Match", "Inconclusive" ], "description": "`False Positive` — `match_score` 低于 `aml_match_score_threshold`，已从风险评估中排除。`Unreviewed` — 等待审核的可能匹配项。`Confirmed Match` / `Inconclusive` — 由审核员（通过 Business Console）针对已保存的会话手动设置；该审核功能不属于本规范的一部分。" }, "score_breakdown": { "type": "object", "nullable": true, "description": "`match_score` 的计算方式。姓名、出生日期和国家/地区各自贡献 `_score` × `_weight_normalized` 分；当筛查数据中缺少某个组件时，权重会重新归一化。证件号码不参与加权，它充当“金钥”：`MATCH` 会将分数直接覆盖为 100，`NEUTRAL` 保持分数不变，`HARD_MISMATCH` 会施加惩罚扣分。", "properties": { "name_score": { "type": "integer", "nullable": true, "description": "原始姓名相似度（0–100）。" }, "name_weight": { "type": "integer", "nullable": true, "description": "配置的姓名权重（`aml_name_weight`）。" }, "name_weight_normalized": { "type": "number", "nullable": true, "description": "重新归一化后的名称权重（0–100）。" }, "name_contribution": { "type": "number", "nullable": true, "description": "姓名对 `total_score` 的贡献点数。" }, "dob_score": { "type": "integer", "nullable": true, "description": "出生日期分数，为其权重的百分比（−100 至 100）。" }, "dob_weight": { "type": "integer", "nullable": true, "description": "配置的出生日期权重（`aml_dob_weight`）。" }, "dob_weight_normalized": { "type": "number", "nullable": true, "description": "重新归一化后的出生日期权重（0–100）。" }, "dob_contribution": { "type": "number", "nullable": true, "description": "出生日期对 `total_score` 的贡献点数。" }, "country_score": { "type": "integer", "nullable": true, "description": "国家/地区分数占其权重的百分比（−100 到 100）。" }, "country_weight": { "type": "integer", "nullable": true, "description": "配置的国家/地区权重（`aml_country_weight`）。" }, "country_weight_normalized": { "type": "number", "nullable": true, "description": "重新归一化后的国家/地区权重（0–100）。" }, "country_contribution": { "type": "number", "nullable": true, "description": "国家/地区对 `total_score` 的贡献点数。" }, "document_number_match_type": { "type": "string", "nullable": true, "enum": [ "MATCH", "NEUTRAL", "HARD_MISMATCH" ], "description": "证件号码比对的黄金标准结果。" }, "document_number_effect": { "type": "string", "nullable": true, "description": "证件号码影响的便于人类阅读的描述。" }, "total_score": { "type": "integer", "nullable": true, "description": "最终加权匹配分数（0–100），与 `match_score` 保持一致。" } } } } } }, "score": { "type": "number", "nullable": true, "description": "综合 AML 风险评分（0–100）：非误报命中项中的最高 `risk_score`。通过两个阈值驱动 `status`。" }, "screened_data": { "type": "object", "description": "回显筛查的内容：`full_name`、`date_of_birth`、`nationality`、`document_number`（缺失字段为 `null`）。", "properties": { "full_name": { "type": "string" }, "date_of_birth": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "引发该警告的功能。" }, "risk": { "type": "string", "description": "机器可读的风险标识符。" }, "additional_data": { "type": "object", "nullable": true, "description": "警告的额外上下文（若有）。" }, "log_type": { "type": "string", "description": "`warning`、`information` 或 `error`：风险如何影响结果。" }, "short_description": { "type": "string", "description": "单行人类可读的摘要。" }, "long_description": { "type": "string", "description": "完整的人类可读解释说明。" } } }, "description": "当 `score` 不为零且 ≥ `aml_score_approve_threshold` 时包含 `POSSIBLE_MATCH_FOUND` 警告（分数刚好为 0 时从不发出警告）；否则为空。" } } }, "vendor_data": { "type": "string", "nullable": true, "description": "回显您发送的 `vendor_data`。" }, "metadata": { "type": "object", "nullable": true, "description": "您发送的 `metadata` 回显。" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "No hits (Approved)": { "summary": "无异常筛查结果 — 零命中", "value": { "request_id": "d27c5509-7a66-45a9-b05e-d69d9f4c336a", "aml": { "status": "Approved", "total_hits": 0, "entity_type": "person", "hits": [], "score": 0, "screened_data": { "full_name": "Maximilian Mustermann-Doe", "date_of_birth": "1992-03-14", "nationality": "DE", "document_number": null }, "warnings": [] }, "vendor_data": "user-1234", "metadata": { "internal_ref": "abc-123" }, "created_at": "2026-06-11T10:21:07.013938+00:00" } }, "PEP hit (Approved — risk below approve threshold)": { "summary": "命中一项政治公众人物疑似匹配；风险评分 73，仍低于默认的通过阈值 80", "value": { "request_id": "0b7e7a3e-65a1-4f3d-9c7a-1de2f9a40111", "aml": { "status": "Approved", "total_hits": 1, "entity_type": "person", "hits": [ { "id": "hit_7c1e9a40b2d35f86e0a4c912", "url": "https://news.example.org/articles/sample", "match": false, "score": 0.93, "match_score": 93.0, "risk_score": 73.0, "target": null, "caption": "Antonio Ejemplo Modelo", "datasets": [ "PEP Level 1", "PEP" ], "features": null, "rca_name": "", "first_seen": "2026-01-07T00:00:00", "last_seen": "2026-01-07T00:00:00", "review_status": "Unreviewed", "properties": { "name": [ "Antonio Ejemplo Modelo", "Antonio Ejemplo" ], "alias": [ "Antonio Ejemplo Modelo", "Ejemplo Modelo, Pedro" ], "notes": [ "Prime Minister of Spain" ], "gender": [ "male" ], "birthDate": [ "1972-02-29" ], "birthPlace": [ "Madrid, Spain" ], "nationality": null, "position": null }, "risk_view": { "crimes": { "score": 0.0, "weightage": 20, "risk_level": "Low", "risk_scores": {} }, "countries": { "score": 9.64, "weightage": 30, "risk_level": "Low", "risk_scores": { "Spain": 25.71 } }, "categories": { "score": 62.5, "weightage": 50, "risk_level": "High", "risk_scores": { "PEP": 100.0, "PEP Level 1": 100.0 } }, "custom_list": {} }, "score_breakdown": { "name_score": 89, "name_weight": 60, "name_weight_normalized": 60.0, "name_contribution": 53.4, "dob_score": 100, "dob_weight": 25, "dob_weight_normalized": 25.0, "dob_contribution": 25.0, "country_score": 100, "country_weight": 15, "country_weight_normalized": 15.0, "country_contribution": 15.0, "document_number_match_type": "NEUTRAL", "document_number_effect": "No document number provided for screening", "total_score": 93 }, "pep_matches": [ { "aliases": [], "education": [], "list_name": "Presidency of the Government of Spain", "publisher": "Presidency of the Government of Spain", "source_url": "https://news.example.org/articles/sample", "description": "The Presidency of the Government is the central institutional body in Spain that supports the Prime Minister and coordinates the general action of the central government.", "matched_name": "Antonio Ejemplo Modelo", "pep_position": "", "date_of_birth": "1972-02-29", "other_sources": [], "place_of_birth": "Madrid, Spain" } ], "sanction_matches": [], "warning_matches": [], "adverse_media_matches": [], "adverse_media_details": null, "linked_entities": [ { "name": [ "Maria Begona Gomez Fernandez" ], "active": [], "status": [], "details": [], "relation": [ "spouse" ] } ], "additional_information": { "flag_summary": [ "Antonio Ejemplo Modelo has been flagged as a Level 1 Politically Exposed Person (PEP) from Spain, serving as the President of the Government of Spain." ] } } ], "score": 73.0, "screened_data": { "full_name": "Pedro Sanchez Perez-Castejon", "date_of_birth": "1972-02-29", "nationality": "ES", "document_number": null }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-11T10:23:44.812000+00:00" } } } } } }, "400": { "description": "验证错误。字段级问题返回 DRF 的标准外层结构（每个违规字段一个消息数组）；跨字段规则（权重总和、阈值排序、无保存监控）返回 `{\"error\": [...]}`。", "content": { "application/json": { "examples": { "Missing full_name": { "summary": "`full_name` 是唯一的必填字段", "value": { "full_name": [ "This field is required." ] } }, "Short full_name": { "summary": "`full_name` 必须至少包含 2 个字符", "value": { "full_name": [ "Ensure this field has at least 2 characters." ] } }, "Invalid nationality": { "summary": "`nationality` 必须为 ISO 3166-1 alpha-2 代码", "value": { "nationality": [ "Invalid ISO 3166-1 alpha-2 country code." ] } }, "Weights do not sum to 100": { "summary": "`aml_name_weight` + `aml_dob_weight` + `aml_country_weight` ≠ 100", "value": { "error": [ "AML weights must sum to 100. Current sum: 90 (name: 50, dob: 25, country: 15)" ] } }, "Thresholds out of order": { "summary": "通过阈值高于审核阈值", "value": { "error": [ "Approve threshold (90.0) cannot be greater than review threshold (80.0)" ] } }, "Monitoring without saving": { "summary": "`include_ongoing_monitoring=true` 且 `save_api_request=false`", "value": { "error": [ "Ongoing monitoring can only be enabled when the API request is saved." ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何筛查或服务商调用之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/face-search/": { "post": { "summary": "人脸搜索", "description": "将人脸图像与您应用的人脸搜索索引进行 1:N 搜索（该索引包含从验证会话中录入的人脸、已保存的独立 API 调用、直接上传的用户资料人脸，以及您的黑名单/白名单），并返回按相似度排序的匹配项以及黑名单和重复警告。\n\n**工作原理。** 系统会对 `user_image` 中检测到的最大人脸提取特征向量，并在您应用专属的索引范围内进行搜索。`matches` 中最多返回 **5 个**高于相似度下限的匹配项，每项均包含 `similarity_percentage`、来源会话（`session_id`、`session_number`、`status`、`vendor_data`）、该会话证件验证期间提取的 `user_details`、`is_blocklisted` / `is_allowlisted` 标志，以及 `source` 区分字段（`session`、`imported` 或 `list_entry`）。\n\n- `search_type=most_similar`（默认）：按相似度对所有已录入人脸进行排序，适用于去重和欺诈团伙排查。\n- `search_type=blocklisted_or_approved`：将候选人脸限定为黑名单人脸、白名单人脸、来自已通过会话的人脸以及导入的用户资料人脸，并将黑名单条目排在最前；适用于主要目标为黑名单筛查的场景。\n\n仅当触发 `FACE_IN_BLOCKLIST` 或 `POSSIBLE_FACE_IN_BLOCKLIST` 警告时，`status` 才会为 `Declined`；`DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`（`information`）和 `MULTIPLE_FACES_DETECTED`（`warning`）绝不会导致拒绝。与静默活体检测（Passive Liveness）不同，该 endpoint **不会**在匹配中排除具有相同 `vendor_data` 的先前会话。内部还会运行静默活体检测分析并随持久化会话一同存储，但其结果不包含在本次响应中。\n\n**计费。** 每次 `200` 响应消耗一个 Face Search API 额度（从您的套餐额度或充值余额中扣除）。余额不足时将在进行任何图像处理之前返回 `403`。\n\n**会话持久化与人脸录入（`save_api_request`，默认为 `true`）。** 为 `true` 时，该调用将作为 API 类型的会话持久化（可在 Business Console 中查看，或通过返回的 `request_id` 调用 `GET /v3/session/{sessionId}/decision/`，并触发 `status.updated` Webhook），且被搜索的人脸会被录入到您的人脸搜索索引中。通过 Face Search 调用录入的人脸将在未来的 Face Search 结果中排除，因此重复搜索绝不会相互匹配。为 `false` 时，该调用为单次调用：不存储任何内容，不录入人脸，且 `match_image_url` 的值为内部存储路径而非可下载的 URL。\n\n**沙盒。** 沙盒 API 密钥将跳过所有处理和计费：在请求验证通过后（格式错误的输入仍会返回 `400`），该 endpoint 返回静态的 `Approved` 模拟 payload，不持久化任何会话，且不消耗额度。\n\n**身份验证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。缺少凭据或凭据无效将返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`），此 API 绝不返回 `401`。\n\n**速率限制。** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 之间共享每分钟 300 次请求的写入配额；超出限制将返回 `429`。", "operationId": "post_v3face-search", "x-didit-sdk": { "resource": "face_search", "method": "search", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "用于搜索的正面人脸图像。允许的文件扩展名：`tiff`、`jpg`、`jpeg`、`png`、`webp`。最大上传大小：**5 MB**（超出限制的文件将被拒绝并返回 `400`）。图像在处理前会自动压缩至约 0.5 MB，因此极高的分辨率并不会提高准确度。图像必须包含至少一张可检测到的人脸，否则 endpoint 将返回 `400`。如果存在多张人脸，将搜索最大的人脸并添加 `MULTIPLE_FACES_DETECTED` 警告。" }, "search_type": { "type": "string", "default": "most_similar", "enum": [ "most_similar", "blocklisted_or_approved" ], "description": "搜索策略。`most_similar`（默认）按相似度对您应用中登记的所有人脸进行排序。`blocklisted_or_approved` 将候选范围限制在黑名单人脸、白名单人脸、已通过会话中的人脸以及导入的用户档案人脸，其中黑名单条目排在最前。", "example": "most_similar" }, "rotate_image": { "type": "boolean", "default": false, "description": "为 `true` 时，服务会尝试按 90 度旋转输入内容的各个方向，并使用人脸检测效果最佳的方向。在缺少 EXIF 方向信息时非常有用。会增加延迟。", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "为 `true`（默认）时，将此次调用持久化为 API 类型会话，发出 `status.updated` Webhook，对 `match_image_url` 值进行预签名，并将搜索的人脸录入到您的人脸搜索索引中（人脸搜索录入项会从未来的搜索中排除）。为 `false` 时，搜索为单次执行，不存储会话，也不录入人脸。", "example": true }, "vendor_data": { "type": "string", "description": "可选的不透明标识符（您的用户 ID、邮箱、UUID 等），存储在持久化会话中并予以回显。它不会在搜索结果中排除同一用户的人脸。", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "与会话一同存储（当 `save_api_request=true` 时）并原样返回的可选 JSON 对象。在 multipart 请求中，请将其作为 JSON 编码的字符串字段发送，它将被解析为对象。", "example": { "flow": "dedup_check" } } } }, "example": { "user_image": "(binary JPEG/PNG selfie)", "search_type": "most_similar", "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "dedup_check" } } } } }, "responses": { "200": { "description": "人脸搜索已完成。`face_search.matches` 包含最多 5 个按相似度排序的相似人脸；空数组表示没有录入的人脸超过相似度底限。仅在命中黑名单时 `status` 为 `Declined`；仅有重复匹配仍会返回 `Approved`，因此请检查 `matches` 和 `warnings`，而不仅仅是 `status`。当 `save_api_request=true` 时，`request_id` 为持久化的会话 ID。每个匹配项都包含 `source`（`session`、`imported`、`list_entry` 或 `retained_template`）、`vendor_user_id` 和 `biometric_template_id`；`retained_template` 匹配来源于在源会话删除后保留的无图像生物特征模板，其会话字段、`match_image_url` 和 `user_details` 均为 `null`。", "content": { "application/json": { "examples": { "Blocklist hit (Declined)": { "summary": "该人脸与黑名单中的人脸匹配", "value": { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "face_search": { "status": "Declined", "total_matches": 1, "matches": [ { "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "session_number": 323442, "similarity_percentage": 99.99, "source": "session", "vendor_data": "user-1", "verification_date": "2025-01-01T00:00:00Z", "user_details": { "full_name": "Jane Marie Doe", "document_type": "ID", "document_number": "X1234567" }, "match_image_url": "https:///face/3f6a1c2e/reference.jpg", "status": "Approved", "is_blocklisted": true, "is_allowlisted": false, "api_service": null, "vendor_user_id": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "biometric_template_id": null } ], "user_image": { "entities": [ { "bbox": [ 40, 40, 120, 120 ], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [ { "risk": "FACE_IN_BLOCKLIST", "feature": "LIVENESS", "additional_data": { "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "blocklisted_session_number": 323442, "api_service": null }, "log_type": "error", "short_description": "Face in blocklist", "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Duplicate found (Approved)": { "summary": "该人脸已出现在另一个已通过的会话中：提示信息，不予拒绝", "value": { "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f", "face_search": { "status": "Approved", "total_matches": 1, "matches": [ { "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788", "session_number": 1024, "similarity_percentage": 87.42, "source": "session", "vendor_data": "user-9", "verification_date": "2025-11-20T09:15:00Z", "user_details": null, "match_image_url": "https:///face/9c8b7a6d/reference.jpg", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": "PASSIVE_LIVENESS", "vendor_user_id": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "biometric_template_id": null } ], "user_image": { "entities": [ { "bbox": [ 40, 40, 120, 120 ], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [ { "risk": "DUPLICATED_FACE", "feature": "LIVENESS", "additional_data": { "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788", "duplicated_session_number": 1024, "api_service": "PASSIVE_LIVENESS" }, "log_type": "information", "short_description": "Duplicated face from other approved session", "long_description": "The system identified a duplicated face from another approved session, requiring further investigation." } ] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "No matches (Approved)": { "summary": "没有已录入的人脸超过相似度下限", "value": { "request_id": "9d8c7b6a-5f4e-3d2c-1b0a-998877665544", "face_search": { "status": "Approved", "total_matches": 0, "matches": [], "user_image": { "entities": [ { "bbox": [ 40, 40, 120, 120 ], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。" }, "face_search": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "仅当触发 `FACE_IN_BLOCKLIST` 或 `POSSIBLE_FACE_IN_BLOCKLIST` 警告时为 `Declined`。重复匹配和多张人脸警告绝不会导致拒绝。" }, "total_matches": { "type": "integer", "description": "`matches` 中的条目数量（0–5）。", "example": 1 }, "matches": { "type": "array", "maxItems": 5, "description": "人脸搜索索引中超过相似度下限的最多 5 张人脸，按相似度排序（当 `search_type=blocklisted_or_approved` 时，黑名单条目排在最前）。当没有已录入的人脸达到足够的相似度时为空。", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "匹配人脸所属验证会话的 ID。当 `source` 为 `imported`、`list_entry` 或 `retained_template` 时为 `null`。", "example": "882c42d5-8a4d-4d20-8080-a22f57822c86" }, "session_number": { "type": "integer", "nullable": true, "description": "在 Business Console 中显示的便于人类阅读的会话编号。对于非会话匹配项为 `null`。", "example": 323442 }, "similarity_percentage": { "type": "number", "format": "float", "minimum": 0, "maximum": 100, "description": "提交的人脸与匹配人脸之间的相似度（0–100）。", "example": 99.99 }, "source": { "type": "string", "enum": [ "session", "imported", "list_entry", "retained_template" ], "description": "比对人脸的录入来源：`session` — 验证会话或已保存的独立 API 调用；`imported` — 直接上传至用户资料的人脸；`list_entry` — 附加到您某个名单中的人脸；`retained_template` — 存储在用户资料中的无图像生物特征模板，列于 `/v3/biometric-templates/` 下。" }, "vendor_data": { "type": "string", "nullable": true, "description": "比对成功的会话或导入及保留模板人脸所关联用户的 `vendor_data`。", "example": "user-1" }, "vendor_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "关联的用户 ID。名单条目和无用户的会话匹配为 `null`。", "example": "2f7c1a9e-4b28-4a6d-97f1-83576f80e1b4" }, "biometric_template_id": { "type": "string", "format": "uuid", "nullable": true, "description": "保留的生物特征模板 ID。仅在 `source` 为 `retained_template` 时设置；否则为 `null`。", "example": null }, "verification_date": { "type": "string", "format": "date-time", "nullable": true, "description": "匹配的人脸最初被采集的时间，或保留的模板创建的时间（`YYYY-MM-DDThh:mm:ssZ`）。对于 `list_entry` 匹配为 `null`。", "example": "2025-01-01T00:00:00Z" }, "user_details": { "type": "object", "nullable": true, "description": "在匹配会话的证件验证期间提取的身份数据。当匹配会话没有证件数据（例如仅活体检测会话）时为 `null`，且对于 `retained_template` 匹配始终为 `null`。对于 `source: imported` 匹配，该字段改由用户档案填充：设置了 `full_name`，`document_type`/`document_number` 为 null。", "properties": { "full_name": { "type": "string", "nullable": true, "example": "Jane Marie Doe" }, "document_type": { "type": "string", "nullable": true, "example": "ID" }, "document_number": { "type": "string", "nullable": true, "example": "X1234567" } } }, "match_image_url": { "type": "string", "nullable": true, "description": "`save_api_request=true` 时匹配人脸参考图像的有时限的 URL（`https:///...`）。当 `save_api_request=false` 时，这是无法直接下载的内部存储路径。对于 `retained_template` 匹配项始终为 `null`，因为保留的模板不包含图像。", "example": "https:///face/3f6a1c2e/reference.jpg" }, "status": { "type": "string", "nullable": true, "description": "匹配会话的状态（`Approved`、`Declined`、`In Review` 等）。对于 `imported`/`list_entry` 匹配为 `null`。", "example": "Approved" }, "is_blocklisted": { "type": "boolean", "description": "当比对出的人脸在您的人脸黑名单中时为 `true`。任何足够相似的黑名单匹配都会使搜索被拒绝。" }, "is_allowlisted": { "type": "boolean", "description": "当比对出的人脸位于您的白名单中时为 `true`。白名单中的匹配会静默重复警告。" }, "api_service": { "type": "string", "nullable": true, "description": "当比对的人脸是通过独立 API 调用（例如 `PASSIVE_LIVENESS`）录入时设置；对于常规验证会话和导入的人脸，该值为 `null`。", "example": null } } } }, "user_image": { "type": "object", "description": "已提交图像的人脸检测结果。此处的条目仅包含 `bbox` 和 `confidence`。", "properties": { "entities": { "type": "array", "description": "每张检测到的人脸对应一个条目。以最大的人脸为准进行搜索。", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "像素边界框 `[x_min, y_min, x_max, y_max]`。", "example": [ 40, 40, 120, 120 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "人脸检测置信度（0–1）。", "example": 0.732973 } } } }, "best_angle": { "type": "integer", "description": "产生最佳人脸检测结果的旋转角度（度）；仅当 `rotate_image=true` 纠正了方向时才为非零值。在此 endpoint 上永不为 null（当模型省略该值时默认为 0）。", "example": 0 } } }, "warnings": { "type": "array", "description": "风险信号。`FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST`（`error`）将拒绝搜索；`MULTIPLE_FACES_DETECTED`（`warning`）和 `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE`（`information`）为参考性提示。", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "MULTIPLE_FACES_DETECTED", "FACE_IN_BLOCKLIST", "POSSIBLE_FACE_IN_BLOCKLIST", "DUPLICATED_FACE", "POSSIBLE_DUPLICATED_FACE" ], "description": "机器可读的风险代码。" }, "feature": { "type": "string", "enum": [ "LIVENESS" ], "description": "引发该警告的功能。在此 endpoint 上始终为 `LIVENESS`。" }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "`MULTIPLE_FACES_DETECTED` 时为 `null`。命中黑名单时带有 `{blocklisted_session_id, blocklisted_session_number, api_service}`；命中重复项时带有指向首个匹配会话的 `{duplicated_session_id, duplicated_session_number, api_service}`。" }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "严重程度。`error` 警告会导致 `status` 变为 `Declined`；`warning` 和 `information` 条目仅供参考，本身绝不会导致拒绝。" }, "short_description": { "type": "string", "description": "易于阅读的单行风险摘要。" }, "long_description": { "type": "string", "description": "风险的便于人类阅读的说明。" } } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，或 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 对象回显，或 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "响应生成时的 ISO 8601 时间戳（UTC），例如 `2026-06-12T01:04:42.763237+00:00`。" } } } } } }, "400": { "description": "验证错误。当 `user_image` 缺失、超过 5 MB、扩展名不受支持，或者提交的图像中**未检测到人脸**时返回。字段错误使用 DRF 的 `{field: [messages]}` 响应格式；人脸检测失败使用 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "No face detected": { "summary": "图像解码正常，但未包含可检测到的人脸", "value": { "error": "No face detected in the image" } }, "Missing image": { "summary": "表单数据中未包含 `user_image`", "value": { "user_image": [ "No file was submitted." ] } }, "Unsupported file extension": { "summary": "文件扩展名不在 tiff/jpg/jpeg/png/webp 范围内", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "上传内容超过 5 MB 限制", "value": { "user_image": [ "File size should not exceed 5 MB" ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头，或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何图像处理之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/face-search/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'search_type=most_similar' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.face_search.search(\n user_image=open(\"user_image.jpg\", \"rb\"),\n search_type=\"most_similar\",\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"dedup_check\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.faceSearch.search({\n user_image: await fileFromPath(\"user_image.jpg\"),\n search_type: \"most_similar\",\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"dedup_check\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FaceSearch.Search(ctx, didit.FaceSearchSearchParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tSearchType: didit.Some(didit.FaceSearchSearchParamsSearchType(\"most_similar\")),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"dedup_check\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.FaceSearchSearchParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.faceSearch().search(FaceSearchSearchParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .searchType(FaceSearchSearchParams.SearchType.of(\"most_similar\"))\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"dedup_check\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "faceSearch->search([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'search_type' => 'most_similar',\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'dedup_check'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.face_search.search(\n user_image: Pathname(\"user_image.jpg\"),\n search_type: \"most_similar\",\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"dedup_check\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FaceSearch.SearchAsync(new FaceSearchSearchParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n SearchType = new FaceSearchSearchParamsSearchType(\"most_similar\"),\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"dedup_check\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/sessions/": { "get": { "summary": "带过滤器和分页列出验证会话（KYC 和/或 KYB）", "description": "返回由您的 API 密钥标识的应用的验证会话分页列表，按从新到旧排序（降序 `session_number`）。\n\n**规范 URL：** 路由为 `/v3/sessions/`（带有末尾斜杠）。针对不带斜杠的 `/v3/sessions` 请求会收到 `301` 重定向至带有斜杠的 URL，并保留查询字符串；大多数 HTTP 客户端会在 GET 请求中透明地遵循该重定向。\n\n**何时使用此 endpoint 与 Webhook：** 在仪表板、后台搜索、对账和批量导出场景中使用此 endpoint。请勿通过轮询此接口来跟踪单个验证的进度；请改为配置 [Webhook](/zh/integration/webhooks)，它会在会话发生变更的瞬间推送 `status.updated` 事件。如需获取单个会话的完整结果，请调用 `GET /v3/session/{sessionId}/decision/`。\n\n**KYC 与 KYB 会话：** `session_kind` 用于选择列出的会话类型：\n- `user`（默认值）- 仅列出用户验证（KYC）会话。向后兼容的行为。\n- `business` - 仅列出企业验证（KYB）会话。数据行具有不同且更精简的结构（参见响应模式）。\n- `all` - 在一个响应中同时返回两种类型：相同 `limit`/`offset` 下的 KYC 页面和 KYB 页面会在 `results` 中拼接（KYC 行在前），因此一个页面最多可包含 `2 x limit` 行。`count` 为两种类型的总和，而 `next`/`previous` 反映 KYC 侧的分页。如需对混合数据进行严格分页，请分别调用 `user` 和 `business`。\n\n每一行都包含一个 `session_kind` 鉴别字段（`\"user\"` 或 `\"business\"`）。\n\n**分页：** 标准 limit/offset：`limit`（默认 50）和 `offset`（默认 0），并提供 `next`/`previous` 开箱即用的页面 URL。对于 KYC 行，`count` 是精确的。对于 KYB 行，`count` 是通过有界扫描计算的，上限为 100；当匹配数超过 100 时它仍保持为 100，因此请使用 `next` 进行迭代（或通过检查返回的数据是否已满一页），而不要根据 `count` 计算总页数。\n\n**过滤器语义：** 所有过滤器均以 AND 组合并应用于 KYC 行。当 `session_kind` 为 `business` 或 `all` 时，KYB 侧支持以下通用参数：`vendor_data`、`status`、`workflow_id`、`country`（登记公司国家/地区代码）、`date_from`、`date_to`、`search`（公司名称、注册号 — 输入注册号时请勿包含分隔符，例如 `DPC001` 而不是 `DPC-001` — vendor_data、会话编号或会话 UUID）、`warning` 和 `organization_name`；其余仅适用于 KYC 的过滤器在 KYB 行中将被忽略。逗号分隔的参数（`status`、`country`、`document_type`、`region`、`workflow_id`、`document_name`、`warning`、`organization_name`、`session_type`）匹配列出的任意值（参数内为 OR 关系）。`vendor_data` 为精确匹配；如需部分匹配请使用 `search`。列表过滤器中的未知值不会返回任何行（不会报错）；类型参数中格式错误的值（`date_from`、`date_to`、`didit_internal_id`、`api_service`、`session_kind`）将返回 `400` 并附带针对各字段的错误对象。\n\n**搜索：** `search` 会自适应输入内容：完整 UUID 用于查询 `session_id`；数字（可选包含 `+ - . space`）匹配会话编号前缀、证件/个人编号、电话号码前缀或 `vendor_data`；包含 `@` 的值匹配邮箱前缀；任何其他文本匹配姓名（不区分重音符号）和 `vendor_data`。\n\n未对此 endpoint 强制实施固定的速率限制，但请保持较低的列表轮询频率，并依靠 Webhook 获取实时更新。", "operationId": "get_v3_sessions", "x-didit-sdk": { "resource": "sessions", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "session_kind", "in": "query", "required": false, "description": "要列出哪种类型的会话：`user`（仅限 KYC，默认值）、`business`（仅限 KYB）或 `all`（两者合并，有关合并分页语义请参阅说明）。匹配不区分大小写（`BUSINESS` 有效）；除 `user`/`business`/`all` 的大小写变体之外的任何值都会返回 `400`。", "schema": { "type": "string", "enum": [ "user", "business", "all" ], "default": "user" }, "example": "all" }, { "name": "limit", "in": "query", "required": false, "description": "每页最大行数（当 `session_kind=all` 时按每种类型计算）。默认值为 50。", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 20 }, { "name": "offset", "in": "query", "required": false, "description": "返回第一行前跳过的行数。默认为 0。建议优先使用响应中的 `next`/`previous` URL。", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 20 }, { "name": "status", "in": "query", "required": false, "description": "要包含的会话状态的逗号分隔列表，例如 `Approved,In Review`。值区分大小写；请参阅[验证状态](/zh/integration/verification-statuses)。未知值不会匹配任何内容。", "schema": { "type": "string" }, "example": "Approved,In Review" }, { "name": "vendor_data", "in": "query", "required": false, "description": "对您在创建会话时发送的 `vendor_data`（您自己的用户/企业标识符）进行精确匹配过滤。如需部分匹配，请改用 `search`。", "schema": { "type": "string" }, "example": "your-user-id-123" }, { "name": "search", "in": "query", "required": false, "description": "完整的显示引用（例如用户的 `S-0001` 或企业的 `B-0001`）仅匹配该会话编号和类型；前导零和字母大小写不影响匹配。智能自由文本搜索。完整的 UUID 匹配 `session_id`；数字输入匹配会话编号前缀、证件/个人编号、电话前缀或 `vendor_data`；包含 `@` 的输入匹配邮箱前缀；其他文本匹配姓名（不区分重音符号）和 `vendor_data`。包含数字的自由文本还会额外匹配证件/个人编号搜索字段和会话编号前缀。", "schema": { "type": "string" }, "example": "jane doe" }, { "name": "workflow_id", "in": "query", "required": false, "description": "以逗号分隔的工作流 UUID 列表（可在控制台的工作流页面中找到）。列表中格式错误的 UUID 将被忽略；若无有效值，则结果为空。", "schema": { "type": "string" }, "example": "9f9b1234-aaaa-bbbb-cccc-1234567890ab" }, { "name": "date_from", "in": "query", "required": false, "description": "仅包含在此日期或之后创建的会话（UTC），格式为 `YYYY-MM-DD`。格式错误的日期返回 `400`。", "schema": { "type": "string", "format": "date" }, "example": "2026-06-01" }, { "name": "date_to", "in": "query", "required": false, "description": "仅包含截至此日期创建的会话（UTC），格式为 `YYYY-MM-DD`。对于 KYC 行，包含全天；对于 KYB 行，比较条件为 `created_at <= date_to`（午夜），因此请使用下一天的日期以包含整天的 KYB 会话。", "schema": { "type": "string", "format": "date" }, "example": "2026-06-30" }, { "name": "tags", "in": "query", "required": false, "schema": { "type": "string" }, "description": "逗号分隔的标签 ID（您应用的 `tags`）。返回带有其中任意标签的会话。非有效 UUID 的 ID 将被忽略，当没有任何有效 ID 时，列表为空。" }, { "name": "decided_from", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 日期时间。返回状态最后变更时间等于或晚于该时间的会话。该参数根据最后状态变更时间进行过滤，而非根据创建时间。" }, { "name": "decided_to", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "ISO 8601 日期时间。返回状态最后变更时间早于该时间的会话。可与 `decided_from` 结合使用以构成半开区间。" }, { "name": "country", "in": "query", "required": false, "description": "以逗号分隔的国家/地区过滤器。对于 KYC 行：身份证件签发国家/地区的 ISO 3166-1 alpha-3 代码（例如 `ESP,USA`），可能与国籍不同。对于 KYB 行：注册公司的国家/地区代码。", "schema": { "type": "string" }, "example": "ESP,USA" }, { "name": "document_type", "in": "query", "required": false, "description": "会话中已验证的以逗号分隔的身份证件类型代码（仅限 KYC 行）：`P`（护照）、`ID`（身份证）、`DL`（驾照）、`RP`（居留许可）、`SSC`（社保卡）、`HIC`（健康保险卡）、`WP`（工作许可）、`TC`（税卡）、`VISA`、`PSC`（公共服务卡）、`BC`（出生证明）、`OTHER`。请注意，响应字段 `document_type` 包含的是显示名称，而非代码。", "schema": { "type": "string" }, "example": "P,ID" }, { "name": "document_name", "in": "query", "required": false, "description": "确切的证件名称；多个名称可使用逗号分隔传递，但只有当值包含多个 ` - ` 分隔符时才会按逗号拆分（包含内嵌逗号的单个名称会进行整体匹配）。名称与证件验证（正面或背面）识别的名称一致，例如 `Spain - Id Card (2021)`。仅适用于 KYC 记录。", "schema": { "type": "string" }, "example": "Spain - Id Card (2021)" }, { "name": "region", "in": "query", "required": false, "description": "以逗号分隔的证件所属地区/州值（适用于按地区签发的证件，例如美国驾照）。仅限 KYC 行。", "schema": { "type": "string" }, "example": "CA,TX" }, { "name": "didit_internal_id", "in": "query", "required": false, "description": "按 Didit 的内部用户标识符（响应字段 `didit_internal_id`）进行过滤，以列出某个已验证用户的所有会话。必须是有效的 UUID；格式错误的值将返回 `400`。仅限 KYC 行。", "schema": { "type": "string", "format": "uuid" }, "example": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147" }, { "name": "session_type", "in": "query", "required": false, "description": "逗号分隔的会话创建渠道：`API`、`HOSTED`、`MIGRATED`。特殊值 `ALL`（或省略该参数）将禁用此过滤器。仅适用于 KYC 记录。", "schema": { "type": "string" }, "example": "HOSTED" }, { "name": "api_service", "in": "query", "required": false, "description": "按服务过滤独立 API 会话。无效值将返回 `400`。仅适用于 KYC 行。", "schema": { "type": "string", "enum": [ "ID_VERIFICATION", "FACE_MATCH", "AGE_ESTIMATION", "FACE_SEARCH", "POA", "AML", "KYB_REGISTRY", "PASSIVE_LIVENESS", "DATABASE_VALIDATION", "PHONE_VERIFICATION", "EMAIL_VERIFICATION" ] }, "example": "AML" }, { "name": "screened_full_name", "in": "query", "required": false, "description": "在 AML 和数据库核验筛查数据中进行不区分重音符号的姓名搜索。当与 `api_service=AML` 或 `api_service=DATABASE_VALIDATION` 结合使用时，搜索将仅限于该功能的筛查数据。仅限 KYC 数据行。", "schema": { "type": "string" }, "example": "Jane Doe" }, { "name": "warning", "in": "query", "required": false, "description": "逗号分隔的警告风险代码；返回触发了其中任意风险代码的会话（例如 `POSSIBLE_FRAUD`）。各个功能的风险代码已在[警告文档](/zh/integration/webhooks)中列出。适用于 KYC 记录，并且配合企业警告代码时也适用于 KYB 记录。", "schema": { "type": "string" }, "example": "POSSIBLE_FRAUD" }, { "name": "status_initialized_as_in_review", "in": "query", "required": false, "description": "为 `true` 时，仅包含其决策最初为 `In Review` 的会话（用于审计人工审核量）。仅限 KYC 行。", "schema": { "type": "boolean" }, "example": true }, { "name": "is_kyc_to_be_reviewed", "in": "query", "required": false, "description": "`true` 返回证件验证被标记为需要人工审核的会话；`false` 返回证件验证明确未被标记的会话。省略以禁用。仅限 KYC 行。", "schema": { "type": "boolean" }, "example": true }, { "name": "euuid", "in": "query", "required": false, "description": "按终端用户的 euuid（分配给验证用户的 UUID，用于 Console 深度链接）过滤。必须是有效的 UUID；格式错误的取值会返回 400 字段错误。仅适用于 KYC 行。", "schema": { "type": "string", "format": "uuid" }, "example": "0f8fad5b-d9cb-469f-a165-70867728950e" }, { "name": "organization_name", "in": "query", "required": false, "description": "逗号分隔的组织名称。面向控制台；使用 API 密钥（已限定为单个应用）时，它仅匹配您自己组织的名称。", "schema": { "type": "string" }, "example": "Acme Inc" } ], "responses": { "200": { "description": "分页会话列表。`results` 中的各项根据 `session_kind` 可能为 KYC 行、KYB 行或两者皆有；可通过每行的 `session_kind` 字段进行区分。", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "匹配过滤条件的会话数量：100 以内为准确数值，超过 100 时封顶显示为 100，因此请勿将其视为总数。请使用 `next` 判断是否存在更多页面。对于 `session_kind=all`，它是两种类型的总和，每种类型各自封顶显示为 100。", "example": 2 }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。", "example": "https://verification.didit.me/v3/sessions/?limit=20&offset=20" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。", "example": null }, "results": { "type": "array", "description": "会话行，最新的排在最前。使用 `session_kind=all` 时，KYC 行排在最前，然后是 KYB 行。", "items": { "oneOf": [ { "$ref": "#/components/schemas/UserSessionListItem" }, { "$ref": "#/components/schemas/BusinessSessionListItem" } ], "discriminator": { "propertyName": "session_kind", "mapping": { "user": "#/components/schemas/UserSessionListItem", "business": "#/components/schemas/BusinessSessionListItem" } } } } } }, "examples": { "KYC sessions (default)": { "summary": "session_kind=user - 一个已完成的会话和一个未开始的会话", "value": { "count": 2, "next": null, "previous": null, "results": [ { "session_id": "5b3720ed-d429-42ef-b67f-37ea805f48ee", "session_kind": "user", "session_number": 720, "session_url": "https://verify.didit.me/session/CuXoBYCYVO5Y", "portrait_image": "https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=...", "document_type": "Passport", "full_name": "Jane Marie Doe", "country": "ESP", "status": "Approved", "vendor_data": "your-user-id-123", "didit_internal_id": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147", "created_at": "2026-06-09T12:26:54.328364Z", "features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" }, { "feature": "IP_ANALYSIS", "status": "Approved" } ], "phone_number": { "number": "+14155552671", "is_verified": true }, "email_address": { "email": "jane@example.com", "is_verified": true }, "additional_details": { "aml": { "total_hits": 0, "entity_type": "person", "is_adverse_media_fetched": false }, "liveness": { "method": "PASSIVE", "score": 0.98 }, "face_match": { "score": 0.95 } } }, { "session_id": "038ad62f-5ebd-46c2-afe9-4b2956bf687f", "session_kind": "user", "session_number": 719, "session_url": "https://verify.didit.me/session/7RGKiO6ioGH6", "portrait_image": null, "document_type": null, "full_name": null, "country": null, "status": "Not Started", "vendor_data": "your-user-id-124", "didit_internal_id": "eb4e679d-ca4b-461f-9685-687bac29ebdb", "created_at": "2026-06-09T08:02:23.343053Z", "features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "FACE_MATCH", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" }, { "feature": "IP_ANALYSIS", "status": "Not Finished" } ], "phone_number": null, "email_address": null, "additional_details": null } ] } }, "Mixed KYC + KYB (session_kind=all)": { "summary": "session_kind=all - 一行 KYC 紧跟一行 KYB", "value": { "count": 2, "next": null, "previous": null, "results": [ { "session_id": "5b3720ed-d429-42ef-b67f-37ea805f48ee", "session_kind": "user", "session_number": 720, "session_url": "https://verify.didit.me/session/CuXoBYCYVO5Y", "portrait_image": null, "document_type": "Identity Card", "full_name": "Jane Marie Doe", "country": "ESP", "status": "In Review", "vendor_data": "your-user-id-123", "didit_internal_id": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147", "created_at": "2026-06-09T12:26:54.328364Z", "features": [ { "feature": "ID_VERIFICATION", "status": "In Review" }, { "feature": "LIVENESS", "status": "Approved" } ], "phone_number": null, "email_address": null, "additional_details": { "liveness": { "method": "PASSIVE", "score": 0.98 } } }, { "session_id": "8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52", "session_kind": "business", "session_number": 42, "status": "Approved", "vendor_data": "your-company-id-77", "created_at": "2026-06-08T09:14:02.118450Z", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "workflow_type": "kyb", "workflow_label": "Standard KYB", "company_name": "Acme Holdings S.L.", "registration_number": "B12345678", "country": "ES" } ] } } } } } }, "301": { "description": "重定向到规范的带尾随斜杠 URL。当请求路径为 `/v3/sessions`（无尾随斜杠）时返回；`Location` 请求头指向保留查询字符串的 `/v3/sessions/`。GET 客户端通常会自动跟随重定向。" }, "400": { "description": "无效的查询参数。响应体是一个以违规参数为键的对象。", "content": { "application/json": { "examples": { "Invalid session_kind": { "summary": "session_kind 不是 user/business/all 之一", "value": { "session_kind": "Must be \"user\", \"business\", or \"all\"." } }, "Invalid date": { "summary": "date_from/date_to 格式错误", "value": { "date_from": [ "Enter a valid date." ] } }, "Invalid didit_internal_id": { "summary": "didit_internal_id 不是有效的 UUID", "value": { "didit_internal_id": [ "Enter a valid UUID." ] } }, "Invalid api_service": { "summary": "api_service 不在允许的选项中", "value": { "api_service": [ "Select a valid choice. FOO is not one of the available choices." ] } } } } } }, "403": { "description": "缺少、格式错误或已撤销的 API 密钥。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。\n\n**已删除的应用：**在应用被删除后的几分钟内，使用其 API 密钥之一发出的请求可能会返回 `{\"detail\": \"This application was deleted.\", \"code\": \"application_deleted\"}`。请勿重试：该应用及其 API 密钥已不再存在。这几分钟过后，该密钥将像任何其他无效密钥一样被拒绝。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." }, "code": { "type": "string", "description": "机器可读的原因，仅在某些失败情况下出现。`application_deleted`：API 密钥属于已被删除的应用。", "example": "application_deleted" } }, "required": [ "detail" ] }, "examples": { "Forbidden": { "summary": "x-api-key 缺失或无效", "value": { "detail": "You do not have permission to perform this action." } }, "ApplicationDeleted": { "summary": "已删除应用的 API 密钥", "value": { "detail": "This application was deleted.", "code": "application_deleted" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s 'https://verification.didit.me/v3/sessions/?status=Approved,In%20Review&date_from=2026-06-01&limit=20' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListAutoPaging(ctx, didit.SessionsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->list() as $item) {\n print_r($item);\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/share/": { "post": { "summary": "为已完成的验证会话生成共享 token", "description": "生成一个短期 JWT，允许特定的 Didit 应用导入此已完成的会话。与 `POST /v3/session/import-shared/` 配合使用。", "operationId": "post_v3_session_share", "x-didit-sdk": { "resource": "sessions", "method": "share", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "已铸造共享 token。", "content": { "application/json": { "schema": { "type": "object", "properties": { "share_token": { "type": "string", "description": "HS256 签名的 JWT。将其原样作为 `share_token` 传递给目标应用上的 [`POST /v3/session/import-shared/`](/sessions-api/import-shared-session)。", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "for_application_id": { "type": "string", "format": "uuid", "description": "回显该 token 绑定的目标应用 UUID。", "example": "a5f3bca2-46e2-411e-90ef-a580900a57ee" }, "session_kind": { "type": "string", "enum": [ "user", "business" ], "description": "源会话是用户验证（KYC）还是企业验证（KYB）会话。" } } }, "examples": { "User session": { "summary": "共享 KYC 会话", "value": { "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzZXNzaW9uX2lkIjoiMjBiYjNjM2ItNjE0Ni00MzlmLTg0YTQtYmQzMGQwMGFjNmEyIiwiZnJvbV9hcHBsaWNhdGlvbl9pZCI6ImRiZDIwZTM0LTQyZTktNGYyYy1iYTkxLWNmMDc2MjAxNmY2NCIsImZvcl9hcHBsaWNhdGlvbl9pZCI6ImE1ZjNiY2EyLTQ2ZTItNDExZS05MGVmLWE1ODA5MDBhNTdlZSIsImlhdCI6MTc1MzYzMDY2NiwiZXhwIjoxNzUzNjM0MjY2fQ.JJ9pNE_hqZsOtbR0XYZIWw4JzidjdEl279iUrsIkhGE", "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee", "session_kind": "user" } }, "Business session": { "summary": "共享 KYB 会话", "value": { "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee", "session_kind": "business" } } } } } }, "401": { "description": "凭据缺失或无效。与大多数 v3 endpoint 不同，此 endpoint 通过权限装饰器进行身份验证，在未提供有效 token/密钥时返回 `401`。", "content": { "application/json": { "examples": { "Unauthorized": { "summary": "未授权", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "404": { "description": "您的应用中不存在具有给定 `session_id` 的会话。", "content": { "application/json": { "examples": { "Not Found": { "summary": "未找到会话", "value": { "detail": "Not found." } } } } } }, "400": { "description": "验证错误。字段错误以字段名为键；未完成错误在 `detail` 键下返回（作为数组）。", "content": { "application/json": { "examples": { "Wrong status": { "summary": "来源会话未结束", "value": { "detail": [ "Only finished sessions (\"Approved\", \"Declined\", \"In Review\") can be shared." ] } }, "Target missing": { "summary": "目标应用不存在", "value": { "for_application_id": [ "Target application does not exist." ] } }, "Self-share": { "summary": "目标为发起调用的应用", "value": { "for_application_id": [ "Cannot share a session with the same application." ] } }, "TTL bounds": { "summary": "ttl_in_seconds 超出范围", "value": { "ttl_in_seconds": [ "Ensure this value is greater than or equal to 60." ] } } } } } }, "403": { "description": "凭证有效，但缺少针对此应用的 `write:sessions` 权限。", "content": { "application/json": { "examples": { "No Permission": { "value": { "detail": "You do not have permission to perform this action." }, "summary": "无权限" } } } } } }, "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "要为其生成 token 的源验证会话的 UUID。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "for_application_id" ], "properties": { "for_application_id": { "type": "string", "format": "uuid", "description": "将兑换该 token 的 Didit 应用的 UUID。必须存在、未被删除，且不同于调用方应用。可在 Business Console 的 **Settings → Application** 下找到。", "example": "a5f3bca2-46e2-411e-90ef-a580900a57ee" }, "ttl_in_seconds": { "type": "integer", "description": "token 生命周期，以秒为单位。最小值为 `60`，最大值为 `86400`（24 小时）。默认为 `3600`（1 小时）。", "minimum": 60, "maximum": 86400, "default": 3600, "example": 3600 } } }, "example": { "for_application_id": "a5f3bca2-46e2-411e-90ef-a580900a57ee", "ttl_in_seconds": 7200 } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/share/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"for_application_id\": \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n \"ttl_in_seconds\": 7200\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.share(\n \"11111111-2222-3333-4444-555555555555\",\n for_application_id=\"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n ttl_in_seconds=7200,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.share(\"11111111-2222-3333-4444-555555555555\", {\n for_application_id: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n ttl_in_seconds: 7200,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Share(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsShareParams{\n\tForApplicationID: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n\tTTLInSeconds: didit.Int(7200),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsShareParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().share(\"11111111-2222-3333-4444-555555555555\", SessionsShareParams.builder()\n .forApplicationId(\"a5f3bca2-46e2-411e-90ef-a580900a57ee\")\n .ttlInSeconds(7200L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->share('11111111-2222-3333-4444-555555555555', [\n 'for_application_id' => 'a5f3bca2-46e2-411e-90ef-a580900a57ee',\n 'ttl_in_seconds' => 7200,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.share(\n \"11111111-2222-3333-4444-555555555555\",\n for_application_id: \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n ttl_in_seconds: 7200\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ShareAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsShareParams\n{\n ForApplicationId = \"a5f3bca2-46e2-411e-90ef-a580900a57ee\",\n TtlInSeconds = 7200,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/import-shared/": { "post": { "summary": "兑换共享 token，以将验证会话克隆到您的应用中", "description": "兑换共享 token，以将 KYC 或 KYB 会话克隆到调用应用中并生成全新的 `session_id`。非幂等 — 每个接收方只能兑换一次 token。", "operationId": "post_v3_session_import_shared", "x-didit-sdk": { "resource": "sessions", "method": "import_shared", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "201": { "description": "会话已克隆。响应体是两种类型的 V3 决策 payload，通过 `session_kind` 进行区分：`\"user\"`（KYC）包含基于列表的功能块，如 `id_verifications`、`liveness_checks`、`aml_screenings`；`\"business\"`（KYB）包含诸如 `registry_checks` 和 `key_people_checks` 的功能块。两者均包含 `shared_from_session`，即源应用中原始会话的 `session_id`。如果 `trust_review: false`，克隆会话的 `status` 将被强制设为 `In Review`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDecision" }, "examples": { "User session imported": { "summary": "克隆的 KYC 会话（截断 — 实际为完整的 V3 决策 payload）", "value": { "session_id": "11111111-2222-3333-4444-555555555555", "session_kind": "user", "shared_from_session": "99999999-8888-7777-6666-555555555555", "session_number": 43762, "session_url": null, "status": "In Review", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "user-1", "created_at": "2026-05-17T08:42:11Z", "expires_at": "2026-05-24T08:42:11Z" } }, "Business session imported": { "summary": "克隆的 KYB 会话（截断 — 实际为完整的 V3 KYB 决策 payload）", "value": { "session_id": "22222222-3333-4444-5555-666666666666", "session_kind": "business", "shared_from_session": "88888888-7777-6666-5555-444444444444", "session_number": 982, "session_url": null, "status": "Approved", "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "company-1" } } } } } }, "400": { "description": "验证错误（token 无效、已过期、目标错误，或引用的会话已不存在）。", "content": { "application/json": { "examples": { "Invalid Share Token": { "summary": "无效的 JWT", "value": { "share_token": [ "Invalid share token." ] } }, "Expired Share Token": { "summary": "token 已超过 `exp`", "value": { "share_token": [ "Share token has expired." ] } }, "Wrong audience": { "summary": "token 未绑定到此应用", "value": { "share_token": [ "This token is not valid for this application." ] } }, "Original missing": { "summary": "来源会话已被删除", "value": { "share_token": [ "Original session does not exist." ] } } } } } }, "403": { "description": "缺少 API 密钥（错误、已撤销或已过期的密钥会收到 `401`），或者该来源会话已被导入到调用方应用中（每个接收方仅可兑换一次）。", "content": { "application/json": { "examples": { "Forbidden": { "summary": "禁止访问", "value": { "detail": "You do not have permission to perform this action." } }, "Already imported": { "summary": "来源已导入过一次", "value": { "detail": "This session has already been shared with your application." } } } } } }, "404": { "description": "`workflow_id` 不属于发起调用的应用。", "content": { "application/json": { "examples": { "Workflow not found": { "summary": "未知工作流", "value": { "detail": "Workflow does not exist for this application." } } } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "share_token", "trust_review", "workflow_id" ], "properties": { "share_token": { "type": "string", "description": "由 [`POST /v3/session/{sessionId}/share/`](/sessions-api/share-session) 签发的 JWT 共享 token。", "example": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." }, "trust_review": { "type": "boolean", "description": "若为 `true`，克隆的会话将保留源会话的最终 `status`。若为 `false`，则强制置为 `In Review`。", "example": false }, "workflow_id": { "type": "string", "format": "uuid", "description": "调用方应用中工作流的 UUID。跨应用 ID 将被拒绝并返回 `404`。", "example": "9f9b1234-aaaa-bbbb-cccc-1234567890ab" }, "vendor_data": { "type": "string", "nullable": true, "description": "针对克隆会话的 `vendor_data` 的可选覆盖值。", "example": "user-1" } } }, "example": { "share_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "trust_review": false, "workflow_id": "9f9b1234-aaaa-bbbb-cccc-1234567890ab", "vendor_data": "user-1" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/import-shared/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"share_token\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n \"trust_review\": false,\n \"workflow_id\": \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n \"vendor_data\": \"user-1\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.import_shared(\n share_token=\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n trust_review=False,\n workflow_id=\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n vendor_data=\"user-1\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.importShared({\n share_token: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n trust_review: false,\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n vendor_data: \"user-1\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ImportShared(ctx, didit.SessionsImportSharedParams{\n\tShareToken: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n\tTrustReview: false,\n\tWorkflowID: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n\tVendorData: didit.String(\"user-1\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsImportSharedParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().importShared(SessionsImportSharedParams.builder()\n .shareToken(\"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\")\n .trustReview(false)\n .workflowId(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\")\n .vendorData(\"user-1\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->importShared([\n 'share_token' => 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...',\n 'trust_review' => false,\n 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab',\n 'vendor_data' => 'user-1',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.import_shared(\n share_token: \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n trust_review: false,\n workflow_id: \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n vendor_data: \"user-1\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ImportSharedAsync(new SessionsImportSharedParams\n{\n ShareToken = \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...\",\n TrustReview = false,\n WorkflowId = \"9f9b1234-aaaa-bbbb-cccc-1234567890ab\",\n VendorData = \"user-1\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/kyb/search/": { "post": { "summary": "KYB 公司登记企业搜索（独立项）", "operationId": "post_v3_kyb_search", "x-didit-sdk": { "resource": "kyb", "method": "search", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "按名称和/或注册号在官方公司登记中搜索候选企业。这是两步登记流程的第 1 步：**搜索**返回轻量级候选企业，随后通过 `POST /v3/kyb/select/` 获取某一候选企业的完整档案。\n\n**搜索计费。**使用付费企业数据源的成功搜索每次请求费用为 USD 0.50，无论候选企业数量多少。空结果、失败以及仅由其他数据源提供的结果不收费。适用价格会在搜索前预扣；余额不足将返回 403 及代码 `insufficient_credits`。若有约定则适用合同费率，未配置的合同搜索费率将返回 403。沙盒搜索免费。重复成功的搜索可能会产生另一笔费用；回调投递不收取额外费用。档案获取单独计费。该搜索费用同样适用于 v2。返回的候选企业状态始终为 `fetch_status: \"pending\"`：完整的企业数据仅在调用 select 时获取（并计费）。\n\n**`kyb_response_id` 为临时句柄。**它是单次搜索的句柄，并非稳定的企业 ID。请在搜索后尽快选择，若需更新请重新搜索获取新句柄，切勿长期存储。\n\n**`tier` 选择提供商链。**`tier` 指定搜索运行的公司登记等级：`basic`（默认值，即 Lite 链）、`shareholders` 或 `ubo`。搜索将使用为该等级提供服务的提供商链，且该链并不总是与 Lite 搜索读取的链相同，因此 Lite 搜索结果为空并不代表公司登记中没有该企业，请在您所需的等级下重新搜索。如果某个国家/地区不提供您指定的等级，则会在其所提供的不高于该等级的最高等级上进行搜索。请从销售该等级的 endpoint 获取候选企业：`POST /v3/kyb/select/`（Lite）、`POST /v3/kyb/shareholders/` 或 `POST /v3/kyb/ubo/`。\n\n**身份验证。**`POST /v3/kyb/search/`（以及 `/v2/`）在 `x-api-key` 请求头中接收您应用的 API 密钥。托管的 `POST /v1/kyb/search/` 是托管验证流程调用的基于会话认证的路由：对 API 密钥会返回 `403`，且不接收 `tier`，由工作流的 KYB 公司登记配置来选择提供商链。\n\n**两种模式。**\n- *同步（默认）：*API 会持续轮询公司登记，直到搜索完成并返回最终候选企业列表（`search_resolved: true`）。\n- *异步：*传入 `webhook_url`，API 将立即返回响应（通常带有 `search_status: \"pending\"` 和空的候选企业列表），随后在公司登记处理完成时向您的 URL 发送 `kyb.registry_search.resolved` 的 POST 回调。回调正文为 `{\"event_id\", \"event_type\": \"kyb.registry_search.resolved\", \"request_id\", \"vendor_data\", \"metadata\", \"search_status\", \"search_resolved\", \"kyb_registry\", \"timestamp\", \"created_at\"}`（请注意，与该 endpoint 的 ISO 格式 `created_at` 不同，回调中的 `timestamp` 和 `created_at` 为 epoch 时间戳整数），并且是以**未签名**形式发送（请求头为 `X-Didit-Unsigned-Callback: true`，无 `X-Signature`）。\n\n**国家/地区代码。**ISO 3166-1 alpha-2（`GB`、`DE`），若公司登记为地区性质，则加上 `XX-YY` 行政区划代码，例如加利福尼亚州的 `US-CA`。\n\n**沙盒。**来自沙盒应用的密钥将返回一个静态候选企业，不会与任何公司登记通信。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "country_code" ], "properties": { "country_code": { "type": "string", "maxLength": 10, "description": "要搜索其公司登记所在国家/地区的 ISO 3166-1 alpha-2 代码。例如 `GB`。若公司登记在州或省级别运作，请以 `XX-YY` 格式附加 ISO 3166-2 行政区划代码：`US-CA` 搜索加利福尼亚州登记。美国搜索始终需要行政区划，仅传 `US` 将被拒绝。不区分大小写；规范化为大写。", "example": "GB" }, "name": { "type": "string", "maxLength": 255, "description": "要搜索的企业名称。`name` 或 `registration_number` 必填其一。", "example": "Tesco" }, "registration_number": { "type": "string", "maxLength": 100, "description": "要搜索的公司登记注册号。`name` 或 `registration_number` 必须提供其一。" }, "tier": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "default": "basic", "description": "本次搜索运行所依托的服务商链对应的公司登记等级。`basic`（默认）搜索该国家/地区的 Lite 链；`shareholders` 和 `ubo` 搜索该等级的股权结构链，两者可能来自不同数据源，因此 Lite 搜索结果为空并不代表公司登记中没有该企业。对于不提供指定等级的国家/地区，将使用其支持的最高等级（不超过该等级）进行搜索。从售卖所搜索等级的 endpoint 获取候选对象：`POST /v3/kyb/select/`（Lite）、`POST /v3/kyb/shareholders/` 或 `POST /v3/kyb/ubo/`。", "example": "basic" }, "search_type": { "type": "string", "enum": [ "contains" ], "default": "contains", "description": "登记处搜索所应用的名称匹配策略。`contains` 是唯一接受的值：搜索背后的登记处数据源均不提供前缀或模糊模式，因此 `start_with` 和 `fuzzy` 会被拒绝并返回 `400`（`not a valid choice`）。" }, "vendor_data": { "type": "string", "description": "您为此查询指定的标识符；将原样返回并包含在 Webhook 回调中。" }, "metadata": { "type": "object", "nullable": true, "description": "自由格式 JSON；回显并包含在 Webhook 回调中。" }, "webhook_url": { "type": "string", "format": "uri", "maxLength": 500, "description": "将搜索切换为异步模式：API 会立即返回，并在候选列表准备就绪时向此 URL 发送未签名的 `kyb.registry_search.resolved` 回调 POST 请求。" } } }, "example": { "country_code": "GB", "name": "Tesco", "search_type": "contains", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/search/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"country_code\": \"GB\",\n \"name\": \"Tesco\",\n \"search_type\": \"contains\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.search(\n country_code=\"GB\",\n name=\"Tesco\",\n search_type=\"contains\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.search({\n country_code: \"GB\",\n name: \"Tesco\",\n search_type: \"contains\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Search(ctx, didit.KYBSearchParams{\n\tCountryCode: \"GB\",\n\tName: didit.String(\"Tesco\"),\n\tSearchType: didit.Some(didit.KYBSearchParamsSearchType(\"contains\")),\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KybSearchParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().search(KybSearchParams.builder()\n .countryCode(\"GB\")\n .name(\"Tesco\")\n .searchType(KybSearchParams.SearchType.of(\"contains\"))\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->search([\n 'country_code' => 'GB',\n 'name' => 'Tesco',\n 'search_type' => 'contains',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.search(\n country_code: \"GB\",\n name: \"Tesco\",\n search_type: \"contains\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.SearchAsync(new KybSearchParams\n{\n CountryCode = \"GB\",\n Name = \"Tesco\",\n SearchType = new KybSearchParamsSearchType(\"contains\"),\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "搜索已受理。同步模式返回已确定的候选名单；Webhook 模式立即返回（通常为 `search_status: \"pending\"`）并通过 `kyb.registry_search.resolved` 回调投递最终名单。", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "包含 `webhook_url` 时：持久化的搜索请求 ID，在 `kyb.registry_search.resolved` 回调中作为 `request_id` 返回。不包含 `webhook_url` 时：临时关联 UUID（搜索不会被存储）。" }, "kyb_registry": { "$ref": "#/components/schemas/KYBRegistrySearchResults" }, "vendor_data": { "type": "string", "nullable": true, "description": "回显您发送的 `vendor_data`。" }, "metadata": { "type": "object", "nullable": true, "description": "您发送的 `metadata` 回显。" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved search": { "summary": "同步模式 — 最终候选列表", "value": { "request_id": "0c7e9a40-3a13-4f7e-8a44-9d2e2f1c5b6a", "kyb_registry": { "companies": [ { "kyb_response_id": "69aeeb95febb0f1704042259", "name": "Tesco PLC", "registration_number": "00445790", "status": "active", "type": "Public Limited Company", "risk_level": null, "fetch_status": "pending" }, { "kyb_response_id": "69aeeb95febb0f170404225a", "name": "E-TESCO LTD", "registration_number": "15168476", "status": "active", "type": "Private Limited Company", "risk_level": null, "fetch_status": "pending" } ], "pagination": { "total": 2, "page": 1, "per_page": 25 }, "search_status": "resolved", "search_resolved": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:40:00.000000+00:00" } }, "Pending search (webhook mode)": { "summary": "已提供 `webhook_url`：候选对象通过 kyb.registry_search.resolved 回调送达", "value": { "request_id": "5f2d8c1b-7e4a-4b9c-9f0d-3a6e8c2b1d4f", "kyb_registry": { "companies": [], "pagination": { "total": 0, "page": 1, "per_page": 25 }, "search_status": "pending", "search_resolved": false }, "vendor_data": "company-1234", "metadata": { "source": "onboarding" }, "created_at": "2026-06-11T10:41:00.000000+00:00" } } } } } }, "400": { "description": "验证错误。字段级问题使用 DRF 的标准外层结构；名称/注册号规则在 `non_field_errors` 下报告。登记处未覆盖的国家/地区返回 `400` 并附带 `code: kyb_registry_country_unsupported`。", "content": { "application/json": { "examples": { "Missing search criteria": { "summary": "既未提供 `name` 也未提供 `registration_number`", "value": { "non_field_errors": [ "Either 'name' or 'registration_number' is required." ] } }, "Invalid country_code": { "summary": "必须为 `XX`（alpha-2 代码）或 `XX-YY` 行政区划代码", "value": { "country_code": [ "country_code must be a 2-letter ISO code." ] } }, "Invalid search_type": { "summary": "仅接受 `contains`", "value": { "search_type": [ "\"start_with\" is not a valid choice." ] } }, "Invalid webhook_url": { "summary": "`webhook_url` 必须是有效的 URL", "value": { "webhook_url": [ "Enter a valid URL." ] } }, "Country not covered": { "summary": "没有覆盖该国家/地区的公司登记", "value": { "detail": "Company registry search is not available for this country. Enter the company details manually to continue.", "code": "kyb_registry_country_unsupported" } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。此外，在搜索之前，如果无法覆盖适用的搜索费用（`code: \"insufficient_credits\"`），或缺少合同搜索费率，也会返回此错误。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制，或搜索配额已耗尽。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度），并带有 `X-RateLimit-*` 和 `Retry-After` 请求头。此外，每个应用每小时的付费公司登记搜索限制为 600 次：超过此限制后响应为 `429`，附带 `code: kyb_registry_search_limit_reached`，仅由免费数据源提供服务的搜索仍可正常工作。请等待并稍后重新搜索。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } }, "Search allowance spent": { "summary": "过去一小时内付费搜索超过 600 次", "value": { "detail": "The maximum number of company registry searches for this session has been reached. Enter the company details manually to continue.", "code": "kyb_registry_search_limit_reached" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } }, "502": { "description": "KYB 登记提供商暂时不可用：上游公司登记返回 5xx 响应、超时或连接失败。搜索不计费。请稍后重试，或者在 Didit 托管验证流程中，系统会自动为用户提供手动输入企业信息的选项，而不是仅提示重试错误。", "content": { "application/json": { "examples": { "Registry provider outage": { "summary": "登记处提供商未响应搜索", "value": { "detail": "The KYB registry provider is temporarily unavailable. Please try again shortly.", "code": "kyb_registry_provider_unavailable" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } } } } }, "/v3/kyb/select/": { "post": { "summary": "KYB 公司登记企业选择 — 基础版等级（独立项）", "operationId": "post_v3_kyb_select", "x-didit-sdk": { "resource": "kyb", "method": "select", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "获取 `POST /v3/kyb/search/` 返回的单个候选企业的 **Lite** 公司登记档案，包括公司详情、注册地址、标识符、状态、经营活动和管理人员，以及原始公司登记 payload。股东和最终实际受益人通过 `POST /v3/kyb/shareholders/` 和 `POST /v3/kyb/ubo/` 出售。\n\n**与搜索配对使用。** 传入候选企业的 `kyb_response_id`，该值必须与同一应用搜索返回的结果完全一致。该句柄是临时的且仅在该搜索范围内有效：请及时选择，如需新句柄请重新搜索，切勿持久化存储。\n\n**计费。** 每次选择均按该国家/地区的 Lite 价格计费（任何搜索费用另计）；请参阅 [KYB 公司登记定价](/zh/getting-started/kyb-registry-pricing)。在进行任何公司登记调用之前都会检查余额（余额不足时返回 `403`），费用将记入所创建的企业会话中。\n\n**必须持久化保存。** 每次选择都会创建一个企业会话（其 ID 即为 `request_id`），以便跟踪计费和检索；它会显示在控制台中。为了保持对称性支持传入 `save_api_request`，但必须为 `true`（默认值），发送 `false` 将返回 `400`。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistryCandidateRequest" }, "example": { "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/select/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"kyb_response_id\": \"69aeeb95febb0f1704042259\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.select(\n kyb_response_id=\"69aeeb95febb0f1704042259\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.select({\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.Select(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KYBRegistryCandidateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().select(KYBRegistryCandidateRequest.builder()\n .kybResponseId(\"69aeeb95febb0f1704042259\")\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->select([\n 'kyb_response_id' => '69aeeb95febb0f1704042259',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.select(\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.SelectAsync(new KYBRegistryCandidateRequest\n{\n KybResponseId = \"69aeeb95febb0f1704042259\",\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "企业已检索并计费。`kyb_registry` 包含完整档案；请检查 `data_resolved`：当为 `false` 时，公司登记仍在处理中，解析完成后已存储的记录将自动补充完整。", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "为此检索创建的企业会话 ID。如果在响应返回后公司登记信息才解析完成，已存储的记录（在控制台中可见）将持续更新。" }, "registry_tier_requested": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "此 endpoint 销售的等级：针对 select 的 `basic` (Lite)、`shareholders`、`ubo`。" }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "实际交付并计费的等级。当该国家/地区的公司登记不包含股权结构数据，或登记机构没有该公司的股权结构记录时，该等级会低于请求的等级。" }, "kyb_registry": { "type": "object", "description": "完整的公司登记档案。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Didit 为此企业记录分配的 ID。" }, "node_id": { "type": "string", "example": "feature_kyb_registry" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review" ], "description": "Didit 对公司登记核验的评估（例如，当企业在登记处中处于非活跃状态或无法获取股权结构数据时为 `In Review`）。" }, "registry_status": { "type": "string", "nullable": true, "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off" ], "description": "公司登记机构报告的归一化企业状态。" }, "data_resolved": { "type": "boolean", "description": "公司登记处返回完整资料后为 `true`。轮询后登记处仍在处理中时为 `false`，一旦登记处处理完成，存储的记录将自动补充完整。" }, "company_name": { "type": "string", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "example": "00445790" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2。", "example": "GB" }, "region": { "type": "string", "nullable": true, "description": "登记属于地区性时的行政区划代码（例如 `US-CA` 对应 `CA`）；否则为空。" }, "company_type": { "type": "string", "nullable": true, "example": "Public Limited Company" }, "incorporation_date": { "type": "string", "format": "date", "nullable": true, "example": "1947-11-27" }, "registered_address": { "type": "string", "nullable": true, "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA" }, "tax_number": { "type": "string", "nullable": true, "example": "GB412 8925 93" }, "risk_level": { "type": "string", "nullable": true, "description": "公司登记所报告的风险等级（如可用）。" }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "跨司法管辖区验证状态：当公司登记状态确认存续（`active`）时为 `verified`；当其显示公司不再存续（例如 `dissolved`）时为 `failed`；否则为 `unknown`。对于非来自公司登记且选择仍处于 `pending` 状态的公司，该值为 `null`。" }, "is_from_registry": { "type": "boolean", "description": "对于此 endpoint 始终为 `true`，该档案从官方登记机构检索获取。" }, "fetch_status": { "type": "string", "enum": [ "pending", "resolved" ], "description": "公司登记获取生命周期。由 `data_resolved` 镜像。" }, "alternative_names": { "type": "string", "nullable": true, "description": "上报时的替代名称、商业名称、曾用名或原始语言公司名称（文本格式）。" }, "nature_of_business": { "type": "string", "nullable": true, "description": "活动描述或分类代码（如有报告）。" }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "字符串形式的十进制金额（若有上报）。" }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "报告的 ISO 4217 代码（如有）。" }, "website": { "type": "string", "nullable": true, "example": "https://www.tesco.com/" }, "email": { "type": "string", "nullable": true, "example": "customer.service@tesco.co.uk" }, "phone": { "type": "string", "nullable": true, "example": "03301231688" }, "legal_entity_identifier": { "type": "string", "nullable": true, "description": "LEI（若已上报）。" }, "location_of_registration": { "type": "string", "nullable": true, "description": "企业注册所在的登记机构/司法管辖区（如有报告）。" }, "vat_number": { "type": "string", "nullable": true, "description": "欧盟增值税号，在托管登记步骤中收集或随后编辑时提供。在选择时通常尚未设置。增值税号和税号核验会在终端用户在托管流程中提交登记步骤时运行。" }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "在登记提交时验证增值税号（若无，则为 `tax_number`）的结果。`valid` / `invalid`：由相应国家/地区的官方登记处判定（欧盟 VIES、挪威、瑞士、巴西、哥伦比亚、哥斯达黎加、厄瓜多尔、巴拉圭；波兰还由其国内增值税登记册判定）。`format_valid` / `invalid_format`：在无法查询登记处时，由该国家/地区的格式和校验位规则判定。`could_not_validate`：登记处不可用。`not_applicable`：无号码、无登记处或规则的国家/地区，或者沙盒会话。" }, "vat_validated_number": { "type": "string", "nullable": true, "description": "已核验的号码，格式以数据源所知为准（例如从法国 SIREN 或荷兰 RSIN 派生的增值税号）。若未运行核验，则为 `null`。" }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "判定 `vat_validation_status` 的来源：官方登记，或 `format_rules`。未运行任何检查时为 `null`。" }, "vat_validated_name": { "type": "string", "nullable": true, "description": "向验证该号码的数据源登记的名称（如果该数据源公开名称）。仅当状态为 `valid` 时设置。" }, "vat_validated_address": { "type": "string", "nullable": true, "description": "核验该号码的数据源中登记的地址（若该数据源披露）。仅在状态为 `valid` 时设置。" }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "检查的时间戳。未运行检查时为 `null`。" }, "financial_summary": { "type": "object", "nullable": true, "description": "公司登记所报告的股份/资本详情（币种、总股数、股份类别，如可用）。" }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MELISSA BETHELL" }, "designation": { "type": "string", "nullable": true, "description": "原始登记处的职务名称（例如 `Director`、`Secretary`）。" }, "role": { "type": "string", "description": "根据职务衍生出的归一化角色。包含完整的 17 个值的模型集；该 endpoint 上的登记解析通常会输出 director、non_executive_director、secretary、chairman 或 company_officer。", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "company_officer", "settlor", "protector", "investor", "other" ] }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "description": "当公司登记处将该任命标记为已辞任时为 `false`。" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending" ], "description": "关联的 KYC 会话状态（若已为此负责人发起）；否则为 `null`。" }, "kyc_session_url": { "type": "string", "nullable": true, "description": "关联 KYC 会话的验证链接（如果存在）。" }, "first_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的名字；并非从全名中推断。" }, "last_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的姓氏。" }, "address": { "type": "string", "nullable": true, "description": "登记处报告的官员地址。" }, "appointment_date": { "type": "string", "nullable": true, "description": "管理人员被任命的日期。", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "任期结束的日期（若有报告）。", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "公司登记报告的完整出生日期。如果仅已知出生年份或月份，则为 null。", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "公司登记所报告的出生年份，包括完整日期不可用的情况。" }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "公司登记所报告的出生月份。仅知晓年份时为 null。" } } }, "description": "从公司登记中提取的董事、秘书和其他高管。" }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "所有者是自然人还是企业实体。" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "归一化的角色（例如 `ubo`、`shareholder`）。" }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "公司登记报告的股权范围下限（例如 `25%`）。" }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "公司登记报告的股权结构区间上限。" }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending" ] }, "kyc_session_url": { "type": "string", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "解析出的股权百分比（上限值，回退为下限值）。" }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "完整的出生日期（如有报告）。", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "有报告时的委任日期。", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } }, "description": "从登记处提取的实际受益人/重大控制权人。当登记处未公开股权结构时可能为空。" }, "addresses": { "type": "array", "nullable": true, "description": "登记处注明的每个地址，采用标准规范格式。如果未注明，则为 null。", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "登记机构对企业进行分类的业务活动，采用一种规范化格式。若未注明则为 null。", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "公司登记备案日期（如可用）。年度申报表和大会使用 last_annual_return_date 与 last_agm_date；它们与财务账目不同。" }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "description": "在此 endpoint 上始终为 `null`（终端用户编辑公司登记数据时由托管 KYB 流程使用）。" }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在此 endpoint 上始终为 `null`。" }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "当控制台审核员随后编辑该记录时设置。" }, "is_editable": { "type": "boolean", "description": "来自公司登记的数据是否仍可在托管流程/控制台中进行编辑。" }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "与顶级 `registry_tier_delivered` 相同。" }, "registry_ownership_status": { "type": "string", "nullable": true, "enum": [ "not_requested", "delivered", "not_held", "unavailable" ], "description": "当股权结构数据返回时为 `delivered`；当股权结构登记处已响应但未列出此企业时为 `not_held`（参见 `registry_data.ownership_error`）；当请求了股权结构等级但登记处没有此企业的数据或无法查询时为 `unavailable`（参见 `registry_data.ownership_error`）；在 Lite 等级上为 `not_requested`。" }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "工作流订购的公司登记等级：`basic`、`shareholders` 或 `ubo`。也可在 `ownership.tier_requested` 中查看。" }, "registry_monitoring": { "type": "object", "nullable": true, "description": "该企业的最新登记监控，不存在时为 `null`。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "监控器监视的企业字段。" } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "回显您发送的 `vendor_data`。" }, "metadata": { "type": "object", "nullable": true, "description": "您发送的 `metadata` 回显。" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved company": { "summary": "完整的公司登记档案（为简明起见截断了管理人员列表）", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d", "node_id": "feature_kyb_registry", "status": "In Review", "registry_status": "active", "data_resolved": true, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": "", "company_type": "Public Limited Company", "incorporation_date": "1947-11-27", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "tax_number": "GB412 8925 93", "risk_level": "low risk", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": "https://www.tesco.com/", "email": "customer.service@tesco.co.uk", "phone": "03301231688", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": { "currency": "Pound (£)", "total_number_of_shares": "8174378721", "meta_detail": { "Class_Of_Share": "Ordinary" } }, "officers": [ { "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b", "name": "CHRISTOPHER JON TAYLOR", "designation": "Secretary", "role": "secretary", "nationality": null, "is_active": true, "kyc_status": null, "kyc_session_url": null }, { "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c", "name": "MELISSA BETHELL", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": null, "kyc_session_url": null } ], "beneficial_owners": [], "addresses": [ { "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "type": "legal_entity_registry_address", "description": "registered office address" } ], "industries": null, "accounts": { "last_account": "26 February 2025", "next_account": "26 February 2026", "due_by_date": "26 August 2026" }, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } }, "Pending (registry still resolving)": { "summary": "轮询后，所选项仍处于待处理状态 — 稀疏字段，服务端自动完成", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d", "node_id": "feature_kyb_registry", "status": "Not Finished", "registry_status": null, "data_resolved": false, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": null, "company_type": null, "incorporation_date": null, "registered_address": null, "tax_number": null, "risk_level": null, "verification_status": null, "is_from_registry": true, "fetch_status": "pending", "alternative_names": null, "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": {}, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } } } } } }, "400": { "description": "验证错误。字段级问题使用 DRF 的标准外层结构。登记处未覆盖的国家/地区返回 `400` 并附带 `code: kyb_registry_country_unsupported`。", "content": { "application/json": { "examples": { "Missing kyb_response_id": { "summary": "`kyb_response_id` 为必填项", "value": { "kyb_response_id": [ "This field is required." ] } }, "save_api_request=false rejected": { "summary": "选择内容始终持久化保存", "value": { "save_api_request": [ "KYB registry select must be saved so billing and retrieval can be tracked." ] } }, "Country not covered": { "summary": "没有覆盖该国家/地区的公司登记", "value": { "detail": "Company registry search is not available for this country. Enter the company details manually to continue.", "code": "kyb_registry_country_unsupported" } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何筛查或服务商调用之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/passive-liveness/": { "post": { "summary": "静默活体检测", "description": "从单张人脸图像中检测呈现攻击（打印照片、屏幕重放、面具、深度伪造）。无需视频、动作或用户交互。\n\n**工作原理。** 图像由生物识别模型进行分析；评估检测到的最大人脸并计算活体 `score`（0–100）。当触发任何 `error` 严重级别的警告时，`status` 为 `Declined`：\n- `NO_FACE_DETECTED`：活体模型未找到人脸，\n- `LOW_LIVENESS_SCORE`：分数达到或低于 `face_liveness_score_decline_threshold`（默认 `30`），\n- `LIVENESS_FACE_ATTACK`：模型检测到呈现攻击，\n- `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST`：该人脸与您的人脸黑名单中的条目匹配。\n\n`MULTIPLE_FACES_DETECTED` 是 `warning` 严重级别的信号（不会拒绝），而 `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` 是 `information` 严重级别的信号，表示同一张人脸已出现在另一个已通过的会话中（它们绝不会拒绝）。`face_quality` 和 `face_luminance`（0–100，可为 null）描述采集质量。\n\n**黑名单和重复筛查。** 在**每次**调用时运行（无论是否包含 `save_api_request`），通过将检测到的人脸与您应用的人脸搜索索引进行比对。具有相同 `vendor_data` 的先前人脸将从整个索引搜索中排除，因此为同一用户重新运行活体检测不会触发 `DUPLICATED_FACE`，并且源自具有调用方自身 `vendor_data` 会话的黑名单人脸也不会被标记（对相同 `vendor_data` 的人脸绕过 `FACE_IN_BLOCKLIST` 筛查）。\n\n**计费。** 每个 `200` 响应消耗一个 Passive Liveness API 额度（从您的套餐额度或充值余额中扣除）。余额不足将在进行任何图像处理之前返回 `403`。\n\n**会话持久化和人脸录入（`save_api_request`，默认 `true`）。** 当为 `true` 时，该调用将持久化为 API 类型的会话（Business Console，通过返回的 `request_id` 调用的 `GET /v3/session/{sessionId}/decision/`，`status.updated` Webhook），存储参考图像和人脸裁剪图，并将检测到的人脸**录入您的人脸搜索索引**，以便后续的人脸搜索调用和重复检查可以与其匹配。当为 `false` 时，该调用为单次调用：不存储任何内容，且不录入人脸（黑名单/重复筛查仍会运行）。\n\n**沙盒。** 沙盒 API 密钥跳过所有处理和计费：在请求验证之后（格式错误的输入仍返回 `400`），endpoint 返回一个静态的 `Approved` 模拟 payload，不持久化会话，且不消耗额度。\n\n**认证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。缺少凭据或凭据无效将返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`），此 API 绝不会返回 `401`。\n\n**速率限制。** 在所有 POST/PATCH/DELETE endpoint 间共享每个 API 密钥 300 次请求/分钟的写入预算；超出将返回 `429`。", "operationId": "post_v3passive-liveness", "x-didit-sdk": { "resource": "passive_liveness", "method": "check", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "user_image" ], "properties": { "user_image": { "type": "string", "format": "binary", "description": "正面人脸图像（例如自拍照）。允许的文件扩展名：`tiff`、`jpg`、`jpeg`、`png`、`webp`。最大上传大小：**5 MB**（超出限制的文件将被拒绝并返回 `400`）。图像在处理前会自动压缩至约 0.5 MB，因此极高的分辨率并不会提高准确度。图像应仅包含一个拍摄主体。若存在多张人脸，将评估最大的人脸并添加 `MULTIPLE_FACES_DETECTED` 警告。" }, "face_liveness_score_decline_threshold": { "type": "number", "format": "float", "default": 30, "minimum": 0, "maximum": 100, "description": "活体评分阈值（0–100）。计算得出的分数**达到或低于**此值将发出 `LOW_LIVENESS_SCORE` 警告，并将 `status` 设为 `Declined`。默认值为 `30`；调高此值可实施更严格的防欺骗攻击策略。超出 0–100 范围的值将返回 `400`。", "example": 30 }, "rotate_image": { "type": "boolean", "default": false, "description": "为 `true` 时，服务会尝试按 90 度旋转输入内容的各个方向，并使用人脸检测效果最佳的方向。在缺少 EXIF 方向信息时非常有用。会增加延迟。", "example": false }, "save_api_request": { "type": "boolean", "default": true, "description": "为 `true`（默认）时，将此次调用持久化为 API 类型会话，存储人脸图像，发出 `status.updated` Webhook，并将检测到的人脸录入到您的人脸搜索索引中。为 `false` 时，该调用为单次执行，不存储任何内容，也不录入人脸。黑名单和重复筛查在两种情况下都会运行。", "example": true }, "vendor_data": { "type": "string", "description": "可选的不透明标识符（您的用户 ID、邮箱、UUID 等），存储在持久化会话中并予以回显。还用于在重复人脸检查中排除具有相同 `vendor_data` 的先前会话，从而避免在重新验证同一用户时触发 `DUPLICATED_FACE`。", "example": "user-123" }, "metadata": { "type": "object", "additionalProperties": true, "description": "与会话一同存储（当 `save_api_request=true` 时）并原样返回的可选 JSON 对象。在 multipart 请求中，请将其作为 JSON 编码的字符串字段发送，它将被解析为对象。", "example": { "flow": "withdrawal" } } } }, "example": { "user_image": "(binary JPEG/PNG selfie)", "face_liveness_score_decline_threshold": 30, "rotate_image": false, "save_api_request": true, "vendor_data": "user-123", "metadata": { "flow": "withdrawal" } } } } }, "responses": { "200": { "description": "静默活体检测已完成。`liveness.score` 是模型对图像显示为活人的置信度（0–100）；除非触发了 `error` 严重级别的警告，否则 `status` 为 `Approved`。欺骗攻击或处于黑名单的人脸仍会返回 `200`，请检查 `liveness.status` 和 `liveness.warnings`，而不仅仅是 HTTP 状态码。当 `save_api_request=true` 时，`request_id` 为持久化的会话 ID。", "content": { "application/json": { "examples": { "Approved": { "summary": "活体面部 — 无警告", "value": { "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef", "liveness": { "status": "Approved", "method": "PASSIVE", "score": 95.0, "user_image": { "entities": [ { "bbox": [ 661, 728, 1688, 2188 ], "confidence": 0.732973, "age": 26.91, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [], "face_quality": 84.21, "face_luminance": 50.33 }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Declined - presentation attack": { "summary": "模型标记了欺骗攻击（打印件、重放、面具等）", "value": { "request_id": "f1c8c9b2-d3e4-4f5a-9b8c-7d6e5f4a3b2c", "liveness": { "status": "Declined", "method": "PASSIVE", "score": 12.5, "user_image": { "entities": [ { "bbox": [ 100, 120, 420, 540 ], "confidence": 0.81, "age": 30.1, "gender": "female", "race": null } ], "best_angle": 0 }, "warnings": [ { "risk": "LOW_LIVENESS_SCORE", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Low liveness score", "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data." }, { "risk": "LIVENESS_FACE_ATTACK", "feature": "LIVENESS", "additional_data": null, "log_type": "error", "short_description": "Liveness Face Attack", "long_description": "The system detected a potential attempt to bypass the liveness check." } ], "face_quality": 72.4, "face_luminance": 48.2 }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } }, "Declined - face on blocklist": { "summary": "活体面部，但命中了黑名单条目", "value": { "request_id": "0b54a1de-22aa-4e0f-9c84-5a2b1f3c4d5e", "liveness": { "status": "Declined", "method": "PASSIVE", "score": 93.75, "user_image": { "entities": [ { "bbox": [ 40, 40, 100, 100 ], "confidence": 0.722082, "age": 27.0, "gender": "male", "race": null } ], "best_angle": 0 }, "warnings": [ { "risk": "FACE_IN_BLOCKLIST", "feature": "LIVENESS", "additional_data": { "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86", "blocklisted_session_number": 3242, "api_service": null }, "log_type": "error", "short_description": "Face in blocklist", "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified." } ], "face_quality": null, "face_luminance": null }, "vendor_data": "user-123", "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } } }, "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。" }, "liveness": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "当触发了至少一个 `error` 严重级别的警告（无人脸、低分、呈现攻击或命中黑名单）时为 `Declined`；否则为 `Approved`。`warning`/`information` 项（多张人脸、重复项）本身绝不会导致拒绝。" }, "method": { "type": "string", "enum": [ "PASSIVE" ], "description": "对于此 endpoint 始终为 `PASSIVE`。" }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "活体置信度（0–100，保留两位小数），表示图像描绘的是活体真人而非欺骗攻击的置信度。当模型未返回置信度时为 `null`。", "example": 95.0 }, "user_image": { "type": "object", "description": "已提交图像的人脸检测结果。", "properties": { "entities": { "type": "array", "items": { "type": "object", "properties": { "bbox": { "type": "array", "items": { "type": "integer" }, "minItems": 4, "maxItems": 4, "description": "检测到的人脸边界框，表示为处理后图像中的 `[x_min, y_min, x_max, y_max]` 像素坐标。", "example": [ 661, 728, 1688, 2188 ] }, "confidence": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "description": "人脸检测置信度（0–1）。", "example": 0.732973 }, "age": { "type": "number", "format": "float", "description": "检测到的人脸的模型估算年龄（以岁为单位）。仅供参考，不影响活体检测决策。", "example": 26.91 }, "gender": { "type": "string", "description": "模型预测的检测人脸性别（`male` 或 `female`）。仅供参考。", "example": "male" }, "race": { "type": "string", "nullable": true, "description": "保留字段 — 在此 endpoint 的响应中始终为 `null`。", "example": null } } }, "description": "每张检测到的人脸对应一个条目。以最大的人脸为准进行评估。" }, "best_angle": { "type": "integer", "nullable": true, "description": "产生最佳人脸检测结果的旋转角度（度）；仅当 `rotate_image=true` 纠正了方向时才为非零值。", "example": 0 } } }, "warnings": { "type": "array", "description": "风险信号。`error` 严重级别（拒绝）：`NO_FACE_DETECTED`、`LOW_LIVENESS_SCORE`（分数低于或等于阈值）、`LIVENESS_FACE_ATTACK`、`FACE_IN_BLOCKLIST`、`POSSIBLE_FACE_IN_BLOCKLIST`。`warning` 严重级别（审核，不拒绝）：`MULTIPLE_FACES_DETECTED`。`information` 严重级别（不拒绝）：`DUPLICATED_FACE`、`POSSIBLE_DUPLICATED_FACE`（同一张人脸已出现在另一个已通过的会话中）。", "items": { "type": "object", "properties": { "risk": { "type": "string", "enum": [ "NO_FACE_DETECTED", "LOW_LIVENESS_SCORE", "LIVENESS_FACE_ATTACK", "MULTIPLE_FACES_DETECTED", "FACE_IN_BLOCKLIST", "POSSIBLE_FACE_IN_BLOCKLIST", "DUPLICATED_FACE", "POSSIBLE_DUPLICATED_FACE" ], "description": "机器可读的风险代码。" }, "feature": { "type": "string", "enum": [ "LIVENESS" ], "description": "引发该警告的功能。在此 endpoint 上始终为 `LIVENESS`。" }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "大多数警告为 `null`。黑名单命中会携带 `{blocklisted_session_id, blocklisted_session_number, api_service}`；重复命中会携带指向匹配会话的 `{duplicated_session_id, duplicated_session_number, api_service}`。" }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "严重程度。`error` 警告会导致 `status` 变为 `Declined`；`warning` 和 `information` 条目仅供参考，本身绝不会导致拒绝。" }, "short_description": { "type": "string", "description": "易于阅读的单行风险摘要。" }, "long_description": { "type": "string", "description": "风险的便于人类阅读的说明。" } } } }, "face_quality": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "检测到人脸的采集质量分数，已归一化至 0–100。当模型无法生成可靠值时为 `null`。", "example": 84.21 }, "face_luminance": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "检测到的人脸亮度，归一化为 0–100。不可用时为 `null`。", "example": 50.33 } } }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，或 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 对象回显，或 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "响应生成时的 ISO 8601 时间戳（UTC），例如 `2026-06-12T01:04:42.763237+00:00`。" } } } } } }, "400": { "description": "验证错误。当 `user_image` 缺失、超过 5 MB、扩展名不受支持、服务端图像解码失败，或选项超出范围时返回。字段错误使用 DRF 的 `{field: [messages]}` 响应格式；图像解码失败使用 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing image": { "summary": "表单数据中未包含 `user_image`", "value": { "user_image": [ "No file was submitted." ] } }, "Invalid image format": { "summary": "扩展名允许，但图像内容无法解码", "value": { "error": "Invalid user image format.", "code": "invalid_image" } }, "Unsupported file extension": { "summary": "文件扩展名不在 tiff/jpg/jpeg/png/webp 范围内", "value": { "user_image": [ "File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp." ] } }, "File too large": { "summary": "上传内容超过 5 MB 限制", "value": { "user_image": [ "File size should not exceed 5 MB" ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头，或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何图像处理之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/passive-liveness/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'user_image=@./selfie.jpg' \\\n -F 'face_liveness_score_decline_threshold=30' \\\n -F 'save_api_request=true' \\\n -F 'vendor_data=user-123'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.passive_liveness.check(\n user_image=open(\"user_image.jpg\", \"rb\"),\n face_liveness_score_decline_threshold=30.0,\n rotate_image=False,\n save_api_request=True,\n vendor_data=\"user-123\",\n metadata={\"flow\": \"withdrawal\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.passiveLiveness.check({\n user_image: await fileFromPath(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"withdrawal\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.PassiveLiveness.Check(ctx, didit.PassiveLivenessCheckParams{\n\tUserImage: didit.FileFromPath(\"user_image.jpg\"),\n\tFaceLivenessScoreDeclineThreshold: didit.Float(30.0),\n\tRotateImage: didit.Bool(false),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"withdrawal\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.PassiveLivenessCheckParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.passiveLiveness().check(PassiveLivenessCheckParams.builder()\n .userImage(Path.of(\"user_image.jpg\"))\n .faceLivenessScoreDeclineThreshold(30.0)\n .rotateImage(false)\n .saveApiRequest(true)\n .vendorData(\"user-123\")\n .metadata(Map.of(\"flow\", \"withdrawal\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "passiveLiveness->check([\n 'user_image' => File::fromPath('user_image.jpg'),\n 'face_liveness_score_decline_threshold' => 30.0,\n 'rotate_image' => false,\n 'save_api_request' => true,\n 'vendor_data' => 'user-123',\n 'metadata' => ['flow' => 'withdrawal'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.passive_liveness.check(\n user_image: Pathname(\"user_image.jpg\"),\n face_liveness_score_decline_threshold: 30.0,\n rotate_image: false,\n save_api_request: true,\n vendor_data: \"user-123\",\n metadata: { flow: \"withdrawal\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.PassiveLiveness.CheckAsync(new PassiveLivenessCheckParams\n{\n UserImage = FileUpload.FromPath(\"user_image.jpg\"),\n FaceLivenessScoreDeclineThreshold = 30.0,\n RotateImage = false,\n SaveApiRequest = true,\n VendorData = \"user-123\",\n Metadata = new Dictionary { [\"flow\"] = \"withdrawal\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/database-validation/": { "post": { "summary": "数据库核验（独立）", "operationId": "post_v3database-validation", "x-didit-sdk": { "resource": "database_validation", "method": "validate", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "根据官方政府和登记机构数据源核验个人的身份数据，包括巴西的 CPF、阿根廷的 RENAPER、西班牙和秘鲁的 DNI 登记库、墨西哥的 INE，以及覆盖 60+ 个国家/地区的 100+ 项服务。\n\n**服务选择。** 每个国家/地区公开一个或多个由 `service_id` 标识的目录服务（例如 `bra_cpf`、`arg_renaper`、`pan_cedula_sib`）。通过 `services` 数组指定您需要的服务；如果省略该参数，则仅运行**一个**默认服务（该国家/地区运营时间最长的生产环境服务）。传递 `services` 还会将响应切换为包含 `services_used` 和 `match_score` 的扩展结构。通过 `GET /v1/organization/database-validation-countries/`（本规范中未记录的目录 endpoint）或 Business Console 工作流编辑器发现服务、其必填字段及价格。目录中部分服务被标记为 `requires_consent=true` 并要求 `consent=true`；其他服务在调用前需要为您的组织进行入驻配置。\n\n**输入字段。** `identification_number` 是一个通用字段，会自动映射到特定国家/地区的正确字段（请参见其描述）。在调用任何提供商之前都会强制执行国家/地区格式规则（例如巴西 CPF 必须正好是 11 位数字），格式错误绝不计费。生物识别服务需要上传 `selfie`（仅限 multipart）；阿根廷 RENAPER 还需要 `gender`。\n\n**结果。** 每个服务返回逐字段的 `validation` 映射以及与供应商无关的 `outcome_code`（`MATCH`、`PARTIAL_MATCH`、`NO_MATCH`、`DOCUMENT_NOT_FOUND`、`INVALID_DOCUMENT_FORMAT`、`INVALID_INPUT`、`MINOR_BLOCKED`、`DECEASED`、`BIOMETRIC_NO_MATCH`、`BIOMETRIC_IMAGE_UNUSABLE`、`INCONCLUSIVE`、`DOCUMENT_SUPERSEDED`、`REGISTRY_UNAVAILABLE`、`REGISTRY_ERROR`）。请注意以下区别：`NO_MATCH` 表示明确不匹配；`INCONCLUSIVE` 表示登记库无法确认任一结果（审核，而非拒绝）；`BIOMETRIC_IMAGE_UNUSABLE` 是技术性自拍问题（重新拍摄），与明确的 `BIOMETRIC_NO_MATCH` 不同。总体 `match_type` 跨服务聚合（任意完全匹配 → `full_match`，否则任意部分匹配 → `partial_match`，否则 `no_match`），且 `no_match_action`/`partial_match_action` 将其转换为最终的 `status`。`validation_type` 为派生值：当两个或更多不同服务生成完全匹配（针对证件号码、针对姓名 + 出生日期组合，或针对地址且无冲突）时为 `two_by_two`，否则为 `one_by_one`。\n\n**持久化。** `save_api_request` 默认为 **true**：结果将作为会话保存（`request_id` 可用于 `GET /v3/session/{sessionId}/decision/`），显示在控制台中，并触发 `status.updated` Webhook。它还控制 `validations` 结构：保存时为按服务划分的对象，未保存时为合并后的 `{field: match}` 映射。\n\n**计费。** 按服务计费：每个返回可计费结果的服务均按其自身的目录价格收费。失败或跳过的服务不予计费，被 `400` 拒绝的请求不收取任何费用。预检余额检查涵盖所选服务价格的总和（不足时返回 `403`）。\n\n**失败。** 当所选服务均未返回可用结果时，如果每次未得到回答的尝试均明确拒绝了输入（`provider_rejected_input`，`retryable: false`），API 将返回 `400` 及 `validation_errors`。请在重试前更正输入。否则，API 将返回 `502` 及 `validation_errors`（`empty_provider_response`，`retryable: true`），包括输入被拒绝与备用尝试不可用的混合情况；不收取任何费用（当 `save_api_request=true` 时，仍会记录状态为 `Not Finished` 的会话）。当仅有部分服务失败时，`200` 响应会在 `database_validation.errors` 中携带其失败信息。\n\n**沙盒。** 来自沙盒应用的密钥会跳过登记库调用和计费，并返回静态的 `full_match` 响应。无论 `services` 如何发送，沙盒 payload 始终包含 `services_used` 和 `match_score: 100`，因此不要针对沙盒响应验证生产环境的扩展结构限制或 0.0–1.0 的 `match_score` 小数值。\n\n以 `application/json` 格式发送请求，上传 `selfie` 时以 `multipart/form-data` 格式发送。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "issuing_state" ], "properties": { "issuing_state": { "type": "string", "description": "用于验证的目标登记处的 ISO 3166-1 **alpha-3** 国家/地区代码（例如 `BRA`、`ESP`、`COL`）。决定哪些服务可用。不受支持的代码将返回 `400` 及有效选项的完整列表。", "example": "BRA" }, "services": { "type": "array", "items": { "type": "string" }, "description": "针对此国家/地区要运行的目录 `service_id` 列表（例如 `[\"bra_cpf\"]`）。也接受单个字符串或以逗号分隔/JSON 编码的字符串。**如果省略或为空，将仅运行一个默认服务** — 即该国家/地区上线时间最长的生产环境服务；较新的、生物识别及按量计费的服务必须显式指定。发送 `services` 会将响应切换为扩展形式（添加 `services_used` 和 `match_score`）。每个 ID 必须存在且对该 `issuing_state` 处于可用状态；需要入驻的服务在为您的组织激活前将返回 `400`。可通过 `GET /v1/organization/database-validation-countries/`（本规范中未记载的目录 endpoint）或 Business Console 工作流编辑器发现每个国家/地区的可用服务。", "example": [ "bra_cpf" ] }, "validation_type": { "type": "string", "deprecated": true, "description": "已弃用。为向后兼容而接受但会被忽略，响应中的 `validation_type` 现在取决于完全匹配的服务数量。使用 `services` 可固定指定的服务。" }, "consent": { "type": "boolean", "default": false, "description": "当终端用户明确同意所选验证服务时设为 `true`。目录中标记为 `requires_consent=true` 的服务必须提供 — 若未提供，这些服务将返回 `400` 以及 `services_requiring_consent`。" }, "identification_number": { "type": "string", "description": "通用身份识别号，自动映射到特定国家/地区的正确字段，因此您可以用来代替 `personal_number`/`tax_number`/`document_number`：ARG→document_number (DNI)、BOL→document_number (CI)、BRA→tax_number (CPF，11 位数字)、CHL→personal_number (RUT)、COL→personal_number (Cédula)、CRI→personal_number (Cédula)、DOM→personal_number (Cédula，11 位数字)、ECU→personal_number (Cédula，10 位数字)、ESP→personal_number (DNI/NIE)、GTM→document_number (DPI)、HND→document_number (DNI)、MEX→personal_number (CURP，18 位字符)、PAN→personal_number (Cédula)、PER→personal_number (DNI，8 位数字)、PRY→document_number (CI)、SLV→document_number (DUI)、URY→personal_number (CI)、VEN→document_number (Cédula)。它绝不会覆盖显式提供的特定国家/地区字段。" }, "first_name": { "type": "string", "description": "个人的名字。某些服务/国家/地区要求必填。", "example": "John" }, "last_name": { "type": "string", "description": "个人的姓氏。某些服务/国家/地区要求必填。", "example": "Doe" }, "middle_name": { "type": "string", "description": "中间名，由部分国家/地区服务使用（澳大利亚、新西兰等）。" }, "full_name": { "type": "string", "description": "姓名 — 部分服务接受以此代替名/姓（例如 CHN 服务，用于比对原生文字系统中的姓名）。" }, "date_of_birth": { "type": "string", "format": "date", "description": "出生日期，`YYYY-MM-DD`。许多服务均要求提供。", "example": "1980-01-01" }, "personal_number": { "type": "string", "description": "政府签发的唯一个人身份标识。适用地区：CHL (RUT)、COL (Cédula)、CRI、DOM、ECU、ESP (DNI/NIE)、MEX (CURP)、PAN (Cédula)、PER (DNI)、URY。建议改用 `identification_number`。" }, "tax_number": { "type": "string", "description": "税号。适用地区：BRA（CPF，11 位数字）。建议改用 `identification_number`。" }, "document_number": { "type": "string", "description": "证件号码。适用于：ARG (DNI)、BOL (CI)、GTM (DPI)、HND (DNI)、PRY (CI)、SLV (DUI)、VEN (Cédula)。建议改用 `identification_number`。" }, "document_type": { "type": "string", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "description": "正在核验的证件类型：`P` 护照、`DL` 驾驶证、`ID` 国民身份证、`RP` 居留许可（以及 `SSC`、`HIC`、`WP`、`TC`、`VISA`、`PSC`、`BC`、`OTHER`）。某些服务需要此字段（例如 ESP）。" }, "expiration_date": { "type": "string", "format": "date", "description": "证件到期日期，`YYYY-MM-DD`。ESP（西班牙）核验必填。", "example": "2030-01-15" }, "date_of_issue": { "type": "string", "format": "date", "description": "证件签发日期，`YYYY-MM-DD`（fecha de expedición）。COL（哥伦比亚）身份证（cédula）核验必填。", "example": "2015-06-20" }, "nationality": { "type": "string", "description": "ISO 3166-1 alpha-3 格式的国籍。某些服务需要此字段。" }, "gender": { "type": "string", "enum": [ "M", "F", "X" ], "description": "性别：`M`、`F` 或 `X`（其他/未知）。阿根廷的 RENAPER 核验（`arg_renaper`）必填。" }, "address": { "description": "居住地址。建议使用结构化对象 `{\"street_1\":\"123 Main St\",\"street_2\":\"Apt 4B\",\"city\":\"Springfield\",\"region\":\"IL\",\"postal_code\":\"62701\",\"country\":\"US\"}`；仍接受完整的单行字符串。地址验证服务要求必填；当某项服务定义了地址要求时，缺少部分将返回 `400` 以及 `address_fields_required_by`。", "oneOf": [ { "type": "object", "properties": { "street_1": { "type": "string" }, "street_2": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, { "type": "string", "description": "完整的单行地址（旧版）。" } ] }, "address_element_1": { "type": "string", "description": "街道地址，包括门牌号和道路类型。如果省略，则从 `address` 推导。" }, "address_element_2": { "type": "string", "description": "公寓、单元、楼栋、楼层或补充地址行。仅在明确掌握该信息时发送。" }, "address_element_3": { "type": "string", "description": "城市、郊区、区、地方或街区。如果省略，则从 `address` 派生。" }, "address_element_4": { "type": "string", "description": "州、省、地区或城镇。如果省略，则从 `address` 推导。" }, "address_element_5": { "type": "string", "description": "邮政编码。接受 `postal_code` 作为别名。" }, "postal_code": { "type": "string", "description": "基于地址的服务的邮政编码（`address_element_5` 的别名）。" }, "driver_license_number": { "type": "string", "description": "用于政府证件验证服务（AUS、NZL、IND）的驾照号码。" }, "driver_license_card_number": { "type": "string", "description": "实体驾照卡号，当与驾照号码（澳大利亚）分开要求时使用。" }, "driver_license_state": { "type": "string", "description": "驾照签发州或领地（AUS）。" }, "driver_license_version": { "type": "string", "description": "驾照版本代码（NZL）。" }, "passport_number": { "type": "string", "description": "用于政府护照核验服务（澳大利亚 AUS、新西兰 NZL、印度 IND、中国 CHN）的护照号码。" }, "passport_expiration_date": { "type": "string", "format": "date", "description": "护照到期日期，格式为 `YYYY-MM-DD`，用于护照核验服务。" }, "passport_file_number": { "type": "string", "description": "护照文件编号（IND）。" }, "passport_issue_country": { "type": "string", "description": "护照验证服务所使用的护照签发国家/地区（ISO 3166-1 alpha-3）。" }, "medicare_card_number": { "type": "string", "description": "Medicare 卡号（澳大利亚）。" }, "immi_card_number": { "type": "string", "description": "澳大利亚 ImmiCard 号码。" }, "immi_card_expiry_date": { "type": "string", "format": "date", "description": "澳大利亚 ImmiCard 到期日期。" }, "citizenship_certificate_number": { "type": "string", "description": "公民身份证书编号（澳大利亚）。" }, "birth_registration_number": { "type": "string", "description": "出生证明登记号（澳大利亚）。" }, "birth_registration_date": { "type": "string", "format": "date", "description": "出生证明登记日期（澳大利亚）。" }, "birth_registration_state": { "type": "string", "description": "出生证明登记州（澳大利亚）。" }, "marriage_certificate_number": { "type": "string", "description": "结婚证明编号（澳大利亚）。" }, "change_of_name_certificate_number": { "type": "string", "description": "更名证明编号（澳大利亚）。" }, "first_partner_name": { "type": "string", "description": "结婚证上配偶的名（澳大利亚）。" }, "last_partner_name": { "type": "string", "description": "结婚证上配偶的姓氏（澳大利亚）。" }, "voter_id": { "type": "string", "description": "选民登记号（IND EPIC、IRL）。" }, "epic_card": { "type": "string", "description": "印度 EPIC 选民卡号。" }, "pan": { "type": "string", "description": "印度 PAN（永久账号）。" }, "national_id": { "type": "string", "description": "国民身份证号（CHN、MYS、KEN、KHM、NGA、ZAF、……）。" }, "cic": { "type": "string", "description": "墨西哥 INE/IFE 凭证识别码（CIC，Código de Identificación de Credencial），9 位数字。由墨西哥 INE 凭据有效性核验服务（`mex_ine_vigencia`）使用。" }, "identificador_ciudadano": { "type": "string", "description": "墨西哥 INE 公民标识符（Identificador del Ciudadano，9 位数字）。在 `mex_ine_vigencia` 中与 `cic` 一起用于现代 INE 型号（E/F/G/H）。" }, "ocr": { "type": "string", "description": "墨西哥 INE OCR 编号（13 位数字，卡片背面）。在 `mex_ine_vigencia` 中与 `cic` 一起用于 D 型号。" }, "voter_number": { "type": "string", "description": "墨西哥 INE 选民识别码（Clave de Elector，18 位字符）。在 `mex_ine_vigencia` 中与 `emission_number` 一起用于旧版 IFE 型号（A/B/C）。" }, "emission_number": { "type": "string", "description": "墨西哥 INE 签发编号（Número de Emisión）。在 `mex_ine_vigencia` 中与 `voter_number` 一起用于旧版 IFE 型号（A/B/C）。" }, "bvn": { "type": "string", "description": "尼日利亚银行验证号码（BVN）。" }, "bank_card_number": { "type": "string", "description": "银行卡号（中国银行卡验证）。" }, "company_registration_number": { "type": "string", "description": "公司登记机构签发的企业注册号：如巴西的 CNPJ（例如 `11222333000181`）、南非的注册号（例如 `1936/007721/06`）。公司登记和企业董事服务（`bra_company_registry`、`bra_company_directors`、`zaf_company_registry`、`zaf_company_directors`）需要此参数。" }, "company_name": { "type": "string", "description": "注册公司名称，与登记条目进行交叉比对。对于 `zaf_company_registry` 可选。" }, "initials": { "type": "string", "description": "证件上印制的该人员姓名首字母缩写。`zaf_drivers_license` 必需；`zaf_bank_account_holder` 可接受。" }, "licence_number": { "type": "string", "description": "卡片上印制的驾照号码，适用于 `zaf_drivers_license`。省略时，使用 `document_number`。" }, "refugee_file_number": { "type": "string", "description": "南非内政部签发的难民档案号。`zaf_refugee` 所需。" }, "bank_name": { "type": "string", "description": "开户银行名称。`zaf_bank_account_holder` 必填。" }, "bank_account_number": { "type": "string", "description": "银行账号。`zaf_bank_account_holder` 必填；`zaf_fraud_prevention` 可接受。" }, "account_type": { "type": "string", "description": "`zaf_bank_account_holder` 的银行账户类型：`current`、`savings`、`transmission`、`subscriptionShare` 或 `notKnown`，不区分大小写。任何其他值返回 `400`。未知类型时请省略：账户类型交叉比对随后将报告为未确认。" }, "phone_number": { "type": "string", "description": "联系手机号码，用于交叉核验可联络性的服务（`zaf_bank_account_holder`、`zaf_fraud_prevention`、`zaf_refugee`）。" }, "right_thumb": { "type": "string", "description": "用于 `zaf_dha_fingerprint_match` 的 Base64 编码右手拇指指纹，可与 `left_thumb` 一起提供或单独提供。" }, "left_thumb": { "type": "string", "description": "用于 `zaf_dha_fingerprint_match` 的 Base64 编码左手拇指指纹，可与 `right_thumb` 一起提供或单独提供。" }, "score_level": { "type": "integer", "description": "`zaf_criminal_face_screening` 的最低生物识别评分等级。默认为 `3`。" }, "max_matches": { "type": "integer", "description": "`zaf_criminal_face_screening` 返回的候选匹配项最大数量。默认值为 `1`。" }, "vehicle_register_number": { "type": "string", "description": "车辆登记编号。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_licence_plate` 和 `vin` 一同提供。" }, "vehicle_licence_plate": { "type": "string", "description": "车辆号牌号码。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_register_number` 和 `vin` 一同提供。" }, "vin": { "type": "string", "description": "车辆识别代号（VIN 或车架号）。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_register_number` 和 `vehicle_licence_plate` 一同提供。" }, "ssn": { "type": "string", "description": "社会安全号码（美国）。" }, "phone": { "type": "string", "description": "用于电话验证服务的电话号码。" }, "landline": { "type": "string", "description": "用于电话验证服务的座机号码。" }, "email": { "type": "string", "format": "email", "description": "用于身份验证服务的邮箱地址。" }, "country_of_residence": { "type": "string", "description": "居住国家/地区的 ISO 3166-1 alpha-2 代码。供全球身份信息增强服务（例如 `glb_identity_enrichment`）用于限定查询范围。", "example": "US" }, "partial_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "NO_ACTION", "description": "`partial_match` 对 `database_validation.status` 的影响。默认值为 `NO_ACTION`（状态保持为 `Approved`，并附带警告）。" }, "no_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "`no_match` 对 `database_validation.status` 的影响。默认值为 `DECLINE`。" }, "save_api_request": { "type": "boolean", "default": true, "description": "将核验持久化为会话（控制台可见性、决策 endpoint、`status.updated` Webhook）。同时会改变 `validations` 响应的格式：为 `true`（默认）时按服务返回对象，为 `false` 时返回合并的字段映射。" }, "vendor_data": { "type": "string", "description": "您为已核验用户指定的标识符；将原样返回并与会话一起存储。" }, "metadata": { "type": "object", "nullable": true, "description": "随请求一同存储并回显的自由格式 JSON。" } } }, "example": { "issuing_state": "BRA", "services": [ "bra_cpf" ], "identification_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01", "vendor_data": "user-1234" } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "issuing_state" ], "properties": { "issuing_state": { "type": "string", "description": "用于验证的目标登记处的 ISO 3166-1 **alpha-3** 国家/地区代码（例如 `BRA`、`ESP`、`COL`）。决定哪些服务可用。不受支持的代码将返回 `400` 及有效选项的完整列表。", "example": "BRA" }, "services": { "type": "array", "items": { "type": "string" }, "description": "针对此国家/地区要运行的目录 `service_id` 列表（例如 `[\"bra_cpf\"]`）。也接受单个字符串或以逗号分隔/JSON 编码的字符串。**如果省略或为空，将仅运行一个默认服务** — 即该国家/地区上线时间最长的生产环境服务；较新的、生物识别及按量计费的服务必须显式指定。发送 `services` 会将响应切换为扩展形式（添加 `services_used` 和 `match_score`）。每个 ID 必须存在且对该 `issuing_state` 处于可用状态；需要入驻的服务在为您的组织激活前将返回 `400`。可通过 `GET /v1/organization/database-validation-countries/`（本规范中未记载的目录 endpoint）或 Business Console 工作流编辑器发现每个国家/地区的可用服务。", "example": [ "bra_cpf" ] }, "validation_type": { "type": "string", "deprecated": true, "description": "已弃用。为向后兼容而接受但会被忽略，响应中的 `validation_type` 现在取决于完全匹配的服务数量。使用 `services` 可固定指定的服务。" }, "consent": { "type": "boolean", "default": false, "description": "当终端用户明确同意所选验证服务时设为 `true`。目录中标记为 `requires_consent=true` 的服务必须提供 — 若未提供，这些服务将返回 `400` 以及 `services_requiring_consent`。" }, "identification_number": { "type": "string", "description": "通用身份识别号，自动映射到特定国家/地区的正确字段，因此您可以用来代替 `personal_number`/`tax_number`/`document_number`：ARG→document_number (DNI)、BOL→document_number (CI)、BRA→tax_number (CPF，11 位数字)、CHL→personal_number (RUT)、COL→personal_number (Cédula)、CRI→personal_number (Cédula)、DOM→personal_number (Cédula，11 位数字)、ECU→personal_number (Cédula，10 位数字)、ESP→personal_number (DNI/NIE)、GTM→document_number (DPI)、HND→document_number (DNI)、MEX→personal_number (CURP，18 位字符)、PAN→personal_number (Cédula)、PER→personal_number (DNI，8 位数字)、PRY→document_number (CI)、SLV→document_number (DUI)、URY→personal_number (CI)、VEN→document_number (Cédula)。它绝不会覆盖显式提供的特定国家/地区字段。" }, "first_name": { "type": "string", "description": "个人的名字。某些服务/国家/地区要求必填。", "example": "John" }, "last_name": { "type": "string", "description": "个人的姓氏。某些服务/国家/地区要求必填。", "example": "Doe" }, "middle_name": { "type": "string", "description": "中间名，由部分国家/地区服务使用（澳大利亚、新西兰等）。" }, "full_name": { "type": "string", "description": "姓名 — 部分服务接受以此代替名/姓（例如 CHN 服务，用于比对原生文字系统中的姓名）。" }, "date_of_birth": { "type": "string", "format": "date", "description": "出生日期，`YYYY-MM-DD`。许多服务均要求提供。", "example": "1980-01-01" }, "personal_number": { "type": "string", "description": "政府签发的唯一个人身份标识。适用地区：CHL (RUT)、COL (Cédula)、CRI、DOM、ECU、ESP (DNI/NIE)、MEX (CURP)、PAN (Cédula)、PER (DNI)、URY。建议改用 `identification_number`。" }, "tax_number": { "type": "string", "description": "税号。适用地区：BRA（CPF，11 位数字）。建议改用 `identification_number`。" }, "document_number": { "type": "string", "description": "证件号码。适用于：ARG (DNI)、BOL (CI)、GTM (DPI)、HND (DNI)、PRY (CI)、SLV (DUI)、VEN (Cédula)。建议改用 `identification_number`。" }, "document_type": { "type": "string", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "description": "正在核验的证件类型：`P` 护照、`DL` 驾驶证、`ID` 国民身份证、`RP` 居留许可（以及 `SSC`、`HIC`、`WP`、`TC`、`VISA`、`PSC`、`BC`、`OTHER`）。某些服务需要此字段（例如 ESP）。" }, "expiration_date": { "type": "string", "format": "date", "description": "证件到期日期，`YYYY-MM-DD`。ESP（西班牙）核验必填。", "example": "2030-01-15" }, "date_of_issue": { "type": "string", "format": "date", "description": "证件签发日期，`YYYY-MM-DD`（fecha de expedición）。COL（哥伦比亚）身份证（cédula）核验必填。", "example": "2015-06-20" }, "nationality": { "type": "string", "description": "ISO 3166-1 alpha-3 格式的国籍。某些服务需要此字段。" }, "gender": { "type": "string", "enum": [ "M", "F", "X" ], "description": "性别：`M`、`F` 或 `X`（其他/未知）。阿根廷的 RENAPER 核验（`arg_renaper`）必填。" }, "address": { "description": "居住地址。建议使用结构化对象 `{\"street_1\":\"123 Main St\",\"street_2\":\"Apt 4B\",\"city\":\"Springfield\",\"region\":\"IL\",\"postal_code\":\"62701\",\"country\":\"US\"}`；仍接受完整的单行字符串。地址验证服务要求必填；当某项服务定义了地址要求时，缺少部分将返回 `400` 以及 `address_fields_required_by`。", "oneOf": [ { "type": "object", "properties": { "street_1": { "type": "string" }, "street_2": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, { "type": "string", "description": "完整的单行地址（旧版）。" } ] }, "address_element_1": { "type": "string", "description": "街道地址，包括门牌号和道路类型。如果省略，则从 `address` 推导。" }, "address_element_2": { "type": "string", "description": "公寓、单元、楼栋、楼层或补充地址行。仅在明确掌握该信息时发送。" }, "address_element_3": { "type": "string", "description": "城市、郊区、区、地方或街区。如果省略，则从 `address` 派生。" }, "address_element_4": { "type": "string", "description": "州、省、地区或城镇。如果省略，则从 `address` 推导。" }, "address_element_5": { "type": "string", "description": "邮政编码。接受 `postal_code` 作为别名。" }, "postal_code": { "type": "string", "description": "基于地址的服务的邮政编码（`address_element_5` 的别名）。" }, "driver_license_number": { "type": "string", "description": "用于政府证件验证服务（AUS、NZL、IND）的驾照号码。" }, "driver_license_card_number": { "type": "string", "description": "实体驾照卡号，当与驾照号码（澳大利亚）分开要求时使用。" }, "driver_license_state": { "type": "string", "description": "驾照签发州或领地（AUS）。" }, "driver_license_version": { "type": "string", "description": "驾照版本代码（NZL）。" }, "passport_number": { "type": "string", "description": "用于政府护照核验服务（澳大利亚 AUS、新西兰 NZL、印度 IND、中国 CHN）的护照号码。" }, "passport_expiration_date": { "type": "string", "format": "date", "description": "护照到期日期，格式为 `YYYY-MM-DD`，用于护照核验服务。" }, "passport_file_number": { "type": "string", "description": "护照文件编号（IND）。" }, "passport_issue_country": { "type": "string", "description": "护照验证服务所使用的护照签发国家/地区（ISO 3166-1 alpha-3）。" }, "medicare_card_number": { "type": "string", "description": "Medicare 卡号（澳大利亚）。" }, "immi_card_number": { "type": "string", "description": "澳大利亚 ImmiCard 号码。" }, "immi_card_expiry_date": { "type": "string", "format": "date", "description": "澳大利亚 ImmiCard 到期日期。" }, "citizenship_certificate_number": { "type": "string", "description": "公民身份证书编号（澳大利亚）。" }, "birth_registration_number": { "type": "string", "description": "出生证明登记号（澳大利亚）。" }, "birth_registration_date": { "type": "string", "format": "date", "description": "出生证明登记日期（澳大利亚）。" }, "birth_registration_state": { "type": "string", "description": "出生证明登记州（澳大利亚）。" }, "marriage_certificate_number": { "type": "string", "description": "结婚证明编号（澳大利亚）。" }, "change_of_name_certificate_number": { "type": "string", "description": "更名证明编号（澳大利亚）。" }, "first_partner_name": { "type": "string", "description": "结婚证上配偶的名（澳大利亚）。" }, "last_partner_name": { "type": "string", "description": "结婚证上配偶的姓氏（澳大利亚）。" }, "voter_id": { "type": "string", "description": "选民登记号（IND EPIC、IRL）。" }, "epic_card": { "type": "string", "description": "印度 EPIC 选民卡号。" }, "pan": { "type": "string", "description": "印度 PAN（永久账号）。" }, "national_id": { "type": "string", "description": "国民身份证号（CHN、MYS、KEN、KHM、NGA、ZAF、……）。" }, "cic": { "type": "string", "description": "墨西哥 INE/IFE 凭证识别码（CIC，Código de Identificación de Credencial），9 位数字。由墨西哥 INE 凭据有效性核验服务（`mex_ine_vigencia`）使用。" }, "identificador_ciudadano": { "type": "string", "description": "墨西哥 INE 公民标识符（Identificador del Ciudadano，9 位数字）。在 `mex_ine_vigencia` 中与 `cic` 一起用于现代 INE 型号（E/F/G/H）。" }, "ocr": { "type": "string", "description": "墨西哥 INE OCR 编号（13 位数字，卡片背面）。在 `mex_ine_vigencia` 中与 `cic` 一起用于 D 型号。" }, "voter_number": { "type": "string", "description": "墨西哥 INE 选民识别码（Clave de Elector，18 位字符）。在 `mex_ine_vigencia` 中与 `emission_number` 一起用于旧版 IFE 型号（A/B/C）。" }, "emission_number": { "type": "string", "description": "墨西哥 INE 签发编号（Número de Emisión）。在 `mex_ine_vigencia` 中与 `voter_number` 一起用于旧版 IFE 型号（A/B/C）。" }, "bvn": { "type": "string", "description": "尼日利亚银行验证号码（BVN）。" }, "bank_card_number": { "type": "string", "description": "银行卡号（中国银行卡验证）。" }, "company_registration_number": { "type": "string", "description": "公司登记机构签发的企业注册号：如巴西的 CNPJ（例如 `11222333000181`）、南非的注册号（例如 `1936/007721/06`）。公司登记和企业董事服务（`bra_company_registry`、`bra_company_directors`、`zaf_company_registry`、`zaf_company_directors`）需要此参数。" }, "company_name": { "type": "string", "description": "注册公司名称，与登记条目进行交叉比对。对于 `zaf_company_registry` 可选。" }, "initials": { "type": "string", "description": "证件上印制的该人员姓名首字母缩写。`zaf_drivers_license` 必需；`zaf_bank_account_holder` 可接受。" }, "licence_number": { "type": "string", "description": "卡片上印制的驾照号码，适用于 `zaf_drivers_license`。省略时，使用 `document_number`。" }, "refugee_file_number": { "type": "string", "description": "南非内政部签发的难民档案号。`zaf_refugee` 所需。" }, "bank_name": { "type": "string", "description": "开户银行名称。`zaf_bank_account_holder` 必填。" }, "bank_account_number": { "type": "string", "description": "银行账号。`zaf_bank_account_holder` 必填；`zaf_fraud_prevention` 可接受。" }, "account_type": { "type": "string", "description": "`zaf_bank_account_holder` 的银行账户类型：`current`、`savings`、`transmission`、`subscriptionShare` 或 `notKnown`，不区分大小写。任何其他值返回 `400`。未知类型时请省略：账户类型交叉比对随后将报告为未确认。" }, "phone_number": { "type": "string", "description": "联系手机号码，用于交叉核验可联络性的服务（`zaf_bank_account_holder`、`zaf_fraud_prevention`、`zaf_refugee`）。" }, "right_thumb": { "type": "string", "description": "用于 `zaf_dha_fingerprint_match` 的 Base64 编码右手拇指指纹，可与 `left_thumb` 一起提供或单独提供。" }, "left_thumb": { "type": "string", "description": "用于 `zaf_dha_fingerprint_match` 的 Base64 编码左手拇指指纹，可与 `right_thumb` 一起提供或单独提供。" }, "score_level": { "type": "integer", "description": "`zaf_criminal_face_screening` 的最低生物识别评分等级。默认为 `3`。" }, "max_matches": { "type": "integer", "description": "`zaf_criminal_face_screening` 返回的候选匹配项最大数量。默认值为 `1`。" }, "vehicle_register_number": { "type": "string", "description": "车辆登记编号。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_licence_plate` 和 `vin` 一同提供。" }, "vehicle_licence_plate": { "type": "string", "description": "车辆号牌号码。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_register_number` 和 `vin` 一同提供。" }, "vin": { "type": "string", "description": "车辆识别代号（VIN 或车架号）。`zaf_vehicle_ownership` 必需此字段，且须与 `vehicle_register_number` 和 `vehicle_licence_plate` 一同提供。" }, "ssn": { "type": "string", "description": "社会安全号码（美国）。" }, "phone": { "type": "string", "description": "用于电话验证服务的电话号码。" }, "landline": { "type": "string", "description": "用于电话验证服务的座机号码。" }, "email": { "type": "string", "format": "email", "description": "用于身份验证服务的邮箱地址。" }, "country_of_residence": { "type": "string", "description": "居住国家/地区的 ISO 3166-1 alpha-2 代码。供全球身份信息增强服务（例如 `glb_identity_enrichment`）用于限定查询范围。", "example": "US" }, "partial_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "NO_ACTION", "description": "`partial_match` 对 `database_validation.status` 的影响。默认值为 `NO_ACTION`（状态保持为 `Approved`，并附带警告）。" }, "no_match_action": { "type": "string", "enum": [ "DECLINE", "NO_ACTION" ], "default": "DECLINE", "description": "`no_match` 对 `database_validation.status` 的影响。默认值为 `DECLINE`。" }, "save_api_request": { "type": "boolean", "default": true, "description": "将核验持久化为会话（控制台可见性、决策 endpoint、`status.updated` Webhook）。同时会改变 `validations` 响应的格式：为 `true`（默认）时按服务返回对象，为 `false` 时返回合并的字段映射。" }, "vendor_data": { "type": "string", "description": "您为已核验用户指定的标识符；将原样返回并与会话一起存储。" }, "metadata": { "type": "object", "nullable": true, "description": "随请求一同存储并回显的自由格式 JSON。" }, "selfie": { "type": "string", "format": "binary", "description": "用于生物识别验证服务（例如阿根廷 RENAPER `arg_renaper` 和巴拿马 SIB `pan_cedula_sib`、`pan_cedula_sib_plus`）的自拍图像（`jpg`、`jpeg`、`png`、`webp`；最大 2 MB — 图像在上传至登记处前会压缩至约 1.5 MB）。只要所选服务将其列为必填字段，即为必填项。仅支持通过 `multipart/form-data` 提供。" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/database-validation/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"issuing_state\": \"BRA\",\n \"services\": [\"bra_cpf\"],\n \"identification_number\": \"12345678900\",\n \"first_name\": \"John\",\n \"last_name\": \"Doe\",\n \"date_of_birth\": \"1980-01-01\",\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.database_validation.validate(\n issuing_state=\"BRA\",\n services=[\"bra_cpf\"],\n identification_number=\"12345678900\",\n first_name=\"John\",\n last_name=\"Doe\",\n date_of_birth=\"1980-01-01\",\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.databaseValidation.validate({\n issuing_state: \"BRA\",\n services: [\"bra_cpf\"],\n identification_number: \"12345678900\",\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1980-01-01\",\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.DatabaseValidation.Validate(ctx, didit.DatabaseValidationValidateParams{\n\tIssuingState: \"BRA\",\n\tServices: didit.Some([]string{\"bra_cpf\"}),\n\tIdentificationNumber: didit.String(\"12345678900\"),\n\tFirstName: didit.String(\"John\"),\n\tLastName: didit.String(\"Doe\"),\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.DatabaseValidationValidateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.databaseValidation().validate(DatabaseValidationValidateParams.builder()\n .issuingState(\"BRA\")\n .services(List.of(\"bra_cpf\"))\n .identificationNumber(\"12345678900\")\n .firstName(\"John\")\n .lastName(\"Doe\")\n .dateOfBirth(LocalDate.parse(\"1980-01-01\"))\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "databaseValidation->validate([\n 'issuing_state' => 'BRA',\n 'services' => ['bra_cpf'],\n 'identification_number' => '12345678900',\n 'first_name' => 'John',\n 'last_name' => 'Doe',\n 'date_of_birth' => '1980-01-01',\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.database_validation.validate(\n issuing_state: \"BRA\",\n services: [\"bra_cpf\"],\n identification_number: \"12345678900\",\n first_name: \"John\",\n last_name: \"Doe\",\n date_of_birth: \"1980-01-01\",\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.DatabaseValidation.ValidateAsync(new DatabaseValidationValidateParams\n{\n IssuingState = \"BRA\",\n Services = new string[] { \"bra_cpf\" },\n IdentificationNumber = \"12345678900\",\n FirstName = \"John\",\n LastName = \"Doe\",\n DateOfBirth = \"1980-01-01\",\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "核验已完成：至少有一个选定的服务返回了可用结果。请查看 `database_validation.match_type` 获取汇总结果，查看 `validations` 获取按服务划分的字段比对和 `outcome_code`s，以及查看 `errors`（若存在）获取失败的服务信息。", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "当 `save_api_request=true` 时持久化的会话 ID（可用于 `GET /v3/session/{sessionId}/decision/`）；否则为一个临时的关联 UUID。" }, "database_validation": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "当整体 `match_type` 触发 `DECLINE` 操作时为 `Declined`（`no_match_action` 默认为 `DECLINE`，`partial_match_action` 默认为 `NO_ACTION`）；当没有服务产生可用的比对结果时为 `In Review`，例如唯一选择的服务返回了 `REGISTRY_UNAVAILABLE` 或 `INCONCLUSIVE`；否则为 `Approved`。选择多个服务的请求可能在一个服务匹配成功时为 `Approved`，而另一个服务不可用，因此请同时检查 `errors` 以及每个服务的 `outcome_code`。" }, "issuing_state": { "type": "string", "description": "用于核验的 ISO 3166-1 alpha-3 国家/地区代码回显。", "example": "BRA" }, "validation_type": { "type": "string", "enum": [ "one_by_one", "two_by_two" ], "description": "根据结果派生：当 ≥2 个不同的服务产生完全匹配时为 `two_by_two`（匹配证件号码、同时匹配姓名 + 出生日期，或匹配地址且无冲突）；否则为 `one_by_one`。（请求中同名字段已被弃用且会被忽略。）" }, "screened_data": { "type": "object", "description": "回显发送给所选服务的输入字段（日期已标准化为 `YYYY-MM-DD`；若发送了 `selfie`，则作为预签名 URL 返回；获得同意时会添加 `consent_obtained: true`）。" }, "match_type": { "type": "string", "nullable": true, "enum": [ "full_match", "partial_match", "no_match" ], "description": "跨具有字段级比对的服务聚合的总体结果：任意 `full_match` → `full_match`；否则任意 `partial_match` → `partial_match`；否则 `no_match`。仅返回结果的服务（如生物识别犯罪筛查）可能返回 `null`；请检查 `validations` 中的每个条目以获取其 `outcome_code`。" }, "validations": { "description": "结构取决于 `save_api_request`。**`true`（默认）：** 按服务划分的对象数组（`service_id`、`service_name`、`validation`、`outcome_code`、`outcome_detail`、`source_data`）。**`false`：** 合并所有服务字段级结果的单个扁平对象（`{\"full_name\": \"full_match\", ...}`）。", "oneOf": [ { "type": "array", "items": { "type": "object", "description": "逐项服务验证结果（在 `save_api_request=true` 时返回，此为默认值）。", "properties": { "service_id": { "type": "string", "description": "生成此结果的服务的目录 ID（例如 `bra_cpf`）。", "example": "bra_cpf" }, "service_name": { "type": "string", "description": "服务在目录中便于人类阅读的名称。", "example": "Brazil - CPF status check" }, "validation": { "type": "object", "description": "您的输入与登记记录之间的逐字段比对。键为规范字段名（`full_name`、`date_of_birth`、`identification_number`、`address` 等）；值为 `full_match`、`partial_match` 或 `no_match`。", "additionalProperties": { "type": "string", "enum": [ "full_match", "partial_match", "no_match" ] } }, "outcome_code": { "type": "string", "enum": [ "MATCH", "PARTIAL_MATCH", "NO_MATCH", "DOCUMENT_NOT_FOUND", "INVALID_DOCUMENT_FORMAT", "INVALID_INPUT", "MINOR_BLOCKED", "DECEASED", "BIOMETRIC_NO_MATCH", "BIOMETRIC_IMAGE_UNUSABLE", "INCONCLUSIVE", "DOCUMENT_SUPERSEDED", "REGISTRY_UNAVAILABLE", "REGISTRY_ERROR" ], "description": "登记处查询的中立结果。`MATCH`/`PARTIAL_MATCH`/`NO_MATCH` 描述比对情况；`DOCUMENT_NOT_FOUND` 表示登记处中不存在该标识符；`INCONCLUSIVE` 表示登记处无法确认任何一种情况（转入人工审核 — 并非不匹配）；`BIOMETRIC_NO_MATCH` 表示明确的人脸不匹配，而 `BIOMETRIC_IMAGE_UNUSABLE` 表示图像技术问题（需重新拍摄自拍照）；`DECEASED`/`MINOR_BLOCKED` 为登记处策略结果；`DOCUMENT_SUPERSEDED` 表示身份匹配，但出示的证件版本与存档的不一致（已签发更新的版本）；`INVALID_DOCUMENT_FORMAT`/`INVALID_INPUT` 表示登记处本身拒绝了所发送的数据；`REGISTRY_UNAVAILABLE`/`REGISTRY_ERROR` 表示上游服务故障。" }, "outcome_detail": { "type": "string", "nullable": true, "description": "支撑结果代码的原始上游状态详情（例如 HTTP 或登记处状态码）。" }, "source_data": { "type": "object", "nullable": true, "description": "使用规范字段名称（`identification_number`、`first_name`、`last_name`、`date_of_birth`，以及登记机构专有标志）整理并标准化的登记机构记录视图。图像字段（若存在）将作为预签名 URL 返回。" } } } }, { "type": "object", "additionalProperties": { "type": "string", "enum": [ "full_match", "partial_match", "no_match" ] }, "description": "合并后的字段级结果（无状态 `save_api_request=false` 结构）。" } ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "引发该警告的功能。" }, "risk": { "type": "string", "description": "机器可读的风险标识符。" }, "additional_data": { "type": "object", "nullable": true, "description": "警告的额外上下文（若有）。" }, "log_type": { "type": "string", "description": "`warning`、`information` 或 `error`：风险如何影响结果。" }, "short_description": { "type": "string", "description": "单行人类可读的摘要。" }, "long_description": { "type": "string", "description": "完整的人类可读解释说明。" } } }, "description": "适用时为 `DATABASE_VALIDATION_NO_MATCH` 或 `DATABASE_VALIDATION_PARTIAL_MATCH`；完全匹配时为空。" }, "errors": { "type": "array", "description": "仅在部分（但非全部）所选服务失败时存在。每个条目包含 `service_id`、`code`、`message` 和 `retryable`。此处报告的服务不会出现在 `validations` 和 `services_used` 中，且不计费。该数组是其唯一出现的位置，因此即使 `status` 为 `Approved` 也应进行检查。", "items": { "type": "object", "properties": { "service_id": { "type": "string" }, "code": { "type": "string", "example": "empty_provider_response" }, "message": { "type": "string" }, "retryable": { "type": "boolean", "description": "当服务未产生响应且稍后重试可能成功时为 `true`；当数据源拒绝了发送的数据且必须先更正输入时为 `false`。", "example": true } } } }, "services_used": { "type": "array", "items": { "type": "string" }, "description": "返回了计费结果的服务的目录 ID。**仅在请求显式发送了 `services` 时提供。**" }, "match_score": { "type": "number", "description": "产生完全匹配（在证件号码上、姓名与出生日期组合上，或在没有矛盾的地址上）的尝试服务比例（0.0–1.0）。**仅在请求显式发送了 `services` 时存在。**" } } }, "vendor_data": { "type": "string", "nullable": true, "description": "回显您发送的 `vendor_data`。" }, "metadata": { "type": "object", "nullable": true, "description": "您发送的 `metadata` 回显。" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Full match (Approved)": { "summary": "默认 save_api_request=true — 各服务的 `validations` 对象", "value": { "request_id": "7f9a1c0e-1f2b-4f6e-9d3a-2b1c0e7f9a1c", "database_validation": { "status": "Approved", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "full_match", "validations": [ { "validation": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "outcome_code": "MATCH", "outcome_detail": "200", "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "source_data": { "identification_number": "12345678900", "first_name": "JOHN", "last_name": "DOE", "date_of_birth": "1980-01-01", "lgpd_minor": false, "minor_under_16": false, "minor_under_18": false } } ], "warnings": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-11T10:30:00.000000+00:00" } }, "Explicit services (extended shape)": { "summary": "发送包含 `services` 的请求 — 响应会添加 `services_used` 和 `match_score`", "value": { "request_id": "b3e7c1a2-9d4f-4f0b-8a6c-5e2d1f0a9b3e", "database_validation": { "status": "Approved", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "full_match", "validations": [ { "validation": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "outcome_code": "MATCH", "outcome_detail": "200", "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "source_data": { "identification_number": "12345678900", "first_name": "JOHN", "last_name": "DOE", "date_of_birth": "1980-01-01", "lgpd_minor": false, "minor_under_16": false, "minor_under_18": false } } ], "warnings": [], "services_used": [ "bra_cpf" ], "match_score": 1.0 }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-11T10:30:00.000000+00:00" } }, "No match (Declined)": { "summary": "公司登记记录不匹配 — 默认 `no_match_action=DECLINE`", "value": { "request_id": "0a1b2c3d-4e5f-6789-abcd-ef0123456789", "database_validation": { "status": "Declined", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "no_match", "validations": [ { "validation": { "full_name": "no_match", "date_of_birth": "no_match", "identification_number": "no_match" }, "outcome_code": "NO_MATCH", "outcome_detail": "200", "service_id": "bra_cpf", "service_name": "Brazil - CPF status check", "source_data": { "identification_number": "00987654321", "first_name": "TOTALLY", "last_name": "DIFFERENT NAME", "date_of_birth": "1999-01-01", "lgpd_minor": false, "minor_under_16": false, "minor_under_18": false } } ], "warnings": [ { "feature": "DATABASE_VALIDATION", "risk": "DATABASE_VALIDATION_NO_MATCH", "additional_data": null, "log_type": "error", "short_description": "Database validation no match", "long_description": "The system identified a no match in the database validation, requiring further investigation." } ] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-11T10:31:00.000000+00:00" } }, "Stateless (save_api_request=false)": { "summary": "`validations` 会折叠为合并的字段映射；不存储任何内容", "value": { "request_id": "c4d5e6f7-8901-2345-6789-abcdef012345", "database_validation": { "status": "Approved", "issuing_state": "BRA", "validation_type": "one_by_one", "screened_data": { "tax_number": "12345678900", "first_name": "John", "last_name": "Doe", "date_of_birth": "1980-01-01" }, "match_type": "full_match", "validations": { "full_name": "full_match", "date_of_birth": "full_match", "identification_number": "full_match" }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-11T10:32:00.000000+00:00" } } } } } }, "400": { "description": "验证错误 - 未产生任何计费。预检字段错误会在执行任何外部调用之前发生。如果所有未响应的尝试均明确拒绝了该输入，则响应将包含 `code: provider_rejected_input` 且 `retryable: false` 的 `validation_errors`；重试前请更正输入。字段级问题使用 DRF 的标准包装格式；目录问题返回 `services` 数组（相关时还会附加 `requires_onboarding` 或 `services_requiring_consent`）；缺少字段的错误包含 `fields_required_by`，用于将每个缺失字段映射到需要它的服务；需要至少一个额外标识符的服务（例如 `usa_states_credit_bureau`，该服务无法仅凭姓名进行验证）将返回 `any_field_required_by`，用于将各服务映射到必须至少提供其中之一的字段；按服务检查的格式问题返回 `invalid_fields_by_service`。", "content": { "application/json": { "examples": { "Invalid issuing_state": { "summary": "不支持的国家/地区 — 消息列出所有有效的 alpha-3 代码", "value": { "error": [ "Invalid issuing state. Valid options are: ARE, ARG, AUS, AUT, BEL, BGD, BOL, BRA, CAN, CHE, CHL, CHN, CIV, COL, CRI, CZE, DEU, DNK, DOM, ECU, ESP, FIN, FRA, GBR, GHA, GLB, GRC, GTM, HKG, HND, IDN, IND, IRL, ITA, KEN, KHM, MAR, MEX, MYS, NGA, NLD, NOR, NZL, OMN, PAN, PER, PHL, POL, PRT, PRY, QAT, SGP, SLV, SVK, SWE, THA, UGA, URY, USA, VEN, ZAF, ZMB, ZWE" ] } }, "Missing required fields": { "summary": "所选服务中必需字段的并集，带有通用字段提示", "value": { "error": [ "Missing required fields: tax_number (or use 'identification_number' which maps to 'tax_number' for BRA)" ], "fields_required_by": { "tax_number": [ "bra_cpf" ] } } }, "Unknown service id": { "summary": "`services` 包含目录中不存在的 id", "value": { "services": [ "Unknown service_id(s): ['bogus_service']" ] } }, "Service not live for country": { "summary": "`services` 指定了来自其他国家/地区的服务（或存根条目）", "value": { "services": [ "Services not currently live for PER: ['bra_cpf']. Available services: ['per_dni', 'per_residential', 'per_tax_registration']" ] } }, "Service requires onboarding": { "summary": "服务存在，但尚未为您的组织激活", "value": { "services": [ "Services require onboarding before they can be enabled for AUS: ['aus_australia_driver_licence']. Contact Didit support to activate them." ], "requires_onboarding": [ "aus_australia_driver_licence" ] } }, "Consent missing": { "summary": "所选服务被标记为 requires_consent=true 且 `consent` 不为 `true`", "value": { "consent": [ "Explicit end-user consent is required for these database validation services: ['chn_national_id']. Send `consent=true`." ], "services_requiring_consent": [ "chn_national_id" ] } }, "Country format rule violation": { "summary": "标识符不符合该国家/地区的格式规则（长度/数字/正则表达式）", "value": { "tax_number": [ "Invalid tax number for BRA: Brazilian CPF (exactly 11 digits). Must be exactly 11 characters long (got 10)." ] } }, "Service-specific format violation": { "summary": "字段不符合所选服务自身的格式要求", "value": { "error": [ "One or more fields do not match the format required by the selected service." ], "invalid_fields_by_service": { "chn_national_id": [ "national_id_format" ] } } }, "Input refused by every attempt": { "summary": "重试前请更正输入", "value": { "error": "The source refused to run this query with the supplied input.", "validation_errors": [ { "service_id": "bra_cpf", "code": "provider_rejected_input", "message": "The source refused to run this query with the supplied input.", "retryable": false } ] } } }, "schema": { "type": "object", "additionalProperties": true, "properties": { "error": { "description": "请求级说明或预检字段错误。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "validation_errors": { "type": "array", "description": "在所有未应答的尝试都在预检后拒绝了输入时存在。", "items": { "type": "object", "properties": { "service_id": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean", "description": "稍后重试是否能够解决此服务故障。为 False 时表示须先修正所提供的输入。" } } } } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何筛查或服务商调用之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "502": { "description": "所选服务均未返回可用结果。在重试之前请检查每个 validation_errors 条目；仅凭 HTTP 502 无法确定是否为暂时性故障。带有 retryable: true 的 empty_provider_response 表示结果不可用或原因不明，包括主要服务被拒绝且随后的回退服务不可用。相比之下，传统的 provider_invalid_input 和 provider_validation_error 条目需要更正输入，并且可能会省略 retryable。此操作不计费。当 save_api_request=true 时，失败的尝试将被记录为状态为 Not Finished 的会话。部分失败将返回 200 及 database_validation.errors。", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "validation_errors": { "type": "array", "items": { "type": "object", "properties": { "service_id": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "retryable": { "type": "boolean", "description": "稍后重试是否能够解决此服务故障。为 False 时表示须先修正所提供的输入。" } } } } } }, "examples": { "Provider returned no result": { "summary": "所有选定的服务均失败", "value": { "error": "Database validation could not be performed. The external validation service did not return a result. Please try again later.", "validation_errors": [ { "service_id": "bra_cpf", "code": "empty_provider_response", "message": "The provider did not return a database validation result.", "retryable": true } ] } } } } } } } } }, "/v3/phone/send/": { "post": { "summary": "发送手机验证码", "description": "通过 WhatsApp、SMS 或其他受支持的渠道向电话号码发送一次性验证码 (OTP)，然后使用 [`POST /v3/phone/check/`](/zh/standalone-apis/phone-check) 进行核验。\n\n**发送与核验的配对方式。** 验证状态以您的应用加上 E.164 格式的 `phone_number` 为键，核验调用不需要传入 `request_id`。每次新的发送都会创建一个待处理的验证，有效期为 **5 分钟**：在窗口关闭前，使用相同的号码和用户收到的验证码调用核验。在验证处于待处理状态时对同一号码再次调用发送，会为该次验证重新发送验证码（`status: \"Retry\"`，相同的 `request_id`）。以此方式最多可关联一次重试（总共两次发送）；进一步发送将使用新的 `request_id` 启动一次全新验证。5 分钟窗口从首次发送开始计算，重试不会延长该时间。\n\n**投递渠道。** `options.preferred_channel` 用于选择渠道（默认为 `whatsapp`；还支持 `sms`、`telegram`、`voice`、`rcs`、`viber` 和 `zalo`）。当首选渠道对目标国家/地区或号码不可用时，投递将自动回退到 SMS，发送仍会报告 `Success`，实际使用的渠道会在核验响应（`phone.verification_method` 和 `lifecycle` 事件）中报告。\n\n**品牌定制。** SMS 验证码带有在 Business Console 中设置的应用 SMS 发送方名称，无需额外费用。传入 `options.sms_sender_name` 可使用其他名称发送一条验证码，或传入 `options.use_white_label_customization: true` 在未设置发送方名称时回退到您的白标公开名称。WhatsApp 验证码使用固定消息；在 Business Console 中连接您自己的 WhatsApp Business 号码即可使用您的企业名称和号码作为发送方，仅按 Didit 费用计费。\n\n**发送状态。** `Success`：已为新验证发送 OTP；`Retry`：已为待处理验证重新发送 OTP；`Blocked`：反欺诈层拒绝发送（参见 `reason`，例如 `repeated_attempts`、`suspicious`、`spam`）。`Blocked` 发送会立即将验证终结为 `Declined` 并带有高风险警告，因此后续核验将返回 `Expired or Not Found`。\n\n**计费。** 价格取决于目标国家/地区和实际投递消息的渠道，参见[电话验证定价](/zh/getting-started/phone-verification-pricing)。只有 `Blocked` 发送保证免费：任何其他未计费的发送尝试均在验证终结或过期时收取费用，即使投递从未得到确认或投递提供商报告消息无法送达也是如此。核验始终免费。作为防滥用措施，电话验证在您的组织完成首次充值之前处于禁用状态（`403`）。\n\n**会话持久化。** 每次新验证都会作为 API 类型的会话进行持久化：`request_id` 是一个真实的会话 ID，您可以将其传递给 `GET /v3/session/{sessionId}/decision/`，验证会显示在 Business Console 中，并且随着验证的推进会触发 `status.updated` Webhook。\n\n**沙盒。** 沙盒 API 密钥会跳过投递和计费：在请求验证之后（格式错误的输入仍返回 `400`），endpoint 会返回带有随机 `request_id` 的静态 `Success` payload；不会发送任何消息，也不会持久化任何内容。在沙盒核验中使用验证码 `123456`。\n\n**身份验证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。缺少凭据或凭据无效将返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`），此 API 从不返回 `401`。\n\n**速率限制。** 所有 POST/PATCH/DELETE endpoint 共享每个 API 密钥 300 次请求/分钟的写入预算，外加每个电话号码每小时 4 次发送尝试的防滥用上限；超过任一限制均返回 `429`。", "operationId": "post_v3phone_send", "x-didit-sdk": { "resource": "phone", "method": "send_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/phone/send/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"+14155552671\",\n \"options\": {\n \"code_size\": 6,\n \"preferred_channel\": \"whatsapp\",\n \"locale\": \"en-US\"\n },\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.phone.send_code(\n phone_number=\"+14155552671\",\n options={\n \"locale\": \"en-US\",\n \"preferred_channel\": \"whatsapp\",\n },\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.phone.sendCode({\n phone_number: \"+14155552671\",\n options: {\n locale: \"en-US\",\n preferred_channel: \"whatsapp\",\n },\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.SendCode(ctx, didit.PhoneSendCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tOptions: didit.Some(didit.PhoneSendCodeParamsOptions{\n\t\tLocale: didit.String(\"en-US\"),\n\t\tPreferredChannel: didit.Some(didit.PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.PhoneSendCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.phone().sendCode(PhoneSendCodeParams.builder()\n .phoneNumber(\"+14155552671\")\n .options(PhoneSendCodeParams.Options.builder()\n .locale(\"en-US\")\n .preferredChannel(PhoneSendCodeParams.Options.PreferredChannel.of(\"whatsapp\"))\n .build())\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "phone->sendCode([\n 'phone_number' => '+14155552671',\n 'options' => [\n 'locale' => 'en-US',\n 'preferred_channel' => 'whatsapp',\n ],\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.phone.send_code(\n phone_number: \"+14155552671\",\n options: {\n locale: \"en-US\",\n preferred_channel: \"whatsapp\",\n },\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Phone.SendCodeAsync(new PhoneSendCodeParams\n{\n PhoneNumber = \"+14155552671\",\n Options = new PhoneSendCodeParamsOptions\n {\n Locale = \"en-US\",\n PreferredChannel = new PhoneSendCodeParamsOptionsPreferredChannel(\"whatsapp\"),\n },\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "maxLength": 20, "description": "E.164 格式的收件人电话号码，以前导 `+` 和国家/地区代码开头（例如 `+14155552671`）。号码会经过验证并标准化为 E.164；无法解析或无效的号码将返回 `400` 并附带 `phone_number` 字段错误。", "example": "+14155552671" }, "options": { "type": "object", "description": "一次性验证码投递选项。所有字段均为可选。", "properties": { "code_size": { "type": "integer", "minimum": 4, "maximum": 8, "default": 6, "description": "OTP 中的数字位数。" }, "locale": { "type": "string", "maxLength": 5, "pattern": "^[a-z]{2,3}(-[A-Z]{2,3})?$", "description": "用于本地化验证消息的 BCP-47 区域设置（例如 `en-US`、`fr`、`es`）。无效格式返回 `400`。", "example": "en-US" }, "preferred_channel": { "type": "string", "enum": [ "whatsapp", "sms", "telegram", "voice", "rcs", "viber", "zalo" ], "default": "whatsapp", "description": "首选投递渠道。如果该渠道对目标国家/地区或号码不可用，消息将自动回退为 SMS，发送仍会报告 `Success`。" }, "use_white_label_customization": { "type": "boolean", "default": false, "description": "为 `true` 时，发送将采用白标：如果您应用没有设置短信发送方名称，短信将改为显示您的白标公开名称（\"123456 是您在 Acme Bank 的验证码\"）。如果设置了短信发送方名称，无论是否设置此标志都会使用该名称。适用于短信消息，包括从其他渠道回退的短信；WhatsApp 验证码使用固定消息发送，不带品牌标识。默认为 `false`。" }, "sms_sender_name": { "type": "string", "nullable": true, "maxLength": 30, "example": "Acme Bank", "description": "该验证码短信所携带的名称（\"123456 是您用于 Acme Bank 的验证码\"），用以代替您应用的短信发送方名称。免费。长度为 1 到 30 个字符：仅限字母、数字、空格以及 ' & - !，不能全为数字，单词之间使用单个空格；任何其他值都将返回 `400` 且不会发送验证码。如果省略、为 `null` 或留空，则使用您应用的短信发送方名称。每个应用每天（UTC）最多可以开始使用两个新名称；超过后，验证码将使用您应用的名称发送。适用于短信消息，包括从其他渠道回退的短信；WhatsApp 验证码不带有品牌标识。", "pattern": "^$|^(?![\\d ]+$)[\\p{L}\\p{N}'&!-]+( [\\p{L}\\p{N}'&!-]+)*$" } } }, "signals": { "type": "object", "description": "关于终端用户的可选设备与网络信号，转发至反欺诈层以提升对滥用或自动化流量的检测能力。所有字段均为可选。", "properties": { "ip": { "type": "string", "description": "终端用户设备的 IP 地址。IPv4 或 IPv6。", "example": "192.0.2.1" }, "device_id": { "type": "string", "maxLength": 255, "description": "终端用户设备的唯一标识符。Android：`ANDROID_ID`；iOS：`identifierForVendor`。", "example": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2" }, "device_platform": { "type": "string", "enum": [ "android", "ios", "ipados", "tvos", "web" ], "description": "终端用户设备的平台。" }, "device_model": { "type": "string", "maxLength": 255, "description": "终端用户设备的型号。", "example": "iPhone17,2" }, "os_version": { "type": "string", "maxLength": 64, "description": "终端用户设备的操作系统版本。", "example": "18.0.1" }, "app_version": { "type": "string", "maxLength": 64, "description": "您的应用版本。", "example": "1.2.34" }, "user_agent": { "type": "string", "maxLength": 512, "description": "终端用户浏览器或应用的 User-Agent。", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1" } } }, "vendor_data": { "type": "string", "description": "由调用方控制的可选标识符（您的内部用户 id、邮箱、UUID 等），在会话中持久化并在发送响应、匹配检查响应、Webhook 和 Business Console 中原样返回。可使用它将 Didit 的 `request_id` 与您的用户记录进行关联。" }, "metadata": { "type": "object", "nullable": true, "description": "可选的自由格式 JSON 对象，持久化保存在会话中，并在发送响应、匹配检查响应、Webhook 以及 Business Console 中回显。" } }, "required": [ "phone_number" ] }, "examples": { "WhatsApp (default)": { "summary": "通过 WhatsApp 发送的 6 位数 OTP，可自动回退到短信", "value": { "phone_number": "+14155552671", "options": { "preferred_channel": "whatsapp", "locale": "en-US" }, "vendor_data": "user-1234" } }, "SMS with custom code length": { "summary": "强制通过短信投递 4 位验证码", "value": { "phone_number": "+34699999999", "options": { "preferred_channel": "sms", "code_size": 4, "locale": "es" } } }, "With fraud signals": { "summary": "转发设备信号以增强反欺诈筛查", "value": { "phone_number": "+14155552671", "signals": { "ip": "192.0.2.1", "device_id": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2", "device_platform": "ios", "device_model": "iPhone17,2", "os_version": "18.0.1", "app_version": "1.2.34" }, "vendor_data": "user-1234" } } } } } }, "responses": { "200": { "description": "已确认发送。请检查 `status`：`Success` 和 `Retry` 表示验证码正在发送中；`Blocked` 表示反欺诈层已拒绝，且验证已最终确定为 `Declined`。`request_id` 是持久化的会话 ID（在 `Retry` 时 ID 相同）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerificationSendResponse" }, "examples": { "Success": { "summary": "已为新验证发送一次性验证码", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Success", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Retry": { "summary": "在 5 分钟窗口内向同一号码进行第二次发送：相同的 request_id", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Retry", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Blocked": { "summary": "反欺诈拒绝 — 验证最终判定为已拒绝，不计费", "value": { "request_id": "0d8af1f4-0c43-46d7-b75c-6e4e22c0a7b3", "status": "Blocked", "reason": "repeated_attempts", "vendor_data": "user-1234", "metadata": null } } } } } }, "400": { "description": "验证错误。格式错误的输入会返回 DRF 的字段错误响应格式（每个有问题的字段对应一个消息数组，选项错误则嵌套在 `options` 下）。如果号码解析成功但在发送时被拒绝（无法接通，或属于不可用的线路类型，如特服短码），则会返回 `{\"detail\": ...}` 响应格式。", "content": { "application/json": { "examples": { "Invalid phone number (field error)": { "summary": "号码不是有效的 E.164 格式", "value": { "phone_number": [ "Invalid phone number provided." ] } }, "Missing phone number": { "summary": "请求体中未包含 `phone_number`", "value": { "phone_number": [ "This field is required." ] } }, "Invalid options": { "summary": "`code_size` 超出范围、`locale` 格式错误、`preferred_channel` 未知", "value": { "options": { "code_size": [ "Ensure this value is less than or equal to 8." ], "locale": [ "Ensure this field has no more than 5 characters." ], "preferred_channel": [ "\"carrier_pigeon\" is not a valid choice." ] } } }, "Number rejected at send time": { "summary": "符合 E.164 格式，但该号码无法接收 OTP", "value": { "detail": "Invalid phone number provided." } }, "Ineligible line type": { "summary": "线路类型无法接收一次性验证码（例如短代码）", "value": { "detail": "Invalid phone line type provided." } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头时返回（`{\"detail\": ...}`）；错误、已撤销或已过期的密钥返回 `401`。当组织从未充值（防滥用控制）或其余额无法覆盖目标目的地的发送价格时，也会在任何发送之前返回（`{\"error\": ...}`）。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Top-up required": { "summary": "电话验证将保持禁用状态，直到组织完成首次充值", "value": { "detail": "To protect against abuse, phone verification is disabled until your first top-up." } }, "Not enough credits": { "summary": "组织余额不足以支付发送价格", "value": { "error": "You don't have enough credits to perform this request." } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。此外，上游对每个电话号码每小时设置了 4 次验证尝试的防滥用上限。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。注意：`X-RateLimit-*`/`Retry-After` 响应头仅伴随 300 次/分钟写入限制的 429 响应；针对每个号码上限的 429 响应不包含速率限制响应头。", "content": { "application/json": { "examples": { "Per-number cap": { "summary": "过去一小时内同一号码的验证尝试超过 4 次", "value": { "detail": "Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number." } }, "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "502": { "description": "电话验证服务商暂时不可用：在内置重试后仍出现 5xx 响应、超时或连接失败。可以安全重试；不收取任何费用，也不会消耗尝试次数。", "content": { "application/json": { "examples": { "Provider outage": { "summary": "服务商未响应发送请求", "value": { "detail": "Phone verification is temporarily unavailable. Please try again shortly.", "code": "phone_provider_unavailable" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "创建验证时发生意外故障，且并非已知的提供商服务中断。可安全重试。", "content": { "application/json": { "examples": { "Provider error": { "summary": "无法发起一次性验证码投递", "value": { "detail": "Error creating phone verification" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/phone/check/": { "post": { "summary": "核验电话验证码", "description": "验证由 [`POST /v3/phone/send/`](/zh/standalone-apis/phone-send) 发送的 OTP，并获取最终验证结果以及电话情报：运营商名称和线路类型、虚拟（VoIP）和一次性标记，以及该号码在您所有会话中的重复使用情况。\n\n**核验如何匹配验证记录。** 匹配依据是您的应用以及 E.164 格式的 `phone_number`，`request_id` 并非输入参数。系统将检查在过去 **5 分钟**内创建的最新的待处理验证。如果不存在（从未发送、已完成或超过 5 分钟），endpoint 将返回 `200` 以及 `status: \"Expired or Not Found\"`。\n\n**尝试次数配额。** 每次验证允许 **3 次验证码尝试**。前两次输入错误验证码将返回 `status: \"Failed\"`，附带剩余尝试次数且 `phone: null`；第三次输入错误验证码会将验证最终判定为 `Declined`，附带 `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` 警告，并返回完整的电话报告。\n\n**结果。** `Approved`：验证码正确且无拒绝风险。`Declined`：终态，验证码正确但匹配到了拒绝风险（下方的 `DECLINE` 操作、黑名单或高风险号码），或者尝试次数耗尽。`Failed`：验证码错误，尚有剩余尝试次数。`Expired or Not Found`：无待核验项。在 `Approved`/`Declined` 状态下，`request_id` 等同于发送时的 `request_id`（即会话 ID），且 `phone` 包含完整报告（`carrier`、`is_virtual`、`is_disposable`、`warnings`、`lifecycle`、`matches`）；在 `Failed` 和 `Expired or Not Found` 状态下，`request_id` 是一个一次性的随机 UUID。\n\n**风险操作。** `duplicated_phone_number_action`、`disposable_number_action` 和 `voip_number_action` 决定在验证码正确但检测到相应风险时的处理方式：`DECLINE` 会将最终状态更改为 `Declined`；`NO_ACTION`（默认）将风险记录在 `phone.warnings` 中，不影响状态。\n\n**计费。** 核验是免费的，投递费用在发送端收取（参见[电话验证定价](/zh/getting-started/phone-verification-pricing)）。\n\n**会话持久化。** 完成核验后，会更新发送步骤创建的会话（可在 Business Console 中查看，可通过 `GET /v3/session/{sessionId}/decision/` 查询），并触发一个 `status.updated` Webhook。\n\n**沙盒。** 沙盒 API 密钥会跳过所有处理：任何格式合规的验证码（4 到 8 位数字，包括 `123456`）都会返回一个静态的 `Approved` payload，其中包含简化的扁平 `phone` 对象（`status`、`phone_number`、`country_code`、`carrier_name`、`line_type`、`flags`）；格式错误的输入仍返回 `400`。不会持久化任何内容。\n\n**身份验证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。凭证缺失或无效将返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`），此 API 从不返回 `401`。\n\n**速率限制。** 每个 API 密钥共享每分钟 300 次请求的写入配额，外加上游防滥用的每个号码每小时 4 次尝试上限；超出任一限制均会返回 `429`。\n\n**社交足迹。** 将 `enable_social` 设置为 `true` 可添加 `phone_social` 块：该号码注册的在线平台，包含按类别统计的数量以及所有可用的个人资料详情。`profiles_registered: 0` 表示已对各平台进行了检查，且未在任何平台上找到该号码，这是一个有效且计费的响应结果。当未请求该附加功能或核验无法完成时，该块不会出现，且在这种情况下不收取费用。计费时，在此 endpoint 自身价格的基础上，每次请求额外增加一个 `phone_social` 计费单元。", "operationId": "post_v3phone_check", "x-didit-sdk": { "resource": "phone", "method": "check_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/phone/check/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"phone_number\": \"+14155552671\",\n \"code\": \"123456\",\n \"voip_number_action\": \"DECLINE\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.phone.check_code(\n phone_number=\"+14155552671\",\n code=\"123456\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.phone.checkCode({\n phone_number: \"+14155552671\",\n code: \"123456\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Phone.CheckCode(ctx, didit.PhoneCheckCodeParams{\n\tPhoneNumber: \"+14155552671\",\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.PhoneCheckCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.phone().checkCode(PhoneCheckCodeParams.builder()\n .phoneNumber(\"+14155552671\")\n .code(\"123456\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "phone->checkCode([\n 'phone_number' => '+14155552671',\n 'code' => '123456',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.phone.check_code(\n phone_number: \"+14155552671\",\n code: \"123456\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Phone.CheckCodeAsync(new PhoneCheckCodeParams\n{\n PhoneNumber = \"+14155552671\",\n Code = \"123456\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone_number": { "type": "string", "maxLength": 20, "description": "与匹配的 [`POST /v3/phone/send/`](/zh/standalone-apis/phone-send) 调用中使用的相同电话号码，采用 E.164 格式。这是将核验与发送关联起来的依据。", "example": "+14155552671" }, "code": { "type": "string", "minLength": 4, "maxLength": 8, "pattern": "^[0-9]{4,8}$", "description": "终端用户收到的 OTP。必须为 4–8 位数字，其他任何格式都会返回 `400` 且不消耗尝试次数。格式正确但内容错误的验证码会返回 `200` 并附带 `status: \"Failed\"`，同时消耗 3 次尝试机会中的一次。", "example": "123456" }, "duplicated_phone_number_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当您应用的另一位用户（不同的 `vendor_data`）已经使用过相同号码时采取的操作。`DECLINE` 会将最终的 `status` 变为 `Declined`；`NO_ACTION` 会在 `phone.warnings` 中记录该风险并填充 `phone.matches`。" }, "disposable_number_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当运营商查询将该号码标记为临时/一次性线路（`phone.is_disposable`）时的处理操作。`DECLINE` 会将最终 `status` 变为 `Declined`；`NO_ACTION` 会在 `phone.warnings` 中记录该风险。" }, "voip_number_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当运营商查询报告虚拟线路类型（`voip`、`isp` 或 `vpn`，`phone.is_virtual`）时的处理操作。`DECLINE` 会将最终 `status` 变为 `Declined`；`NO_ACTION` 会在 `phone.warnings` 中记录该风险。" }, "enable_enrichment": { "type": "boolean", "default": false, "description": "为 `true` 时，还会对该号码运行电话情报分析：风险评分、线路类型、近期是否携号转网以及信任指数。除此 endpoint 本身的价格外，每次请求按单次 `phone_intelligence_api` 计费（标价为 $0.05）。当您的余额不足以支付时，请求将返回 `403`。", "example": false }, "phone_intelligence_score_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "电话情报风险评分高于阈值时的操作。`DECLINE` 会将最终 `status` 翻转为 `Declined`；`NO_ACTION` 会记录该信号而不拒绝。仅在 `enable_enrichment` 为 `true` 时生效。" }, "phone_type_risk_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "号码属于高风险线路类型时的操作。`DECLINE` 会将最终 `status` 翻转为 `Declined`；`NO_ACTION` 会记录该信号而不拒绝。仅在 `enable_enrichment` 为 `true` 时生效。" }, "recent_port_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "号码最近携号转网至另一运营商时的操作。`DECLINE` 会将最终 `status` 翻转为 `Declined`；`NO_ACTION` 会记录该信号而不拒绝。仅在 `enable_enrichment` 为 `true` 时生效。" }, "low_phone_trust_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "电话情报信任指数处于或低于阈值时的操作。`DECLINE` 会将最终 `status` 翻转为 `Declined`；`NO_ACTION` 会记录该信号而不拒绝。仅在 `enable_enrichment` 为 `true` 时生效。" }, "enable_social": { "type": "boolean", "default": false, "description": "为 true 时，还会查找该号码的社交足迹，即其注册所在的消息、社交、电子商务和职业平台。除此 endpoint 本身的价格外，每次请求按一个 `phone_social` 计费。", "example": true }, "phone_no_social_presence_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "社交足迹核查发现该号码在其覆盖的所有平台上均未注册时的操作。此 endpoint 仅接受 NO_ACTION 和 DECLINE；同名工作流配置键上提供 REVIEW。" } }, "required": [ "phone_number", "code" ] }, "examples": { "Default": { "summary": "记录任何风险但绝不自动拒绝", "value": { "phone_number": "+14155552671", "code": "123456" } }, "Strict risk policy": { "summary": "自动拒绝网络电话（VoIP）和一次性线路", "value": { "phone_number": "+14155552671", "code": "123456", "voip_number_action": "DECLINE", "disposable_number_action": "DECLINE" } } } } } }, "responses": { "200": { "description": "核验已完成：错误的验证码和缺失的验证也会返回 `200`；请检查 `status`，而非 HTTP 状态码。`phone` 仅在最终结果（`Approved`/`Declined`）中填充，在 `Failed` 时为 `null`，在 `Expired or Not Found` 时不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PhoneVerificationCheckResponse" }, "examples": { "Approved": { "summary": "验证码正确：包含运营商、生命周期及匹配项的完整电话报告", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Approved", "message": "The verification code is correct.", "phone": { "status": "Approved", "phone_number_prefix": "+1", "phone_number": "4155552671", "full_number": "+14155552671", "country_code": "US", "country_name": "United States", "carrier": { "name": "AT&T", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.0509 }, { "type": "PHONE_DELIVERY_DELIVERED", "timestamp": "2026-06-12T01:23:43.118220+00:00", "details": { "channel": "whatsapp", "status": "delivered" }, "fee": 0 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Failed (attempts remaining)": { "summary": "验证码错误，用户可以重试；此处的 request_id 为一次性 UUID", "value": { "request_id": "11111111-2222-3333-4444-555555555555", "status": "Failed", "message": "The verification code is incorrect. Attempts remaining: 2", "phone": null, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:21.512340+00:00" } }, "Declined (max attempts)": { "summary": "第三次输入错误验证码 — 验证最终判定为已拒绝", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Declined", "message": "The verification code is incorrect. Maximum attempts reached.", "phone": { "status": "Declined", "phone_number_prefix": "+1", "phone_number": "4155552671", "full_number": "+14155552671", "country_code": "US", "country_name": "United States", "carrier": { "name": "AT&T", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": null, "warnings": [ { "feature": "PHONE", "risk": "VERIFICATION_CODE_ATTEMPTS_EXCEEDED", "additional_data": null, "log_type": "error", "short_description": "Verification code attempts exceeded", "long_description": "The system detected that the phone number has exceeded the maximum number of verification code attempts." } ], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.0509 }, { "type": "INVALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:01.118220+00:00", "details": { "code_tried": "111111", "status": "Failed" }, "fee": 0 }, { "type": "INVALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:21.512340+00:00", "details": { "code_tried": "222222", "status": "Failed" }, "fee": 0 }, { "type": "INVALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "333333", "status": "Failed" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_DECLINED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": { "reason": "VERIFICATION_CODE_ATTEMPTS_EXCEEDED" }, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Declined (risk policy)": { "summary": "验证码正确，但线路为 VoIP 且 voip_number_action=DECLINE", "value": { "request_id": "7f1c9d2e-44a1-4b6e-9a3e-5b8e6f1c2d3a", "status": "Declined", "message": "The verification code is correct.", "phone": { "status": "Declined", "phone_number_prefix": "+1", "phone_number": "5005550006", "full_number": "+15005550006", "country_code": "US", "country_name": "United States", "carrier": { "name": "CLEC LLC", "type": "voip" }, "is_disposable": false, "is_virtual": true, "verification_method": "sms", "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [ { "feature": "PHONE", "risk": "VOIP_NUMBER_DETECTED", "additional_data": null, "log_type": "error", "short_description": "VoIP number detected", "long_description": "The system detected that the phone number is a VoIP number, which is not allowed." } ], "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "sms" }, "fee": 0.0509 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_DECLINED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": { "reason": "VOIP_NUMBER_DETECTED" }, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Expired or Not Found": { "summary": "最近 5 分钟内没有针对该号码的待处理验证", "value": { "request_id": "69cc35c6-280a-47a6-ab8c-4f32abc02ed0", "status": "Expired or Not Found", "message": "No pending phone verification found in the last 5 minutes.", "vendor_data": null, "metadata": null, "created_at": "2026-06-12T01:24:47.311323+00:00" } } } } } }, "400": { "description": "验证错误 — DRF 的字段错误包装格式：每个违规字段对应一个消息数组。", "content": { "application/json": { "examples": { "Invalid code format": { "summary": "`code` 不是 4–8 位纯数字", "value": { "code": [ "Invalid code format. Enter 4 to 8 numeric digits." ] } }, "Invalid phone number": { "summary": "`phone_number` 不是有效的 E.164 格式", "value": { "phone_number": [ "Invalid phone number provided." ] } }, "Invalid action": { "summary": "风险操作仅接受 NO_ACTION 或 DECLINE", "value": { "voip_number_action": [ "\"REVIEW\" is not a valid choice." ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头时返回；错误、已撤销或已过期的密钥返回 `401`。核验是免费的，因此此处不进行额度检查。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。此外，上游对每个电话号码每小时设置了 4 次验证尝试的防滥用上限。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。注意：`X-RateLimit-*`/`Retry-After` 响应头仅伴随 300 次/分钟写入限制的 429 响应；针对每个号码上限的 429 响应不包含速率限制响应头。", "content": { "application/json": { "examples": { "Per-number cap": { "summary": "过去一小时内同一号码的验证尝试超过 4 次", "value": { "detail": "Maximum verification attempts reached for this phone number. Only 4 authentication attempts are allowed per hour. Try again later or use a different number." } }, "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "502": { "description": "电话验证服务商暂时不可用：在内置重试后仍出现 5xx 响应、超时或连接失败。可以安全重试；不会消耗尝试额度。", "content": { "application/json": { "examples": { "Provider outage": { "summary": "服务商未响应检查请求", "value": { "detail": "Phone verification is temporarily unavailable. Please try again shortly.", "code": "phone_provider_unavailable" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } } } } }, "500": { "description": "向上游核验验证码时发生意外故障，且并非已知的提供商服务中断。可安全重试；尝试次数额度仅由已完成的检查消耗。", "content": { "application/json": { "examples": { "Provider error": { "summary": "验证码验证无法完成", "value": { "detail": "Error checking phone verification" } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/bank/account-check/": { "post": { "summary": "核验银行账户", "description": "在向银行账户汇款之前，核验该账户是否属于您指定的个人或企业。无需会话也无需登录：发送名称和账户，读取结果。这是银行验证步骤中的[账户核验](/zh/core-technology/bank-verification/account-check)，从您的后端运行。\n\n**您发送的内容。** 账户的 `country`（ISO 3166-1 alpha-3）、按该国家/地区书写方式填写的 `account`，以及 `holder` 名称：个人填写 `full_name`，企业填写 `business_name`。企业名称用于核验企业账户。\n\n**您收到的结果。** `result` 为 `match`、`close_match`、`no_match` 或 `cannot_verify`。在 `close_match` 时，如果银行返回了开户人名称，`holder_name` 即为银行记录中的账户所属名称。返回的 `account` 会脱敏仅显示后 4 位字符。\n\n**计费。** 无论结果如何，银行回复的每次核验均按该账户所在国家/地区的账户核验价格计费一次：`no_match`、账户不存在以及 `cannot_verify` 同样计费。返回错误响应的请求绝不计费。\n\n**每个请求都是一次新的核验。** 没有幂等性密钥，也没有用于重新读取核验结果的 endpoint，因此重试的请求会再次运行并计费。请存储响应。\n\n**沙盒。** 使用带有示例账户信息的沙盒 API 密钥。沙盒密钥不会调用银行，也不会产生费用。IBAN（如果无 IBAN 则为账号）的后 4 位字符决定回复结果：`0001` 为带有 `holder_name` 的 `close_match`，`0002` 为不带该名称的 `close_match`，`0003` 和 `0006` 为 `no_match`，`0004` 为 `cannot_verify`，`0005` 为 `503`，`0009` 为 `400`。任何其他结尾均为 `match`。\n\n**API 密钥。** 带有作用域的 API 密钥需要会话的写入权限。", "operationId": "post_v3_bank_account_check", "tags": [ "Standalone APIs" ], "x-didit-sdk": { "resource": "bank", "method": "account_check", "auth": "api_key", "server": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckRequest" }, "examples": { "Person, Nigeria": { "summary": "银行代码和账号，根据个人姓名进行核验", "value": { "country": "NGA", "account": { "bank_code": "000014", "account_number": "0123450001" }, "holder": { "full_name": "Maria Oliveira" }, "vendor_data": "payout_20481" } }, "Company, Nigeria": { "summary": "银行代码和账号，根据企业名称进行核验", "value": { "country": "NGA", "account": { "bank_code": "000014", "account_number": "0123456789" }, "holder": { "business_name": "Northwind Trading Ltd" } } } } } } }, "responses": { "200": { "description": "银行已响应。无论结果如何，该核验均会计费。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckResponse" }, "examples": { "Close match": { "summary": "银行持有的账户姓名与提交的姓名相近", "value": { "request_id": "c2f4a9e0-7b1d-4c3a-9e55-1d0a6b8f2a47", "result": "close_match", "holder_name": "MARIA R OLIVEIRA", "account": "****0001", "vendor_data": "payout_20481", "created_at": "2026-10-21T14:32:08Z" } }, "Match": { "summary": "银行持有的账户姓名与提交的姓名一致", "value": { "request_id": "5b0e2d7c-41a8-4f6e-9c3b-8e7d1a2f6c90", "result": "match", "holder_name": null, "account": "****6789", "vendor_data": null, "created_at": "2026-10-21T14:35:41Z" } } } } } }, "400": { "description": "按原样拒绝，且不计费。`field` 指出需修正的请求体字段，`reason` 说明原因，其原因与托管账户表单显示的原因相同。仅报告第一个被拒绝的字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Missing field": { "summary": "该国家/地区的核验需要银行代码", "value": { "detail": "The bank code is not valid (required).", "code": "invalid_account_input", "field": "account.bank_code", "reason": "required" } }, "Invalid IBAN": { "summary": "IBAN 长度与该国家/地区不符", "value": { "detail": "The iban is not valid (length).", "code": "invalid_account_input", "field": "account.iban", "reason": "length" } }, "Refused by the bank": { "summary": "银行拒绝了按所提交信息发送的账户", "value": { "detail": "The account was refused as typed (rejected).", "code": "invalid_account_input", "field": "account.account_number", "reason": "rejected" } }, "No name": { "summary": "`holder` 既没有 `full_name` 也没有 `business_name`", "value": { "detail": "Send full_name for a person or business_name for a company.", "code": "invalid_account_input", "field": "holder", "reason": "required" } }, "Consent required": { "summary": "该国家/地区的账户核验需要账户持有人的同意", "value": { "detail": "Account checks in this country need the account holder's explicit consent. Ask for it, then send `consent=true`.", "code": "invalid_account_input", "field": "consent", "reason": "required" } } } } } }, "401": { "description": "作用域 API 密钥已过期。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "402": { "description": "无法支付此项检查的费用，因此未运行。请为您的余额充值，然后重新发送。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Out of credit": { "summary": "您的余额不足以支付单次核验费用", "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me", "code": "insufficient_credits" } }, "Not in your contract": { "summary": "您的合同中未包含 Account check API 的价格", "value": { "detail": "Your contract does not price the Account check API. Contact your account manager.", "code": "contract_rate_missing" } } } } } }, "403": { "description": "`x-api-key` 请求头或 Bearer token 缺失或无效，请求来自密钥 IP 名单之外的地址，或者限定权限的密钥对会话没有写入权限。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Missing or invalid credentials": { "summary": "无有效的 API 密钥或 token", "value": { "detail": "You do not have permission to perform this action." } }, "No sessions write": { "summary": "对会话没有写入权限的作用域受限密钥", "value": { "detail": "This API key has no write access to sessions." } } } } } }, "404": { "description": "尚无账户检查支持此账户，因此未进行任何检查或计费。`country_not_covered`：没有任何账户检查支持其所在国家/地区，或支持该国家/地区中的此类账户（个人或企业）。`bank_not_covered`：没有任何账户检查支持其所属银行。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Country not covered": { "summary": "没有支持该国家/地区的账户检查", "value": { "detail": "No account check serves this country yet.", "code": "country_not_covered" } }, "Bank not covered": { "summary": "没有支持该账户所属银行的账户检查", "value": { "detail": "No account check serves this account's bank yet.", "code": "bank_not_covered" } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" }, "503": { "description": "银行未能响应。未执行核验亦未计费；请稍后重新发送核验请求。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankAccountCheckError" }, "examples": { "Unavailable": { "summary": "银行未响应", "value": { "detail": "The account check is temporarily unavailable and this request was not charged. Please try again.", "code": "account_check_unavailable" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/bank/account-check/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"country\": \"NGA\",\n \"account\": {\"bank_code\": \"000014\", \"account_number\": \"0123450001\"},\n \"holder\": {\"full_name\": \"Maria Oliveira\"},\n \"vendor_data\": \"payout_20481\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.bank.account_check(\n country=\"NGA\",\n account={\n \"account_number\": \"0123450001\",\n \"bank_code\": \"000014\",\n },\n holder={\n \"full_name\": \"Maria Oliveira\",\n },\n vendor_data=\"payout_20481\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.bank.accountCheck({\n country: \"NGA\",\n account: {\n account_number: \"0123450001\",\n bank_code: \"000014\",\n },\n holder: {\n full_name: \"Maria Oliveira\",\n },\n vendor_data: \"payout_20481\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Bank.AccountCheck(ctx, didit.BankAccountCheckRequest{\n\tCountry: \"NGA\",\n\tAccount: didit.BankAccountCheckRequestAccount{\n\t\tAccountNumber: didit.String(\"0123450001\"),\n\t\tBankCode: didit.String(\"000014\"),\n\t},\n\tHolder: didit.BankAccountCheckHolder{\n\t\tFullName: didit.String(\"Maria Oliveira\"),\n\t},\n\tVendorData: didit.String(\"payout_20481\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BankAccountCheckHolder;\nimport me.didit.types.BankAccountCheckPersonHolder;\nimport me.didit.types.BankAccountCheckRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.bank().accountCheck(BankAccountCheckRequest.builder()\n .country(\"NGA\")\n .account(BankAccountCheckRequest.Account.builder()\n .accountNumber(\"0123450001\")\n .bankCode(\"000014\")\n .build())\n .holder(BankAccountCheckHolder.ofBankAccountCheckPersonHolder(BankAccountCheckPersonHolder.builder()\n .fullName(\"Maria Oliveira\")\n .build()))\n .vendorData(\"payout_20481\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "bank->accountCheck([\n 'country' => 'NGA',\n 'account' => [\n 'account_number' => '0123450001',\n 'bank_code' => '000014',\n ],\n 'holder' => [\n 'full_name' => 'Maria Oliveira',\n ],\n 'vendor_data' => 'payout_20481',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.bank.account_check(\n country: \"NGA\",\n account: {\n account_number: \"0123450001\",\n bank_code: \"000014\",\n },\n holder: {\n full_name: \"Maria Oliveira\",\n },\n vendor_data: \"payout_20481\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Bank.AccountCheckAsync(new BankAccountCheckRequest\n{\n Country = \"NGA\",\n Account = new()\n {\n AccountNumber = \"0123450001\",\n BankCode = \"000014\",\n },\n Holder = new()\n {\n FullName = \"Maria Oliveira\",\n },\n VendorData = \"payout_20481\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/email/send/": { "post": { "summary": "发送邮箱验证码", "description": "向邮箱地址发送一次性验证码（OTP），然后通过 [`POST /v3/email/check/`](/zh/standalone-apis/email-check) 进行核验。\n\n**发送与核验的配对机制。** 验证状态由您的应用加上 `email` 地址作为键，核验调用不需要传入 `request_id`。每次新的发送都会创建一个处于待处理状态的验证，有效期为 **5 分钟**：在窗口期关闭前，使用相同的地址以及用户收到的验证码调用核验。在验证处于待处理状态期间再次针对同一地址调用发送，会为该同一验证生成一个全新验证码（`status: \"Retry\"`，相同的 `request_id`）；先前的验证码随即失效。通过这种方式最多可关联一次重试（共两次发送）；后续再次发送则会开启一个带有全新 `request_id` 的新验证。5 分钟的有效窗口从首次发送开始计算，不会因重试而延长。\n\n**可投递性预检。** 在发送任何内容之前，该地址都会通过语法以及 DNS/MX 验证。无法接收邮件的地址将返回 `200`，且 `status: \"Undeliverable\"`，`reason: \"email_can_not_be_delivered\"`：不会发送任何邮件，不收取任何费用，并且该验证会立即定为 `Declined`（后续核验将返回 `Expired or Not Found`）。如果发送因非地址原因失败（邮件无法交接投递），则返回 `503`：不会发送验证码，不收取任何费用，验证保持开启状态，并且可以重复相同的请求。\n\n**验证码格式与品牌定制。** 验证码长度为 4–8 个字符（`options.code_size`，默认为 6），默认是纯数字；设置 `options.alphanumeric_code: true` 可使用大写字母和数字（核验比对不区分大小写）。邮件模板可通过 `options.locale` 进行本地化（支持 54 种语言），并可通过 `options.use_white_label_customization` 使用您应用的白标品牌定制。\n\n**计费。** 每次成功发送（`status: \"Success\"`）消耗一个邮箱验证 API 额度，在发送时扣费。`Retry` 和 `Undeliverable` 发送免费，核验免费。\n\n**会话持久化。** 每次新验证都会作为 API 类型的会话进行持久化：`request_id` 是一个真实的会话 ID，您可以将其传递给 `GET /v3/session/{sessionId}/decision/`，该验证会显示在 Business Console 中，并且随着流程推进会触发 `status.updated` Webhook。\n\n**沙盒。** 沙盒 API 密钥跳过投递和计费：在请求验证后（格式错误的输入仍返回 `400`），endpoint 返回带有随机 `request_id` 的静态 `Success` payload；不会发送邮件，也不持久化任何内容。在沙盒核验中使用验证码 `123456`。\n\n**身份验证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。缺失或无效的凭据将返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`），此 API 从不返回 `401`。\n\n**速率限制。** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 间共享 300 个请求/分钟的写入预算；超出将返回 `429`。", "operationId": "post_v3email_send", "x-didit-sdk": { "resource": "email", "method": "send_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/email/send/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"alice@example.com\",\n \"options\": { \"code_size\": 6, \"locale\": \"en\" },\n \"vendor_data\": \"user-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.email.send_code(\n email=\"alice@example.com\",\n options={\n \"locale\": \"en\",\n },\n vendor_data=\"user-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.email.sendCode({\n email: \"alice@example.com\",\n options: {\n locale: \"en\",\n },\n vendor_data: \"user-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.SendCode(ctx, didit.EmailSendCodeParams{\n\tEmail: \"alice@example.com\",\n\tOptions: didit.Some(didit.EmailSendCodeParamsOptions{\n\t\tLocale: didit.Some(didit.EmailSendCodeParamsOptionsLocale(\"en\")),\n\t}),\n\tVendorData: didit.String(\"user-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EmailSendCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.email().sendCode(EmailSendCodeParams.builder()\n .email(\"alice@example.com\")\n .options(EmailSendCodeParams.Options.builder()\n .locale(EmailSendCodeParams.Options.Locale.of(\"en\"))\n .build())\n .vendorData(\"user-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "email->sendCode([\n 'email' => 'alice@example.com',\n 'options' => [\n 'locale' => 'en',\n ],\n 'vendor_data' => 'user-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.email.send_code(\n email: \"alice@example.com\",\n options: {\n locale: \"en\",\n },\n vendor_data: \"user-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Email.SendCodeAsync(new EmailSendCodeParams\n{\n Email = \"alice@example.com\",\n Options = new EmailSendCodeParamsOptions\n {\n Locale = new EmailSendCodeParamsOptionsLocale(\"en\"),\n },\n VendorData = \"user-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "收件人邮箱地址。格式错误的地址返回 `400`；语法有效但无法接收邮件（DNS/MX 验证失败）的地址返回 `200`，且 `status: \"Undeliverable\"`。", "example": "alice@example.com" }, "options": { "type": "object", "description": "一次性验证码格式、本地化及品牌化选项。所有字段均为可选。", "properties": { "code_size": { "type": "integer", "minimum": 4, "maximum": 8, "default": 6, "description": "OTP 中的字符数（默认为数字；当 `alphanumeric_code` 为 `true` 时为大写字母和数字）。" }, "alphanumeric_code": { "type": "boolean", "default": false, "description": "为 `true` 时，一次性验证码由大写字母 `A–Z` 和数字 `0–9` 组成，而非仅包含数字。`/v3/email/check/` 比对不区分大小写。" }, "locale": { "type": "string", "maxLength": 5, "enum": [ "en", "ar", "bn", "bg", "bs", "ca", "cs", "da", "de", "el", "es", "et", "fa", "fi", "fr", "he", "hi", "hr", "hu", "hy", "id", "it", "ja", "ka", "kk", "ko", "ky", "lt", "lv", "cnr", "mk", "mn", "ms", "nl", "no", "pl", "pt-BR", "pt", "ro", "ru", "sk", "sl", "so", "sq", "sr", "sv", "th", "tr", "uk", "uz", "vi", "zh-CN", "zh-TW", "zh" ], "description": "OTP 邮件模板的语言。默认为 `en`。不支持的值将返回 `400` 并列出所有支持的语言环境。", "example": "en" }, "use_white_label_customization": { "type": "boolean", "default": false, "description": "为 `true` 时，一次性验证码邮件将使用您应用的白标定制（logo、配色、发送方品牌标识），而非默认的 Didit 模板。" } } }, "signals": { "type": "object", "description": "关于终端用户的可选设备与网络信号，转发至反欺诈层以提升对滥用或自动化流量的检测能力。所有字段均为可选。", "properties": { "ip": { "type": "string", "description": "终端用户设备的 IP 地址。IPv4 或 IPv6。", "example": "192.0.2.1" }, "device_id": { "type": "string", "maxLength": 255, "description": "终端用户设备的唯一标识符。Android：`ANDROID_ID`；iOS：`identifierForVendor`。", "example": "8F0B8FDD-C2CB-4387-B20A-56E9B2E5A0D2" }, "device_platform": { "type": "string", "enum": [ "android", "ios", "ipados", "tvos", "web" ], "description": "终端用户设备的平台。" }, "device_model": { "type": "string", "maxLength": 255, "description": "终端用户设备的型号。", "example": "iPhone17,2" }, "os_version": { "type": "string", "maxLength": 64, "description": "终端用户设备的操作系统版本。", "example": "18.0.1" }, "app_version": { "type": "string", "maxLength": 64, "description": "您的应用版本。", "example": "1.2.34" }, "user_agent": { "type": "string", "maxLength": 512, "description": "终端用户浏览器或应用的 User-Agent。", "example": "Mozilla/5.0 (iPhone; CPU iPhone OS 14_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/14.0.3 Mobile/15E148 Safari/604.1" } } }, "vendor_data": { "type": "string", "description": "由调用方控制的可选标识符（您的内部用户 id、邮箱、UUID 等），在会话中持久化并在发送响应、匹配检查响应、Webhook 和 Business Console 中原样返回。可使用它将 Didit 的 `request_id` 与您的用户记录进行关联。" }, "metadata": { "type": "object", "nullable": true, "description": "可选的自由格式 JSON 对象，持久化保存在会话中，并在发送响应、匹配检查响应、Webhook 以及 Business Console 中回显。" } }, "required": [ "email" ] }, "examples": { "Numeric 6-digit code": { "summary": "默认 — 英文 6 位数字验证码", "value": { "email": "alice@example.com", "options": { "locale": "en" }, "vendor_data": "user-1234" } }, "Alphanumeric 8-character code": { "summary": "大写字母 + 数字，西班牙模板", "value": { "email": "bob@example.com", "options": { "code_size": 8, "alphanumeric_code": true, "locale": "es" } } }, "White-label branding": { "summary": "发送带有您应用白标定制的 OTP 邮件", "value": { "email": "carol@example.com", "options": { "locale": "en", "use_white_label_customization": true }, "vendor_data": "user-5678" } } } } } }, "responses": { "200": { "description": "已确认发送。请检查 `status`：`Success` 和 `Retry` 表示验证码正在发送中；`Undeliverable` 表示该地址无法接收邮件，且验证已最终确定为 `Declined`。`request_id` 是持久化的会话 ID（在 `Retry` 时 ID 相同）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationSendResponse" }, "examples": { "Success": { "summary": "已为新验证发送一次性验证码邮件（计费）", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Success", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Retry": { "summary": "在 5 分钟时间窗口内的第二次发送：新验证码，相同的 request_id，免费", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Retry", "reason": null, "vendor_data": "user-1234", "metadata": null } }, "Undeliverable": { "summary": "地址未通过 DNS/MX 验证，验证最终状态为已拒绝，不会产生费用", "value": { "request_id": "cb1a5011-344d-444d-bdce-218904745d7f", "status": "Undeliverable", "reason": "email_can_not_be_delivered", "vendor_data": "user-1234", "metadata": null } } } } } }, "400": { "description": "验证错误 — DRF 的字段错误包装格式：每个违规字段对应一个消息数组，对于选项错误则嵌套在 `options` 下。", "content": { "application/json": { "examples": { "Invalid email": { "summary": "邮箱地址格式错误", "value": { "email": [ "Enter a valid email address." ] } }, "Unsupported locale": { "summary": "`options.locale` 不在支持的集合内", "value": { "options": { "locale": [ "Invalid locale. Supported locales are en, ar, bn, bg, bs, ca, cs, da, de, el, es, et, fa, fi, fr, he, hi, hr, hu, hy, id, it, ja, ka, kk, ko, ky, lt, lv, cnr, mk, mn, ms, nl, no, pl, pt-BR, pt, ro, ru, sk, sl, so, sq, sr, sv, th, tr, uk, uz, vi, zh-CN, zh-TW, zh." ] } } }, "Code size out of range": { "summary": "`options.code_size` 超出 4–8 范围", "value": { "options": { "code_size": [ "Ensure this value is less than or equal to 8." ] } } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头时返回（`{\"detail\": ...}`）；错误、已撤销或已过期的密钥返回 `401`。当组织的余额无法覆盖单次邮箱验证 API 额度时，也会在任何发送之前返回（`{\"error\": ...}`）。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付发送价格", "value": { "error": "You don't have enough credits to perform this request." } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "503": { "description": "由于与地址无关的原因（无法连接邮件服务商、超时或拒绝发送本身）导致电子邮件无法发送，因此未发送验证码，也不会产生计费或计入发送尝试次数。请重复相同的请求。", "content": { "application/json": { "examples": { "Email delivery unavailable": { "summary": "自动重试一次后，邮件服务商仍然失败", "value": { "detail": "Email delivery is temporarily unavailable. Please try again." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/email/check/": { "post": { "summary": "核验邮箱验证码", "description": "验证通过 [`POST /v3/email/send/`](/zh/standalone-apis/email-send) 投递的 OTP，并获取最终验证结果以及邮箱情报：可投递性、数据泄露暴露情况（来自泄露情报数据库的 `is_breached` 及 `breaches` 列表）、一次性邮箱提供商检测，以及该地址在您各会话间的重复使用情况。\n\n**检查如何查找验证记录。** 匹配依据为您的应用加上 `email` 地址，`request_id` 不是输入参数。系统会检查过去 **5 分钟**内创建的最新待处理验证。如果不存在（从未发送、已完成、发送时不可投递或早于 5 分钟），该 endpoint 返回 `200`，且 `status: \"Expired or Not Found\"`。\n\n**尝试次数预算。** 每次验证允许 **3 次验证码尝试**。前两次输入错误验证码返回 `status: \"Failed\"`，包含剩余尝试次数且 `email: null`；第三次输入错误验证码会将验证最终定性为 `Declined`，附带 `EMAIL_CODE_ATTEMPTS_EXCEEDED` 警告并返回完整的邮箱报告。验证码比较不区分大小写（适用于 `alphanumeric_code` 发送方式）；仅最新发送的验证码有效。\n\n**结果。** `Approved`：验证码正确且未触发拒绝风险。`Declined`（最终状态）：验证码正确但匹配到了拒绝风险（下方的 `DECLINE` 操作、黑名单地址，或在完成验证时发现地址不可投递），或尝试次数已耗尽。`Failed`：验证码错误，仍有剩余尝试次数。`Expired or Not Found`：无可检查内容。在 `Approved`/`Declined` 状态下，`request_id` 等于发送时的 `request_id`（会话 ID），且 `email` 携带完整报告（`is_breached`、`breaches`、`is_disposable`、`is_undeliverable`、`warnings`、`lifecycle`、`matches`）；在 `Failed` 和 `Expired or Not Found` 状态下，`request_id` 为一次性随机 UUID。\n\n**风险操作。** `duplicated_email_action`、`breached_email_action` 和 `disposable_email_action` 决定在验证码正确但检测到相应风险时的处理方式：`DECLINE` 会将最终状态更改为 `Declined`；`NO_ACTION`（默认）仅在 `email.warnings` 中记录该风险，不影响最终状态。\n\n**计费。** 核验免费，成功的发送操作已扣除额度。\n\n**会话持久化。** 最终完成的核验会更新由发送操作创建的会话（在 Business Console 中可见，可通过 `GET /v3/session/{sessionId}/decision/` 查询），并触发 `status.updated` Webhook。\n\n**沙盒。** 沙盒 API 密钥跳过所有处理流程：任何格式正确的验证码（包括 `123456`）均返回包含简化 `email` 对象（`status`、`email`、`is_breached`、`is_disposable`、`is_undeliverable`）的静态 `Approved` payload；格式错误的输入仍返回 `400`。不会持久化任何数据。\n\n**认证。** 在 `x-api-key` 请求头中发送您应用的 API 密钥。凭证缺失或无效返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`），此 API 从不返回 `401`。\n\n**速率限制。** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 间共享 300 次请求/分钟的写入预算；超出将返回 `429`。\n\n**社交足迹。** 将 `enable_social` 设置为 `true` 可添加 `email_social` 区块：该地址注册的在线平台，包含各分类计数以及任何可用的个人资料详情。`profiles_registered: 0` 表示已检查相关平台且未发现该地址注册，这是有效且计费的响应。当未请求该附加功能或核验无法完成时，该区块不存在，且在这种情况下不予计费。计费时将在该 endpoint 本身价格的基础上，按每次请求额外增加一个 `email_social` 计费单位。", "operationId": "post_v3email_check", "x-didit-sdk": { "resource": "email", "method": "check_code", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/email/check/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"email\": \"alice@example.com\",\n \"code\": \"123456\",\n \"disposable_email_action\": \"DECLINE\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.email.check_code(\n email=\"alice@example.com\",\n code=\"123456\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.email.checkCode({\n email: \"alice@example.com\",\n code: \"123456\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Email.CheckCode(ctx, didit.EmailCheckCodeParams{\n\tEmail: \"alice@example.com\",\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EmailCheckCodeParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.email().checkCode(EmailCheckCodeParams.builder()\n .email(\"alice@example.com\")\n .code(\"123456\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "email->checkCode([\n 'email' => 'alice@example.com',\n 'code' => '123456',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.email.check_code(\n email: \"alice@example.com\",\n code: \"123456\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Email.CheckCodeAsync(new EmailCheckCodeParams\n{\n Email = \"alice@example.com\",\n Code = \"123456\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "与匹配的 [`POST /v3/email/send/`](/zh/standalone-apis/email-send) 调用中使用的相同邮箱地址。这是将核验与发送关联起来的依据。", "example": "alice@example.com" }, "code": { "type": "string", "maxLength": 10, "description": "终端用户收到的一次性验证码：4–8 位数字，若发送时使用了 `alphanumeric_code: true`，则为 4–8 位字母/数字。比对不区分大小写。", "example": "123456" }, "duplicated_email_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当您应用的另一位用户（不同的 `vendor_data`）已经使用过相同地址并已通过验证（仅计入先前已通过的验证）时采取的操作。`DECLINE` 会将最终的 `status` 变为 `Declined`；`NO_ACTION` 会在 `email.warnings` 中记录该风险并填充 `email.matches`。" }, "breached_email_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当地址出现在已知数据泄露事件中（`email.is_breached`）时的处理操作。`DECLINE` 会将最终 `status` 变为 `Declined`；`NO_ACTION` 会在 `email.warnings` 中记录该风险。" }, "disposable_email_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当域名属于一次性/临时邮箱提供商（`email.is_disposable`）时采取的操作。`DECLINE` 会将最终的 `status` 变为 `Declined`；`NO_ACTION` 会在 `email.warnings` 中记录该风险。" }, "enable_enrichment": { "type": "boolean", "default": false, "description": "为 `true` 时，还会对该地址运行邮箱情报分析：风险评分及其数据泄露历史。除此 endpoint 本身的价格外，每次请求按单次 `email_intelligence_api` 计费（标价为 $0.05）。当您的余额不足以支付时，请求将返回 `403`。", "example": false }, "email_intelligence_score_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "邮箱情报风险评分高于阈值时的操作。`DECLINE` 会将最终 `status` 翻转为 `Declined`；`NO_ACTION` 会记录该信号而不拒绝。仅在 `enable_enrichment` 为 `true` 时生效。" }, "recent_email_breach_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当该地址出现在近期已知的数据泄露事件中时采取的操作。`DECLINE` 会将最终 `status` 更改为 `Declined`；`NO_ACTION` 仅记录该信号而不拒绝。仅在 `enable_enrichment` 为 `true` 时生效。" }, "frequent_email_breach_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "当该地址出现在多起已知的数据泄露事件中时采取的操作。`DECLINE` 会将最终 `status` 更改为 `Declined`；`NO_ACTION` 仅记录该信号而不拒绝。仅在 `enable_enrichment` 为 `true` 时生效。" }, "enable_social": { "type": "boolean", "default": false, "description": "为 true 时，还会查找该地址的社交足迹，即其注册所在的邮箱、社交、职业、电子商务和娱乐平台。除此 endpoint 本身的价格外，每次请求按一个 `email_social` 单位计费。", "example": true }, "email_no_social_presence_action": { "type": "string", "enum": [ "NO_ACTION", "DECLINE" ], "default": "NO_ACTION", "description": "社交足迹核查发现该地址在其覆盖的所有平台上均未注册时的操作。此 endpoint 仅接受 NO_ACTION 和 DECLINE；同名工作流配置键上提供 REVIEW。" } }, "required": [ "email", "code" ] }, "examples": { "Default": { "summary": "记录任何风险但绝不自动拒绝", "value": { "email": "alice@example.com", "code": "123456" } }, "Strict risk policy": { "summary": "自动拒绝一次性邮箱和泄露邮箱", "value": { "email": "alice@example.com", "code": "123456", "disposable_email_action": "DECLINE", "breached_email_action": "DECLINE" } } } } } }, "responses": { "200": { "description": "核验已完成：错误的验证码和缺失的验证也会返回 `200`；请检查 `status`，而非 HTTP 状态码。`email` 仅在最终结果（`Approved`/`Declined`）中填充，在 `Failed` 时为 `null`，在 `Expired or Not Found` 时不存在。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmailVerificationCheckResponse" }, "examples": { "Approved": { "summary": "验证码正确：干净的地址，完整的邮箱报告", "value": { "request_id": "e39cb057-92fc-4b59-b84e-02fec29a0f24", "status": "Approved", "message": "The verification code is correct.", "email": { "status": "Approved", "email": "alice@example.com", "is_breached": false, "breaches": [], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Approved with breach exposure": { "summary": "验证码正确；数据泄露风险记录为警告（breached_email_action=NO_ACTION）", "value": { "request_id": "3a1f2b6c-9d4e-4f7a-8b2c-1e5d6f7a8b9c", "status": "Approved", "message": "The verification code is correct.", "email": { "status": "Approved", "email": "bob@example.com", "is_breached": true, "breaches": [ { "name": "ExampleApp", "domain": "exampleapp.com", "breach_date": "2019-03-21", "breach_emails_count": 763117, "description": "In March 2019, the social platform ExampleApp suffered a data breach that exposed email addresses and passwords.", "logo_path": "https:///logos/ExampleApp.png", "data_classes": [ "email_addresses", "passwords" ], "is_verified": true } ], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [ { "feature": "EMAIL", "risk": "BREACHED_EMAIL_DETECTED", "additional_data": null, "log_type": "information", "short_description": "Breached email detected", "long_description": "This email address was found in one or more known data breaches." } ], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "835126", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_APPROVED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": null, "fee": 0 } ], "matches": [] }, "vendor_data": "user-5678", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Failed (attempts remaining)": { "summary": "验证码错误，用户可以重试；此处的 request_id 为一次性 UUID", "value": { "request_id": "11111111-2222-3333-4444-555555555555", "status": "Failed", "message": "The verification code is incorrect. Attempts remaining: 2", "email": null, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:21.512340+00:00" } }, "Declined (risk policy)": { "summary": "验证码正确，但地址是一次性邮箱且 disposable_email_action=DECLINE", "value": { "request_id": "8c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "status": "Declined", "message": "The verification code is correct.", "email": { "status": "Declined", "email": "tempuser42@mailinator.com", "is_breached": false, "breaches": [], "is_disposable": true, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-06-12T01:24:47.311323Z", "warnings": [ { "feature": "EMAIL", "risk": "DISPOSABLE_EMAIL_DETECTED", "additional_data": null, "log_type": "error", "short_description": "Disposable email detected", "long_description": "The system detected that the email is disposable, which is not allowed." } ], "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-06-12T01:23:39.580554+00:00", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-06-12T01:24:47.311201+00:00", "details": { "code_tried": "123456", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_DECLINED", "timestamp": "2026-06-12T01:24:47.384292+00:00", "details": { "reason": "DISPOSABLE_EMAIL_DETECTED" }, "fee": 0 } ], "matches": [] }, "vendor_data": "user-1234", "metadata": null, "created_at": "2026-06-12T01:24:47.401719+00:00" } }, "Expired or Not Found": { "summary": "过去 5 分钟内该地址没有待处理的验证", "value": { "request_id": "88808a77-06e9-4cb0-85f5-9c052ddfd987", "status": "Expired or Not Found", "message": "No pending email verification found in the last 5 minutes.", "vendor_data": null, "metadata": null, "created_at": "2026-06-12T01:24:59.887904+00:00" } } } } } }, "400": { "description": "验证错误 — DRF 的字段错误包装格式：每个违规字段对应一个消息数组。", "content": { "application/json": { "examples": { "Invalid email": { "summary": "邮箱地址格式错误", "value": { "email": [ "Enter a valid email address." ] } }, "Missing code": { "summary": "请求体中未包含 `code`", "value": { "code": [ "This field is required." ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头时返回；错误、已撤销或已过期的密钥返回 `401`。核验是免费的，因此此处不进行额度检查。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/workflows/": { "get": { "summary": "列出工作流", "description": "列出您的工作流，最新的排在最前，采用 limit/offset 分页封装格式（`{count, next, previous, results}`，默认页面大小为 50）。每一行代表一个版本；`workflow_id` 是稳定组 ID，新会话将使用最新的 `published` 版本。", "operationId": "list_workflows", "x-didit-sdk": { "resource": "workflows", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "页面大小（每页工作流数量）。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "返回第一个工作流前跳过的行数。" } ], "responses": { "200": { "description": "按 `created_at` 降序排列的一页工作流，封装在分页结构中。`results` 中的每一项均为 `WorkflowListItem`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "该应用的工作流版本总数。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的 URL，最后一页为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的 URL，第一页为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowListItem" } } } }, "examples": { "Two workflows": { "summary": "一个默认的 KYC 工作流和一个草稿状态的 KYC + AML 工作流", "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_id": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_label": "Standard KYC", "workflow_type": "kyc", "is_default": true, "is_archived": false, "is_white_label_enabled": false, "total_price": 0.15, "min_price": 0.15, "max_price": 0.15, "features": "OCR + LIVENESS + FACE_MATCH", "is_simple_workflow": true, "is_editable": false, "workflow_url": "https://verify.didit.me/u/_yljPOx8RWG3UAz5ZRQGVQ", "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 2, "status": "published", "has_draft": false, "created_by": { "name": "Alex Mateo", "email": "alex@example.com", "type": "user" }, "updated_at": "2026-04-12T10:30:00Z" }, { "uuid": "b2c3d4e5-6789-01bc-defa-222222222222", "workflow_id": "b2c3d4e5-6789-01bc-defa-222222222222", "workflow_label": "Full Verification + AML", "workflow_type": "kyc", "is_default": false, "is_archived": false, "is_white_label_enabled": false, "total_price": 0.25, "min_price": 0.25, "max_price": 0.25, "features": "OCR + LIVENESS + FACE_MATCH + AML", "is_simple_workflow": true, "is_editable": true, "workflow_url": "https://verify.didit.me/u/Aq3kPOx8RWG3UAz5ZRQGVQ", "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 1, "status": "draft", "has_draft": true, "created_by": null, "updated_at": "2026-04-15T18:05:21Z" } ] } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或属于其他应用。响应体：`{\"detail\": \"You do not have permission to perform this action.\"}`。请通过 [Auth API](/zh/auth-api/get-credentials) 刷新 token 并重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制。请使用指数退避重试，并遵循任何 `Retry-After` 请求头。" }, "500": { "description": "构建列表时发生意外服务器错误。该请求可以安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/workflows/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Accept: application/json'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.workflows.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.workflows.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Workflows.ListAutoPaging(ctx, didit.WorkflowsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.workflows().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "workflows->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.workflows.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Workflows.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "创建工作流", "description": "创建简单工作流。按执行顺序发送 `features`（适用排序规则）；默认为 `published` v1。请求体仅接受 `SimpleWorkflowRequest` 中列出的字段，任何其他键（包括 `workflow_type`）都会被拒绝并返回 400。非幂等：每次调用都会创建一个新工作流。每个应用最多支持 50 个工作流。", "operationId": "create_workflow", "x-didit-sdk": { "resource": "workflows", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleWorkflowRequest" }, "examples": { "Simple KYC": { "summary": "身份证件、活体检测与人脸比对线性工作流", "value": { "workflow_label": "Standard KYC", "features": [ { "feature": "OCR", "config": { "duplicated_user_action": "review" } }, { "feature": "LIVENESS", "config": { "face_liveness_method": "passive" } }, { "feature": "FACE_MATCH", "config": { "face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60 } } ] } }, "KYC + AML": { "summary": "身份证件验证后运行 AML", "value": { "workflow_label": "KYC with AML", "features": [ { "feature": "OCR" }, { "feature": "AML", "config": { "aml_score_review_threshold": 70, "aml_score_approve_threshold": 30 } } ] } }, "Questionnaire workflow": { "summary": "运行通过 POST /v3/questionnaires/ 创建的问卷", "value": { "workflow_label": "Source of Funds", "features": [ { "feature": "QUESTIONNAIRE", "config": { "questionnaire_uuid": "11111111-2222-3333-4444-555555555555", "review_questionnaire_manually": true } } ] } } } } } }, "responses": { "201": { "description": "工作流已创建。响应体为完整的工作流配置，与 `GET /v3/workflows/{settings_uuid}/` 返回的原生 `VerificationSettings` 序列化内容相同（约 190 个字段：每个功能开关、阈值、操作以及生成的 `workflow_graph`），而非精简的列表项。请存储 `uuid`（同时也暴露为 `workflow_id`），以便在后续创建会话调用时引用它。注意：`features` 是以 `\" + \"` 连接的字符串，价格为 JSON 数字。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetail" }, "examples": { "Created (abbreviated)": { "summary": "完整配置对象的关键字段", "value": { "uuid": "c3d4e5f6-7890-12cd-ef34-333333333333", "workflow_id": "c3d4e5f6-7890-12cd-ef34-333333333333", "workflow_label": "Standard KYC", "workflow_type": null, "is_default": false, "is_archived": false, "total_price": 0.15, "min_price": 0.15, "max_price": 0.15, "features": "OCR + LIVENESS + FACE_MATCH", "is_simple_workflow": false, "is_editable": false, "workflow_url": "https://verify.didit.me/u/w9TkPOx8RWG3UAz5ZRQGVQ", "workflow_graph": { "start_node": "ocr", "nodes": "... one node per feature plus a final status node ..." }, "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 1, "status": "published", "published_at": "2026-05-17T10:30:00Z", "created_at": "2026-05-17T10:30:00Z", "updated_at": "2026-05-17T10:30:00Z" } } } } } }, "400": { "description": "验证错误。常见原因：顶级键不在接受的白名单中（例如 `workflow_type`）、未知的 `feature` 值、功能放置在其依赖项之前（例如在 `OCR` 之前放置 `FACE_MATCH`）、将被动功能（`AML`、`IP_ANALYSIS`、`DATABASE_VALIDATION`、`KYB_KEY_PEOPLE`）用作第一步、`QUESTIONNAIRE` 功能的 `config.questionnaire_uuid` 在此应用中不存在、`SIGNATURE` 功能在没有待签署证件的情况下上线、`SIGNATURE` 功能设置为 `signature_level: \"aes\"` 但高级签名（AES）不可用（`aes_not_available`，请参阅工作流上的 `signature_availability`），或阈值超出范围。响应体是 DRF 验证错误对象 — 键为字段名，值为人类可读消息的数组。", "content": { "application/json": { "examples": { "Advanced (AES) not available": { "value": { "features": { "signature_level": [ "Node 'signature': Advanced (AES) is not available yet (aes_not_available)." ] } } }, "Signature step with no document": { "value": { "features": { "non_field_errors": [ "Node 'signature': Add a document to sign, or let each session bring its own." ] } } }, "Missing feature": { "value": { "features": [ "At least one feature is required." ] } }, "Unknown top-level field": { "value": { "workflow_type": [ "The v3 workflow API only accepts `workflow_label`, `is_default`, `status`, `features`, `is_white_label_enabled`, `is_desktop_allowed`, `max_retry_attempts`, `retry_window_days`, `session_expiration_time`, `face_liveness_max_attempts`, `face_match_max_attempts`." ] } }, "Unknown feature": { "value": { "features": [ "Invalid feature 'FOO'. Allowed values: AGE_ESTIMATION, AML, DATABASE_VALIDATION, EMAIL_VERIFICATION, FACE_MATCH, IP_ANALYSIS, KYB_DOCUMENTS, KYB_KEY_PEOPLE, KYB_REGISTRY, LIVENESS, NFC, OCR, PHONE_VERIFICATION, PROOF_OF_ADDRESS, QUESTIONNAIRE." ] } }, "Ordering": { "value": { "features": [ "Feature 'FACE_MATCH' must appear after one of: OCR." ] } }, "Questionnaire not found": { "value": { "features": "Questionnaire '11111111-2222-3333-4444-555555555555' was not found for this application. Create the questionnaire first, then use its questionnaire_id." } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或限定于其他应用。请通过 [Auth API](/zh/auth-api/get-credentials) 刷新并重试。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "415": { "description": "不支持的媒体类型。请设置 `Content-Type: application/json` 并发送 JSON 请求体。" }, "429": { "description": "超出速率限制。请使用指数退避重试。" }, "500": { "description": "创建工作流时发生意外服务器错误。可安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/workflows/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"workflow_label\": \"Standard KYC\",\n \"features\": [\n {\"feature\": \"OCR\"},\n {\"feature\": \"LIVENESS\", \"config\": {\"face_liveness_method\": \"passive\"}},\n {\"feature\": \"FACE_MATCH\", \"config\": {\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60}}\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.workflows.create(\n workflow_label=\"Standard KYC\",\n features=[{\n \"feature\": \"OCR\",\n \"config\": {\"duplicated_user_action\": \"review\"},\n }, {\n \"feature\": \"LIVENESS\",\n \"config\": {\"face_liveness_method\": \"passive\"},\n }, {\n \"feature\": \"FACE_MATCH\",\n \"config\": {\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60},\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.workflows.create({\n workflow_label: \"Standard KYC\",\n features: [{\n feature: \"OCR\",\n config: { duplicated_user_action: \"review\" },\n }, {\n feature: \"LIVENESS\",\n config: { face_liveness_method: \"passive\" },\n }, {\n feature: \"FACE_MATCH\",\n config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Create(ctx, didit.SimpleWorkflowRequest{\n\tWorkflowLabel: didit.String(\"Standard KYC\"),\n\tFeatures: []didit.SimpleWorkflowFeature{{\n\t\tFeature: \"OCR\",\n\t\tConfig: didit.Some(map[string]any{\"duplicated_user_action\": \"review\"}),\n\t}, {\n\t\tFeature: \"LIVENESS\",\n\t\tConfig: didit.Some(map[string]any{\"face_liveness_method\": \"passive\"}),\n\t}, {\n\t\tFeature: \"FACE_MATCH\",\n\t\tConfig: didit.Some(map[string]any{\"face_match_score_decline_threshold\": 40, \"face_match_score_review_threshold\": 60}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SimpleWorkflowFeature;\nimport me.didit.types.SimpleWorkflowRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.workflows().create(SimpleWorkflowRequest.builder()\n .workflowLabel(\"Standard KYC\")\n .features(List.of(\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"OCR\"))\n .config(Map.of(\"duplicated_user_action\", \"review\"))\n .build(),\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"LIVENESS\"))\n .config(Map.of(\"face_liveness_method\", \"passive\"))\n .build(),\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"FACE_MATCH\"))\n .config(Map.of(\"face_match_score_decline_threshold\", 40, \"face_match_score_review_threshold\", 60))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "workflows->create([\n 'workflow_label' => 'Standard KYC',\n 'features' => [[\n 'feature' => 'OCR',\n 'config' => ['duplicated_user_action' => 'review'],\n ], [\n 'feature' => 'LIVENESS',\n 'config' => ['face_liveness_method' => 'passive'],\n ], [\n 'feature' => 'FACE_MATCH',\n 'config' => ['face_match_score_decline_threshold' => 40, 'face_match_score_review_threshold' => 60],\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.workflows.create(\n workflow_label: \"Standard KYC\",\n features: [{\n feature: \"OCR\",\n config: { duplicated_user_action: \"review\" },\n }, {\n feature: \"LIVENESS\",\n config: { face_liveness_method: \"passive\" },\n }, {\n feature: \"FACE_MATCH\",\n config: { face_match_score_decline_threshold: 40, face_match_score_review_threshold: 60 },\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Workflows.CreateAsync(new SimpleWorkflowRequest\n{\n WorkflowLabel = \"Standard KYC\",\n Features = new SimpleWorkflowFeature[]\n {\n new()\n {\n Feature = \"OCR\",\n Config = new Dictionary { [\"duplicated_user_action\"] = \"review\" },\n },\n new()\n {\n Feature = \"LIVENESS\",\n Config = new Dictionary { [\"face_liveness_method\"] = \"passive\" },\n },\n new()\n {\n Feature = \"FACE_MATCH\",\n Config = new Dictionary { [\"face_match_score_decline_threshold\"] = 40, [\"face_match_score_review_threshold\"] = 60 },\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/workflows/{settings_uuid}/": { "get": { "summary": "获取工作流", "description": "通过 `settings_uuid` 获取某个工作流版本的完整配置：功能开关、阈值、允许的证件、图谱、重试策略、回调和定价。", "operationId": "get_workflow", "x-didit-sdk": { "resource": "workflows", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "settings_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "工作流每个版本对应的 UUID（列表 endpoint 返回的 `uuid` 值）。工作流的每个版本都有其自己的 `settings_uuid`。" } ], "responses": { "200": { "description": "完整的工作流配置。其结构为原始的 `VerificationSettings` 序列化结果（约 190 个字段：涵盖每个功能开关、阈值、警告操作、允许证件配置、`workflow_graph`、重试策略、回调以及定价）。以下示例已简化。注意事项：`features` 为用 `\" + \"` 连接的字符串（例如 `\"OCR + LIVENESS\"`），价格为 JSON 数字，且仅对于 `draft` 版本 `is_editable` 为 `true`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetail" }, "examples": { "KYC workflow with face match (abbreviated)": { "value": { "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_id": "a1b2c3d4-5678-90ab-cdef-111111111111", "workflow_label": "Standard KYC", "workflow_type": "kyc", "is_default": true, "is_archived": false, "is_liveness_enabled": true, "face_liveness_method": "passive", "face_liveness_score_decline_threshold": 50, "face_liveness_score_review_threshold": 70, "is_face_match_enabled": true, "face_match_score_decline_threshold": 40, "face_match_score_review_threshold": 60, "is_aml_enabled": false, "is_phone_verification_enabled": false, "is_email_verification_enabled": false, "is_database_validation_enabled": false, "is_ip_analysis_enabled": false, "is_nfc_enabled": false, "duplicated_user_action": "no_action", "documents_allowed": { "ESP": { "P": { "sides": 1, "enabled": 1, "subtypes": [ "EPASSPORT", "PASSPORT_GENERIC" ], "preferred_characters": "latin", "expiration_check_mode": "strict" } } }, "max_retry_attempts": 3, "retry_window_days": 7, "session_expiration_time": 604800, "version": 2, "status": "published", "published_at": "2026-04-12T10:30:00Z", "is_simple_workflow": false, "is_editable": false, "workflow_url": "https://verify.didit.me/u/_yljPOx8RWG3UAz5ZRQGVQ", "total_price": 0.15, "min_price": 0.15, "max_price": 0.15, "features": "OCR + LIVENESS + FACE_MATCH", "created_at": "2025-01-15T10:30:00Z", "updated_at": "2026-04-12T10:30:00Z" } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "已验证身份的应用中不存在具有此 `settings_uuid` 的工作流。可能是 UUID 错误，或者它属于另一个应用；Didit 刻意不对这两种情况进行区分，以避免泄露跨应用记录的存在。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制。请使用指数退避重试。" }, "500": { "description": "意外服务器错误。可安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/workflows/a1b2c3d4-5678-90ab-cdef-111111111111/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.workflows.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.workflows.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.workflows().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "workflows->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.workflows.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Workflows.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "更新工作流", "description": "更新工作流。版本控制取决于您发送的 `status` 字段以及该版本的当前状态：(1) **已发布**版本未传 `status` → 已发布版本就地更新（相同的 `uuid`，相同的 `version`）；(2) **草稿**未传 `status` → 草稿更新并立即发布；(3) **已发布**版本传入 `status: \"published\"` → 在同一个 `workflow_id` 下创建并返回一个新的已发布版本（新的 `uuid`，`version` + 1），并删除该分组中现有的任何草稿；(4) `status: \"draft\"` 将草稿保持为草稿（自动保存），但若在已发布版本上操作则会被拒绝并返回 400（`\"Cannot revert a published version to draft.\"`）。请求体接受与创建时相同的严格字段白名单 — 未知键将被拒绝并返回 400。", "operationId": "update_workflow", "x-didit-sdk": { "resource": "workflows", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "settings_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "要更新的工作流版本 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleWorkflowUpdateRequest" }, "examples": { "Replace features": { "summary": "发送完整的预期功能顺序", "value": { "features": [ { "feature": "OCR" }, { "feature": "AML" } ] } }, "Rename": { "summary": "重命名工作流", "value": { "workflow_label": "Premium KYC" } }, "Set as default": { "summary": "将此工作流设为应用的默认工作流", "value": { "is_default": true } }, "Update config": { "summary": "更改功能配置", "value": { "features": [ { "feature": "OCR" }, { "feature": "LIVENESS", "config": { "face_liveness_method": "passive" } } ] } }, "Publish a draft": { "summary": "将草稿转为已发布", "value": { "status": "published" } } } } } }, "responses": { "200": { "description": "工作流已更新。响应体为最终版本的完整配置（与 `GET /v3/workflows/{settings_uuid}/` 相同的原始 `VerificationSettings` 结构）。当更新创建了新版本（在已发布的记录上发送了 `status: \"published\"`）时，返回的 `uuid` 和 `version` 会与您执行 PATCH 操作时的不同，后续调用请使用返回的 `uuid`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowDetail" } } } }, "400": { "description": "验证错误 — 存在白名单之外的顶层键、未知的功能、无效的排序、超出范围的阈值、引用了不存在的问卷、配置了 `SIGNATURE` 功能但在上线时没有待签署的证件、新增了 `signature_level: \"aes\"` 的 `SIGNATURE` 功能但高级（AES）不可用（`aes_not_available`，请参见工作流上的 `signature_availability`；已存储 `aes` 的步骤将予以保留），或者对已发布的版本提交了 `status: \"draft\"`（`\"Cannot revert a published version to draft.\"`）。响应体是以字段名为键的 DRF 验证错误。" }, "403": { "description": "API 密钥缺失或无效。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "已验证身份的应用中不存在具有此 `settings_uuid` 的工作流。" }, "415": { "description": "不支持的媒体类型。请设置 `Content-Type: application/json`。" }, "429": { "description": "超出速率限制。请使用指数退避重试。" }, "500": { "description": "意外服务器错误。可安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH 'https://verification.didit.me/v3/workflows/a1b2c3d4-5678-90ab-cdef-111111111111/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"workflow_label\": \"Premium KYC\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.workflows.update(\n \"11111111-2222-3333-4444-555555555555\",\n features=[{\n \"feature\": \"OCR\",\n }, {\n \"feature\": \"AML\",\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.workflows.update(\"11111111-2222-3333-4444-555555555555\", {\n features: [{\n feature: \"OCR\",\n }, {\n feature: \"AML\",\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Workflows.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SimpleWorkflowUpdateRequest{\n\tFeatures: didit.Some([]didit.SimpleWorkflowFeature{{\n\t\tFeature: \"OCR\",\n\t}, {\n\t\tFeature: \"AML\",\n\t}}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SimpleWorkflowFeature;\nimport me.didit.types.SimpleWorkflowUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.workflows().update(\"11111111-2222-3333-4444-555555555555\", SimpleWorkflowUpdateRequest.builder()\n .features(List.of(\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"OCR\"))\n .build(),\n SimpleWorkflowFeature.builder()\n .feature(SimpleWorkflowFeature.Feature.of(\"AML\"))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "workflows->update('11111111-2222-3333-4444-555555555555', [\n 'features' => [[\n 'feature' => 'OCR',\n ], [\n 'feature' => 'AML',\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.workflows.update(\n \"11111111-2222-3333-4444-555555555555\",\n features: [{\n feature: \"OCR\",\n }, {\n feature: \"AML\",\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Workflows.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new SimpleWorkflowUpdateRequest\n{\n Features = new SimpleWorkflowFeature[]\n {\n new()\n {\n Feature = \"OCR\",\n },\n new()\n {\n Feature = \"AML\",\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "删除工作流", "description": "永久删除单个工作流版本（无法撤销）。现有会话会保留其验证结果，但其工作流引用会被清除；同一 `workflow_id` 分组中的其他版本不会被删除。", "operationId": "delete_workflow", "x-didit-sdk": { "resource": "workflows", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Workflows" ], "parameters": [ { "name": "settings_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "要删除的工作流版本 UUID。" } ], "responses": { "204": { "description": "工作流已删除。响应体为空。" }, "403": { "description": "API 密钥缺失或无效。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "已验证身份的应用中不存在具有此 `settings_uuid` 的工作流。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制。请使用指数退避重试。" }, "500": { "description": "意外服务器错误。可安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE 'https://verification.didit.me/v3/workflows/a1b2c3d4-5678-90ab-cdef-111111111111/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.workflows.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.workflows.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Workflows.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.workflows().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "workflows->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.workflows.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Workflows.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/questionnaires/": { "get": { "summary": "列出问卷", "description": "列出您的问卷，最新的排在最前，采用 limit/offset 分页封装格式（`{count, next, previous, results}`，默认页面大小为 50）。每一行代表一个版本；`questionnaire_group_id` 是解析为最新 `published` 版本的稳定组 ID。", "operationId": "list_questionnaires", "x-didit-sdk": { "resource": "questionnaires", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50 }, "description": "页面大小（每页问卷数量）。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0 }, "description": "返回第一个问卷前跳过的行数。" } ], "responses": { "200": { "description": "按 `created_at` 降序排列的一页问卷，封装在分页结构中。`results` 中的每一项均为 `QuestionnaireListItem`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "该应用的问卷版本总数。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的 URL，最后一页为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的 URL，第一页为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/QuestionnaireListItem" } } } }, "examples": { "One questionnaire": { "summary": "简单的双语问卷", "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "11111111-2222-3333-4444-555555555555", "title": "KYC Questionnaire", "description": "Additional verification questions", "languages": [ "en", "es" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "created_at": "2026-04-23T09:55:00Z", "updated_at": "2026-04-23T10:00:00Z", "question_types": [ "SHORT_TEXT", "MULTIPLE_CHOICE", "FILE_UPLOAD" ], "workflow_names": [], "questionnaire_group_id": "11111111-2222-3333-4444-555555555555", "version": 1, "status": "published", "published_at": "2026-04-23T10:00:00Z", "is_editable": false } ] } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制。请使用指数退避重试。" }, "500": { "description": "构建列表时发生意外服务器错误。可安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/questionnaires/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.questionnaires.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.questionnaires.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Questionnaires.ListAutoPaging(ctx, didit.QuestionnairesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.questionnaires().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "questionnaires->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.questionnaires.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Questionnaires.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "创建问卷", "description": "创建简单的线性问卷。按显示顺序发送 `form_elements`；分支和可重复组需要在控制台中配置。默认为 `published` v1。", "operationId": "create_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleQuestionnaireRequest" }, "examples": { "Simple": { "summary": "基础问卷", "value": { "title": "Customer Onboarding", "description": "Additional information needed for verification", "default_language": "en", "languages": [ "en" ], "is_active": true, "form_elements": [ { "id": "occupation", "element_type": "short_text", "label": { "en": "What is your occupation?" }, "is_required": true, "placeholder": { "en": "Software engineer" } }, { "id": "source_of_funds", "element_type": "multiple_choice", "label": { "en": "Source of funds" }, "is_required": true, "options": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } }, { "value": "investments", "label": { "en": "Investments" } }, { "value": "other", "label": { "en": "Other" } } ] } ] } } } } } }, "responses": { "201": { "description": "问卷已创建。响应包含 `questionnaire_id` — 请保存该 ID，以便在工作流或将来的更新/删除调用中引用此问卷。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireDetail" }, "examples": { "Created": { "value": { "questionnaire_id": "11111111-2222-3333-4444-555555555555", "title": "Customer Onboarding", "description": "Additional information needed for verification", "languages": [ "en" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "graph": { "start_node": "occupation", "nodes": { "occupation": { "element_type": "SHORT_TEXT", "is_required": true, "title": { "en": "What is your occupation?" }, "next": "source_of_funds" }, "source_of_funds": { "element_type": "MULTIPLE_CHOICE", "is_required": true, "title": { "en": "Source of funds" }, "choices": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } } ], "next": null } } }, "sections": [], "questionnaire_group_id": "11111111-2222-3333-4444-555555555555", "version": 1, "status": "published", "published_at": "2026-04-23T10:00:00Z", "is_editable": false } } } } } }, "400": { "description": "验证错误。常见原因：未知的 `element_type`、可翻译字段缺少 `languages` 之一的翻译、`languages` 缺少 `en`、`default_language` 不在 `languages` 中、选项缺少 `label`、包含 `branches`/`required_if`/`repeatable_config` 的问题（此 endpoint 不支持），或发送了原始 `graph` 而不是 `form_elements`。响应体是以字段名为键的 DRF 验证错误。", "content": { "application/json": { "examples": { "Graph not accepted": { "value": { "graph": "The v3 questionnaire API only accepts simple `form_elements`, not `graph`." } }, "Missing label": { "value": { "form_elements": [ { "label": [ "This field is required." ] } ] } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "415": { "description": "不支持的媒体类型。请设置 `Content-Type: application/json` 并发送 JSON 请求体。" }, "429": { "description": "超出速率限制。请使用指数退避重试。" }, "500": { "description": "创建问卷时发生意外服务器错误。可安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X POST 'https://verification.didit.me/v3/questionnaires/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"title\": \"Customer Onboarding\",\n \"default_language\": \"en\",\n \"languages\": [\"en\"],\n \"form_elements\": [\n {\n \"id\": \"occupation\",\n \"element_type\": \"short_text\",\n \"label\": {\"en\": \"What is your occupation?\"},\n \"is_required\": true\n }\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.questionnaires.create(\n title=\"Customer Onboarding\",\n description=\"Additional information needed for verification\",\n languages=[\"en\"],\n default_language=\"en\",\n is_active=True,\n form_elements=[{\n \"id\": \"occupation\",\n \"element_type\": \"short_text\",\n \"label\": {\"en\": \"What is your occupation?\"},\n \"placeholder\": {\"en\": \"Software engineer\"},\n \"is_required\": True,\n }, {\n \"id\": \"source_of_funds\",\n \"element_type\": \"multiple_choice\",\n \"label\": {\"en\": \"Source of funds\"},\n \"is_required\": True,\n \"options\": [{\n \"value\": \"employment\",\n \"label\": {\"en\": \"Employment\"},\n }, {\n \"value\": \"business\",\n \"label\": {\"en\": \"Business\"},\n }, {\n \"value\": \"investments\",\n \"label\": {\"en\": \"Investments\"},\n }, {\n \"value\": \"other\",\n \"label\": {\"en\": \"Other\"},\n }],\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.questionnaires.create({\n title: \"Customer Onboarding\",\n description: \"Additional information needed for verification\",\n languages: [\"en\"],\n default_language: \"en\",\n is_active: true,\n form_elements: [{\n id: \"occupation\",\n element_type: \"short_text\",\n label: { en: \"What is your occupation?\" },\n placeholder: { en: \"Software engineer\" },\n is_required: true,\n }, {\n id: \"source_of_funds\",\n element_type: \"multiple_choice\",\n label: { en: \"Source of funds\" },\n is_required: true,\n options: [{\n value: \"employment\",\n label: { en: \"Employment\" },\n }, {\n value: \"business\",\n label: { en: \"Business\" },\n }, {\n value: \"investments\",\n label: { en: \"Investments\" },\n }, {\n value: \"other\",\n label: { en: \"Other\" },\n }],\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Questionnaires.Create(ctx, didit.SimpleQuestionnaireRequest{\n\tTitle: \"Customer Onboarding\",\n\tDescription: didit.String(\"Additional information needed for verification\"),\n\tLanguages: []string{\"en\"},\n\tDefaultLanguage: didit.String(\"en\"),\n\tIsActive: didit.Bool(true),\n\tFormElements: []didit.SimpleQuestionnaireElement{{\n\t\tID: didit.String(\"occupation\"),\n\t\tElementType: \"short_text\",\n\t\tLabel: map[string]string{\"en\": \"What is your occupation?\"},\n\t\tPlaceholder: didit.Some(map[string]string{\"en\": \"Software engineer\"}),\n\t\tIsRequired: didit.Bool(true),\n\t}, {\n\t\tID: didit.String(\"source_of_funds\"),\n\t\tElementType: \"multiple_choice\",\n\t\tLabel: map[string]string{\"en\": \"Source of funds\"},\n\t\tIsRequired: didit.Bool(true),\n\t\tOptions: didit.Some([]didit.SimpleQuestionnaireElementOptions{{\n\t\t\tValue: didit.String(\"employment\"),\n\t\t\tLabel: map[string]string{\"en\": \"Employment\"},\n\t\t}, {\n\t\t\tValue: didit.String(\"business\"),\n\t\t\tLabel: map[string]string{\"en\": \"Business\"},\n\t\t}, {\n\t\t\tValue: didit.String(\"investments\"),\n\t\t\tLabel: map[string]string{\"en\": \"Investments\"},\n\t\t}, {\n\t\t\tValue: didit.String(\"other\"),\n\t\t\tLabel: map[string]string{\"en\": \"Other\"},\n\t\t}}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SimpleQuestionnaireElement;\nimport me.didit.types.SimpleQuestionnaireRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.questionnaires().create(SimpleQuestionnaireRequest.builder()\n .title(\"Customer Onboarding\")\n .description(\"Additional information needed for verification\")\n .languages(List.of(\"en\"))\n .defaultLanguage(\"en\")\n .isActive(true)\n .formElements(List.of(\n SimpleQuestionnaireElement.builder()\n .id(\"occupation\")\n .elementType(SimpleQuestionnaireElement.ElementType.of(\"short_text\"))\n .label(Map.of(\"en\", \"What is your occupation?\"))\n .placeholder(Map.of(\"en\", \"Software engineer\"))\n .isRequired(true)\n .build(),\n SimpleQuestionnaireElement.builder()\n .id(\"source_of_funds\")\n .elementType(SimpleQuestionnaireElement.ElementType.of(\"multiple_choice\"))\n .label(Map.of(\"en\", \"Source of funds\"))\n .isRequired(true)\n .options(List.of(\n SimpleQuestionnaireElement.Options.builder()\n .value(\"employment\")\n .label(Map.of(\"en\", \"Employment\"))\n .build(),\n SimpleQuestionnaireElement.Options.builder()\n .value(\"business\")\n .label(Map.of(\"en\", \"Business\"))\n .build(),\n SimpleQuestionnaireElement.Options.builder()\n .value(\"investments\")\n .label(Map.of(\"en\", \"Investments\"))\n .build(),\n SimpleQuestionnaireElement.Options.builder()\n .value(\"other\")\n .label(Map.of(\"en\", \"Other\"))\n .build()))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "questionnaires->create([\n 'title' => 'Customer Onboarding',\n 'description' => 'Additional information needed for verification',\n 'languages' => ['en'],\n 'default_language' => 'en',\n 'is_active' => true,\n 'form_elements' => [[\n 'id' => 'occupation',\n 'element_type' => 'short_text',\n 'label' => ['en' => 'What is your occupation?'],\n 'placeholder' => ['en' => 'Software engineer'],\n 'is_required' => true,\n ], [\n 'id' => 'source_of_funds',\n 'element_type' => 'multiple_choice',\n 'label' => ['en' => 'Source of funds'],\n 'is_required' => true,\n 'options' => [[\n 'value' => 'employment',\n 'label' => ['en' => 'Employment'],\n ], [\n 'value' => 'business',\n 'label' => ['en' => 'Business'],\n ], [\n 'value' => 'investments',\n 'label' => ['en' => 'Investments'],\n ], [\n 'value' => 'other',\n 'label' => ['en' => 'Other'],\n ]],\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.questionnaires.create(\n title: \"Customer Onboarding\",\n description: \"Additional information needed for verification\",\n languages: [\"en\"],\n default_language: \"en\",\n is_active: true,\n form_elements: [{\n id: \"occupation\",\n element_type: \"short_text\",\n label: { en: \"What is your occupation?\" },\n placeholder: { en: \"Software engineer\" },\n is_required: true,\n }, {\n id: \"source_of_funds\",\n element_type: \"multiple_choice\",\n label: { en: \"Source of funds\" },\n is_required: true,\n options: [{\n value: \"employment\",\n label: { en: \"Employment\" },\n }, {\n value: \"business\",\n label: { en: \"Business\" },\n }, {\n value: \"investments\",\n label: { en: \"Investments\" },\n }, {\n value: \"other\",\n label: { en: \"Other\" },\n }],\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Questionnaires.CreateAsync(new SimpleQuestionnaireRequest\n{\n Title = \"Customer Onboarding\",\n Description = \"Additional information needed for verification\",\n Languages = new string[] { \"en\" },\n DefaultLanguage = \"en\",\n IsActive = true,\n FormElements = new SimpleQuestionnaireElement[]\n {\n new()\n {\n Id = \"occupation\",\n ElementType = \"short_text\",\n Label = new Dictionary { [\"en\"] = \"What is your occupation?\" },\n Placeholder = new Dictionary { [\"en\"] = \"Software engineer\" },\n IsRequired = true,\n },\n new()\n {\n Id = \"source_of_funds\",\n ElementType = \"multiple_choice\",\n Label = new Dictionary { [\"en\"] = \"Source of funds\" },\n IsRequired = true,\n Options = new SimpleQuestionnaireElementOptions[]\n {\n new()\n {\n Value = \"employment\",\n Label = new Dictionary { [\"en\"] = \"Employment\" },\n },\n new()\n {\n Value = \"business\",\n Label = new Dictionary { [\"en\"] = \"Business\" },\n },\n new()\n {\n Value = \"investments\",\n Label = new Dictionary { [\"en\"] = \"Investments\" },\n },\n new()\n {\n Value = \"other\",\n Label = new Dictionary { [\"en\"] = \"Other\" },\n },\n },\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/questionnaires/{questionnaire_uuid}/": { "get": { "summary": "获取问卷", "description": "通过 `questionnaire_uuid` 获取某个版本的完整问卷详情：标题、`languages`、规范 `graph`、派生的 `sections` 以及版本元数据。", "operationId": "get_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "questionnaire_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "问卷每个版本对应的 UUID（列表 endpoint 返回的 `uuid` 值，在详情 endpoint 上也作为 `questionnaire_id` 返回）。" } ], "responses": { "200": { "description": "问卷完整详情，包括规范 `graph`、衍生的 `sections` 视图、版本元数据以及 `is_editable`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireDetail" }, "examples": { "Published questionnaire": { "value": { "questionnaire_id": "11111111-2222-3333-4444-555555555555", "title": "Customer Onboarding", "description": "Additional information needed for verification", "languages": [ "en" ], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "graph": { "start_node": "occupation", "nodes": { "occupation": { "element_type": "SHORT_TEXT", "is_required": true, "title": { "en": "What is your occupation?" }, "next": "source_of_funds" }, "source_of_funds": { "element_type": "MULTIPLE_CHOICE", "is_required": true, "title": { "en": "Source of funds" }, "choices": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } } ], "next": null } } }, "sections": [ { "title": {}, "description": {}, "items": [ { "uuid": "11111111-2222-3333-4444-666666666666", "value": "occupation", "element_type": "SHORT_TEXT", "is_required": true, "title": { "en": "What is your occupation?" } } ] } ], "questionnaire_group_id": "11111111-2222-3333-4444-555555555555", "version": 1, "status": "published", "published_at": "2026-04-23T10:00:00Z", "is_editable": false } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "已验证身份的应用中不存在具有此 `questionnaire_uuid` 的问卷。可能是 UUID 错误，或者它属于另一个应用，API 刻意不对这两种情况进行区分。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制。请使用指数退避重试。" }, "500": { "description": "意外服务器错误。可安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X GET 'https://verification.didit.me/v3/questionnaires/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.questionnaires.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.questionnaires.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Questionnaires.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.questionnaires().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "questionnaires->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.questionnaires.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Questionnaires.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "更新问卷", "description": "更新问卷。版本控制取决于您发送的 `status` 字段以及该版本的当前状态：(1) **已发布**版本未传 `status` → 已发布版本就地更新（相同的 `questionnaire_id`，相同的 `version`）；(2) **草稿**未传 `status` → 草稿更新并立即发布；(3) **已发布**版本传入 `status: \"published\"` → 在同一个 `questionnaire_group_id` 下创建并返回一个新的已发布版本（新的 `questionnaire_id`，`version` + 1），并删除该分组中现有的任何草稿；(4) `status: \"draft\"` 将草稿保持为草稿（自动保存），但若在已发布版本上操作则会被拒绝并返回 400（`\"Cannot revert a published version to draft.\"`）。", "operationId": "update_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "questionnaire_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "要更新的问卷版本 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimpleQuestionnaireUpdateRequest" }, "examples": { "Rename": { "summary": "重命名问卷", "value": { "title": "Updated Customer Onboarding" } }, "Replace questions": { "summary": "替换完整的线性问题列表", "value": { "form_elements": [ { "id": "occupation", "element_type": "short_text", "label": { "en": "What is your occupation?" }, "is_required": true }, { "id": "source_of_funds", "element_type": "multiple_choice", "label": { "en": "Source of funds" }, "options": [ { "value": "employment", "label": { "en": "Employment" } }, { "value": "business", "label": { "en": "Business" } } ] } ] } } } } } }, "responses": { "200": { "description": "问卷已更新。body 是生成版本的最新状态 — 就地更新的版本，或者当您在已发布行上发送 `status: \"published\"` 时新创建的已发布版本（在该情况下，`questionnaire_id` 和 `version` 与您打补丁的版本不同）。响应中的 `questionnaire_id` 是每个版本的 UUID；如果您需要稳定的组标识符，请使用 `questionnaire_group_id`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuestionnaireDetail" } } } }, "400": { "description": "验证错误 — 未知的 `element_type`、缺少翻译、不支持的分支/条件字段、`languages` 中缺少 `en`、`default_language` 不在 `languages` 中、选项缺少标签、发送了原始 `graph`，或在已发布版本上设置 `status: \"draft\"`（`\"Cannot revert a published version to draft.\"`）。响应体是以字段名为键的 DRF 验证错误。" }, "403": { "description": "API 密钥缺失或无效。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "已验证身份的应用中不存在具有此 `questionnaire_uuid` 的问卷。" }, "415": { "description": "不支持的媒体类型。请设置 `Content-Type: application/json`。" }, "429": { "description": "超出速率限制。请使用指数退避重试。" }, "500": { "description": "意外服务器错误。可安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X PATCH 'https://verification.didit.me/v3/questionnaires/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Updated Customer Onboarding\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.questionnaires.update(\n \"11111111-2222-3333-4444-555555555555\",\n title=\"Updated Customer Onboarding\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.questionnaires.update(\"11111111-2222-3333-4444-555555555555\", {\n title: \"Updated Customer Onboarding\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Questionnaires.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SimpleQuestionnaireUpdateRequest{\n\tTitle: didit.String(\"Updated Customer Onboarding\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SimpleQuestionnaireUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.questionnaires().update(\"11111111-2222-3333-4444-555555555555\", SimpleQuestionnaireUpdateRequest.builder()\n .title(\"Updated Customer Onboarding\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "questionnaires->update('11111111-2222-3333-4444-555555555555', [\n 'title' => 'Updated Customer Onboarding',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.questionnaires.update(\n \"11111111-2222-3333-4444-555555555555\",\n title: \"Updated Customer Onboarding\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Questionnaires.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new SimpleQuestionnaireUpdateRequest\n{\n Title = \"Updated Customer Onboarding\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "删除问卷", "description": "永久删除单个问卷版本（无法撤销）。与此版本关联的已存储问卷响应将随之一并删除，引用它的会话将失去该关联；同一分组中的其他版本不会被删除。引用它的工作流将继续运行，但问卷步骤将无法再加载它。", "operationId": "delete_questionnaire", "x-didit-sdk": { "resource": "questionnaires", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Questionnaires" ], "parameters": [ { "name": "questionnaire_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "要删除的问卷版本 UUID。" } ], "responses": { "204": { "description": "问卷已删除。响应正文为空。" }, "403": { "description": "API 密钥缺失或无效。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "已验证身份的应用中不存在具有此 `questionnaire_uuid` 的问卷。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制。请使用指数退避重试。" }, "500": { "description": "意外服务器错误。可安全重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl -X DELETE 'https://verification.didit.me/v3/questionnaires/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.questionnaires.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.questionnaires.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Questionnaires.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.questionnaires().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "questionnaires->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.questionnaires.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Questionnaires.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/users/": { "get": { "summary": "列出用户", "description": "列出 Didit 根据共享相同 `vendor_data`（自由格式字符串，非 UUID）的 KYC 会话汇编的[用户](/entities/users)，以及通过 API 创建的用户。支持分页，按 `last_session_at` 降序排列。该 endpoint 不支持过滤或搜索参数，请获取分页并在客户端进行过滤。", "operationId": "list_users", "x-didit-sdk": { "resource": "users", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "页面大小。省略时默认为 50。虽无强制上限，但为降低延迟建议保持较小的页面大小。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "要返回的第一条记录的从零开始的偏移量。建议跟随上一页的 `next` URL，而不是手动计算。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/users/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.users.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.users.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Users.ListAutoPaging(ctx, didit.UsersListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.users().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "users->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.users.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Users.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页的用户列表，包含验证状态、会话计数和功能明细。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "匹配行数，出于性能考虑，不超过 100 时为精确值，超过 100 时上限为 100。请勿使用它来检测最后一页；应依靠 `next` 为 `null` 进行判断。" }, "next": { "type": "string", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/UserListItem" } } } }, "examples": { "Example": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Michael Doe", "date_of_birth": "1990-05-15", "effective_name": "John Michael Doe", "status": "ACTIVE", "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2025-06-01T08:00:00Z" }, { "didit_internal_id": "6ed99d53-e8f5-4cf8-9ac1-4a506cb40f6b", "vendor_data": null, "display_name": "Jane S.", "full_name": "Jane Elizabeth Smith", "date_of_birth": "1985-11-22", "effective_name": "Jane S.", "status": "FLAGGED", "portrait_image_url": null, "session_count": 1, "approved_count": 0, "declined_count": 0, "in_review_count": 1, "issuing_states": [], "approved_emails": [], "approved_phones": [], "features": { "ID_VERIFICATION": "In Review" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "In Review" } ], "last_session_at": "2025-06-20T14:00:00Z", "last_activity_at": "2025-06-20T14:05:00Z", "first_session_at": "2025-06-20T14:00:00Z", "tags": [], "created_at": "2025-06-20T14:00:00Z" } ] } } } } } }, "401": { "description": "未提供凭证。对 `/v3/users/*` 路径的请求如果不包含 `x-api-key` 请求头（或 `Authorization: Bearer` token），将在到达 API 之前被身份验证中间件拒绝。", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "该密钥无法列出此应用的用户。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/users/{vendor_data}/": { "get": { "summary": "获取用户", "description": "通过 `vendor_data` 获取单个[用户](/entities/users)（精确匹配）。在列表视图的基础上补充 `metadata`、`comments` 和 `updated_at`，并将 `tags` 切换为详细的标签链接格式。", "operationId": "get_user", "x-didit-sdk": { "resource": "users", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "您对该用户的唯一标识符，即自由格式字符串（非 UUID）。该值与您在首次引入该用户创建会话时作为 `vendor_data` 传入的值相同，按发送的内容精确匹配。", "example": "user-abc-123" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/users/user-abc-123/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.retrieve(\n \"user-abc-123\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.retrieve(\"user-abc-123\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Retrieve(ctx, \"user-abc-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().retrieve(\"user-abc-123\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->retrieve('user-abc-123');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.retrieve(\"user-abc-123\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.RetrieveAsync(\"user-abc-123\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "完整的用户详情，包括元数据、备注/活动日志以及汇总的会话数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetailItem" }, "examples": { "Active user": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Michael Doe", "date_of_birth": "1990-05-15", "effective_name": "John Michael Doe", "status": "ACTIVE", "metadata": { "tier": "premium", "source": "website" }, "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "tag": { "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "VIP", "color": "#2567FF", "description": null, "source": "custom", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-05-01T09:00:00Z" }, "added_by_email": "analyst@acme.com", "added_by_name": "Jane Analyst", "created_at": "2025-06-02T11:00:00Z" } ], "comments": [ { "uuid": "c1111111-2222-4333-8444-555555555555", "comment_type": "STATUS_CHANGED", "comment": null, "actor_email": "analyst@acme.com", "actor_name": "Jane Analyst", "previous_status": "FLAGGED", "new_status": "ACTIVE", "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "mentioned_emails": [], "created_at": "2025-06-01T10:30:00Z" } ], "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-15T10:30:00Z" } } } } } }, "401": { "description": "未提供凭证。对 `/v3/users/*` 路径的请求如果不包含 `x-api-key` 请求头（或 `Authorization: Bearer` token），将在到达 API 之前被身份验证中间件拒绝。", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "无效或已撤销的 API 密钥，或者该密钥无法读取此应用的用户。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "此应用中不存在具有所提供 `vendor_data` 的用户。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新用户", "description": "用户的部分更新：`display_name`、`full_name`、`date_of_birth`、`status`、`metadata`、`approved_emails`/`approved_phones`/`issuing_states`。`metadata` 将完全替换。在此处更改 `status` 的效果类似于[更新用户状态](#patch-/v3/users/-vendor_data-/update-status/)：它会记录一条带有可选 `reason` 的 `STATUS_CHANGED` 活动记录，且 `BLOCKED` 会将 `vendor_data` 添加到系统黑名单（移出 `BLOCKED` 则会移除该条目）。对 `display_name`、`full_name`、`date_of_birth` 或 `metadata` 的更改会记录为 `PROFILE_UPDATED` 活动记录。", "operationId": "update_user", "x-didit-sdk": { "resource": "users", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "您对该用户的唯一标识符（自由格式字符串，非 UUID）。", "example": "user-abc-123" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"display_name\": \"Jane S.\", \"status\": \"FLAGGED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.update(\n \"user-abc-123\",\n display_name=\"Jane S.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.update(\"user-abc-123\", {\n display_name: \"Jane S.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Update(ctx, \"user-abc-123\", didit.UsersUpdateParams{\n\tDisplayName: didit.String(\"Jane S.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.UsersUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().update(\"user-abc-123\", UsersUpdateParams.builder()\n .displayName(\"Jane S.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->update('user-abc-123', [\n 'display_name' => 'Jane S.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.update(\n \"user-abc-123\",\n display_name: \"Jane S.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.UpdateAsync(\"user-abc-123\", new UsersUpdateParams\n{\n DisplayName = \"Jane S.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "用户已更新。返回完整的已更新用户记录（格式与获取用户相同）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetailItem" }, "examples": { "Updated": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": "Jane S.", "full_name": "Jane Elizabeth Smith", "date_of_birth": "1985-11-22", "effective_name": "Jane S.", "status": "FLAGGED", "metadata": { "tier": "premium" }, "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "tag": { "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "VIP", "color": "#2567FF", "description": null, "source": "custom", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-05-01T09:00:00Z" }, "added_by_email": "analyst@acme.com", "added_by_name": "Jane Analyst", "created_at": "2025-06-02T11:00:00Z" } ], "comments": [], "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-15T10:30:00Z" } } } } } }, "400": { "description": "无效的请求体：通常是未知的 `status`，或 `date_of_birth` 不符合 `YYYY-MM-DD` 格式。", "content": { "application/json": { "examples": { "Bad status": { "value": { "status": [ "\"INVALID\" is not a valid choice." ] } }, "Bad date_of_birth": { "value": { "date_of_birth": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "401": { "description": "未提供凭证。对 `/v3/users/*` 路径的请求如果不包含 `x-api-key` 请求头（或 `Authorization: Bearer` token），将在到达 API 之前被身份验证中间件拒绝。", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "该密钥无法更新此应用的用户。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "此应用中不存在具有所提供 `vendor_data` 的用户。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "full_name": { "type": "string", "nullable": true, "maxLength": 512, "description": "用户的姓名" }, "display_name": { "type": "string", "nullable": true, "description": "该用户的自定义显示名称" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "YYYY-MM-DD 格式的出生日期" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "用户生命周期状态。状态变更会记录为 `STATUS_CHANGED` 活动，且 `BLOCKED` 会将 `vendor_data` 添加到系统黑名单中（移出 `BLOCKED` 会移除该条目）。" }, "metadata": { "type": "object", "nullable": true, "description": "附加到用户的任意 JSON 对象。更新时将**完全替换**现有元数据；如果仅想添加键，请在客户端进行合并。" }, "approved_emails": { "type": "array", "items": { "type": "string" }, "description": "该用户的已验证邮箱地址，例如 `[\"john@example.com\"]`。完全替换已存储的列表。" }, "approved_phones": { "type": "array", "items": { "type": "string" }, "description": "该用户的已验证电话号码。完全替换已存储的列表。" }, "issuing_states": { "type": "array", "items": { "type": "string" }, "description": "签发国家/地区（ISO 3166-1 alpha-3），例如 `[\"USA\"]`。完全替换已存储的列表。" }, "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "状态变更的原因。仅在状态实际变更时，记录在用户活动的状态变更条目（`comments[].comment`，以及 Business Console 中的 **Activity**）上。Webhook 不包含此项。" } } }, "examples": { "Rename": { "summary": "设置显示名称", "value": { "display_name": "Jane S." } }, "Override status": { "summary": "标记用户以待审核", "value": { "status": "FLAGGED" } }, "Add metadata": { "summary": "替换元数据 JSON", "value": { "metadata": { "tier": "premium", "risk_level": "low" } } }, "Fix extracted DOB": { "summary": "提取的个人资料字段正确", "value": { "full_name": "Jane Elizabeth Smith", "date_of_birth": "1985-11-22" } }, "Flag with reason": { "summary": "标记用户并记录原因", "value": { "status": "FLAGGED", "reason": "Address does not match the billing country" } } } } } } } }, "/v3/users/{vendor_data}/generate-pdf/": { "get": { "summary": "下载完整的用户历史记录 PDF 报告", "description": "渲染并下载一份符合合规要求的 PDF，其中包含通过 `vendor_data` 标识的用户的完整验证历史记录。这与 Console 中通过 **User detail → Actions → Download PDF** 生成的文件相同，因此定期的合规导出不再需要专人在 Console 中手动点击。\n\n**报告包含的内容。** 包含个人资料摘要的封面（姓名、出生日期、签发国家/地区、已通过的邮箱和电话）、每项功能的最新状态、会话计数器以及所包含会话的索引，随后按时间顺序（从最早开始）附上每个所包含会话的标准报告。每个会话报告与针对该会话调用 `GET /v3/session/{sessionId}/generate-pdf/` 返回的文件相同。\n\n**符合条件的会话。** 仅包含处于 `Approved`、`Declined`、`In Review` 或 `Kyc Expired` 状态的用户验证（KYC）会话；任何处于其他状态的会话都会被跳过。如果用户没有任何处于上述状态之一的会话，该 endpoint 将返回 `403`（见下文）。\n\n**上限。** 报告最多包含**最近 20 个**可报告会话。当用户拥有的会话超过此数量时，将包含最新的 20 个，并在封面上说明遗漏了多少较早的会话。使用 `GET /v3/sessions/?vendor_data=…` 获取完整的 JSON 列表。\n\n**品牌定制。** 如果您的应用启用了白标定制，封面和每个会话报告都将使用您的 Logo 和隐私政策 URL 进行渲染；否则将带有 Didit 品牌标识。报告以英文渲染，没有语言参数。\n\n**无缓存。** 每次调用都会根据当前数据重新渲染 PDF，因此在人工审核后生成的报告会反映审核员的决策。针对同一用户的两次调用可能会生成字节不同的文件。如果您需要不可变的副本，请对下载的文件进行归档。\n\n**延迟。** 渲染过程是同步的，并且会下载所包含每个会话的所有已存储图片，因此对于包含较多富媒体会话的用户，可能需要数十秒。建议设置宽松的客户端读取超时时间（推荐 120 秒）并将响应体流式传输到磁盘。生成过程受服务端时间预算限制，而不会一直运行到客户端放弃：如果达到该预算，响应仍然是包含最近会话的有效 PDF，且封面会说明省略了多少次会话。\n\n**作用域。** 用户在拥有该 API 密钥的应用内解析。密钥绝不能导出另一个应用的用户；对该密钥而言，该用户不存在，且该 endpoint 将返回 `404`。\n\n**末尾斜杠。** 规范路由以末尾斜杠（`…/generate-pdf/`）结尾。不带斜杠的请求将直接以相同响应提供服务；不存在 `301` 重定向，因此客户端无需跟随重定向，`curl` 也不需要 `-L`。请按照示例使用带斜杠的 URL。", "operationId": "get_user_generate_pdf", "x-didit-sdk": { "resource": "users", "method": "generate_pdf", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "您对该用户的唯一标识符，为自由格式字符串（非 UUID）。该值与您在创建该用户会话时作为 `vendor_data` 传入的值相同，按发送的内容精确匹配。请对其进行 URL 编码；包含 `/` 的值无法由此路由寻址。", "example": "user-abc-123" } ], "responses": { "200": { "description": "渲染生成的 PDF 文档，直接以二进制 `application/pdf` 形式返回，没有 JSON 包装，也没有下载 URL 重定向。正文以 `%PDF` 魔数开头。可将其保存为 `.pdf` 文件或直接流式传输给您的调用方。", "headers": { "Content-Disposition": { "description": "`attachment; filename=user_{didit_internal_id}.pdf`：文件以用户稳定的 Didit 标识符（`GET /v3/users/{vendor_data}/` 上的 `didit_internal_id`）命名，而非以 `vendor_data` 命名。", "schema": { "type": "string", "example": "attachment; filename=user_f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418.pdf" } }, "Content-Length": { "description": "PDF 的总大小（以字节为单位）；正文未分块。", "schema": { "type": "integer", "example": 148213 } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "未提供凭证。对 `/v3/users/*` 路径的请求如果不包含 `x-api-key` 请求头（或 `Authorization: Bearer` token），将在到达 API 之前被身份验证中间件拒绝。", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "授权或资格失败。可通过 `detail` 字符串区分这两者：\n\n- `\"You do not have permission to perform this action.\"` — API 密钥无效或已撤销，或者请求携带了控制台用户 token 而非应用 API 密钥。\n- `\"This user has no sessions in review, declined, approved or kyc expired to report.\"` — 该用户存在于您的应用中，但其会话均未处于可生成报告的状态（例如所有会话仍为 `In Progress`，或者该用户是通过 `POST /v3/users/create/` 创建且从未进行过验证）。请等待 `status.updated` Webhook 触发后再请求报告。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "This user has no sessions in review, declined, approved or kyc expired to report." } } }, "examples": { "Invalid credentials": { "summary": "已撤销或无效的 API 密钥，或 Console 用户 token", "value": { "detail": "You do not have permission to perform this action." } }, "No reportable sessions": { "summary": "用户存在，但没有已通过 / 已拒绝 / 审核中 / KYC 已过期会话", "value": { "detail": "This user has no sessions in review, declined, approved or kyc expired to report." } } } } } }, "404": { "description": "该 API 密钥关联的应用中不存在具有所提供 `vendor_data` 的用户。其他应用的用户对该密钥不可见，并同样返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "User not found." } } }, "examples": { "Unknown user": { "summary": "vendor_data 与该应用的任何用户均不匹配", "value": { "detail": "User not found." } } } } } }, "429": { "description": "超出速率限制。除全局 600 次/分钟的 GET 限制外，PDF 生成还具有**每个凭证每分钟 50 次请求**的专属限制（API 密钥、Bearer token，或未认证时的源 IP），由本 endpoint 与 `GET /v3/session/{sessionId}/generate-pdf/` 共享。请等待 `Retry-After` 秒（也会反映在 `X-RateLimit-*` 响应头中），然后重试。报告不会在服务端缓存，因此请下载每份报告一次并保存文件，而不是重复获取。", "headers": { "Retry-After": { "description": "重试请求前需等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "当前时间窗口内允许的最大 PDF 生成次数（50）。", "schema": { "type": "integer", "example": 50 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间戳（秒）。", "schema": { "type": "integer", "example": 1750000000 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "超出速率限制的便于人类阅读的说明。", "example": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } }, "examples": { "Throttled": { "summary": "同一凭证在一分钟内生成的 PDF 超过 50 份", "value": { "detail": "Session PDF generation rate limit exceeded. You can make up to 50 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --fail \\\n 'https://verification.didit.me/v3/users/user-abc-123/generate-pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output user-history.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.users.generate_pdf(\n \"user-abc-123\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.users.generatePdf(\"user-abc-123\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Users.GeneratePDF(ctx, \"user-abc-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.users().generatePdf(\"user-abc-123\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "users->generatePdf('user-abc-123');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.users.generate_pdf(\"user-abc-123\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Users.GeneratePdfAsync(\"user-abc-123\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/users/delete/": { "post": { "summary": "批量删除用户", "description": "**永久删除**用户：用户记录将被永久移除。对于日常阻止操作，建议使用 [Update User Status](#patch-/v3/users/-vendor_data-/update-status/) 并传入 `BLOCKED`。可以通过 `vendor_data_list`、`didit_internal_id_list` 或两者同时使用来选择用户；也可以传递 `delete_all: true`。此 endpoint 绝不会通过过滤器缩小 `delete_all` 的范围。Console 的人员过滤器将被拒绝并返回 `400`（参见 `400` 响应），以避免缩小的意图变成全面清除。两个例外情况：`filter_has_approved_sessions` 和 `filter_has_declined_sessions` 不会被拒绝也不会被应用，因此在传入 `delete_all: true` 时它们仍会删除所有用户；请勿发送它们。\n\n**生物特征模板：**除非您将 `retain_face_embeddings` 设置为 `true`，否则在删除会话后为这些用户保留的所有无图像生物特征模板（参见 `/v3/biometric-templates/`）都会在用户被删除前清除，从而使该人员不再匹配重复检测和人脸搜索。若传入 `retain_face_embeddings: true` 和 `face_retention_days`，您可以选择为每人保留一份无图像的生物特征模板达相应天数，而该人员的其他信息均不保留。如果由于生物特征存储库不可用而导致模板无法清除，该调用将返回 `503`，请求中的任何用户都不会被删除，重试请求即可完成该操作。\n\n**已归档的监管报告：**如果选定的数据包含在已定稿的监管报告中，整个请求将被拒绝并返回 `409`，且不会删除任何内容。响应体使用 `code: in_filed_report`，并通过 `uuid`、`report_number`、`report_type` 和 `case_uuid` 列出每份报告。请先删除这些报告，然后重试请求。", "operationId": "batch_delete_users", "x-didit-sdk": { "resource": "users", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "提供 `vendor_data_list`、`didit_internal_id_list` 或 `delete_all: true`。两个列表可以组合使用，相互之间为“或”（OR）逻辑。当 `delete_all` 为 `true` 时，其优先级最高，两个列表都会被忽略。", "properties": { "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "您要删除的自身标识符，完全按照发送的内容进行匹配。" }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "要删除的 Didit 内部用户 ID，即创建和获取 endpoint 返回的 `didit_internal_id`。" }, "delete_all": { "type": "boolean", "default": false, "description": "若为 `true`，则删除该应用中的所有用户。" }, "retain_face_embeddings": { "type": "boolean", "default": false, "description": "您的明确选择，用于为每个被删除的人员保留一份无图像的生物特征模板以用于重复检测，保留 `face_retention_days` 天。该人员的所有其他信息都将被删除。省略此参数或发送 `false`，将连同用户一起删除模板。当为 `true` 时，`face_retention_days` 为必填项。" }, "face_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "当 `retain_face_embeddings` 为 `true` 时保留无图像生物特征模板的天数。与该参数配合使用时为必填项；未配置该参数时将被拒绝并在 `face_retention_days` 上返回 `400`。", "example": 365 } } }, "examples": { "Specific users": { "summary": "按 vendor_data 删除用户", "value": { "vendor_data_list": [ "user-123", "user-456" ] } }, "By Didit internal ID": { "summary": "按 didit_internal_id 删除用户", "value": { "didit_internal_id_list": [ "3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11" ] } }, "All users": { "summary": "清空此应用中的所有用户", "value": { "delete_all": true } }, "Keep face templates": { "summary": "删除用户并保留匿名人脸模板 365 天", "value": { "vendor_data_list": [ "user-123" ], "retain_face_embeddings": true, "face_retention_days": 365 } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/users/delete/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data_list\": [\"user-123\", \"user-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.batch_delete(\n vendor_data_list=[\"user-123\", \"user-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.batchDelete({\n vendor_data_list: [\"user-123\", \"user-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.BatchDelete(ctx, didit.UsersBatchDeleteParams{\n\tVendorDataList: didit.Some([]string{\"user-123\", \"user-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.UsersBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().batchDelete(UsersBatchDeleteParams.builder()\n .vendorDataList(List.of(\"user-123\", \"user-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->batchDelete([\n 'vendor_data_list' => ['user-123', 'user-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.batch_delete(vendor_data_list: [\"user-123\", \"user-456\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.BatchDeleteAsync(new UsersBatchDeleteParams\n{\n VendorDataList = new string[] { \"user-123\", \"user-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "用户已删除。返回实际删除的用户数量。", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer", "description": "已删除的用户数量（不包括未匹配到任何内容的 vendor_data 值）。" } } }, "examples": { "Deleted some": { "value": { "deleted": 2 } }, "Nothing matched": { "value": { "deleted": 0 } } } } } }, "400": { "description": "验证错误；未删除任何内容。错误以字段名为键。若未提供选择器（两个列表均未提供且 `delete_all` 不为 `true`），响应体为 `{\"vendor_data_list\": [\"This field is required unless delete_all is true.\"]}`；空列表会被拒绝并在其自身键下返回 `\"This list may not be empty.\"`。仅限控制台的过滤器（`filter_search`、`filter_status`、`filter_country`、`filter_date_from`、`filter_date_to`、`filter_tag`、`filter_latest_verification_status`、`filter_risk`、`filter_has_sessions`、`filter_has_open_alerts`、`filter_aml_monitoring`、`filter_can_sign_in`、`filter_auth_status`、`filter_auth_method` 或 `filter_auth_mfa_enabled`）只要包含值（即使为 `false`）就会被拒绝，并返回以各对应字段为键的对象。任何其他未知的 `filter_*` 键都会被拒绝并返回 `\"Unknown filter.\"`。", "content": { "application/json": { "examples": { "Missing selector": { "summary": "既未提供 list 也未提供 delete_all", "value": { "vendor_data_list": [ "This field is required unless delete_all is true." ] } }, "Console-only filter": { "value": { "filter_has_sessions": "This filter is Console-only and is not supported by this endpoint." } } } } } }, "401": { "description": "未提供凭证。对 `/v3/users/*` 路径的请求如果不包含 `x-api-key` 请求头（或 `Authorization: Bearer` token），将在到达 API 之前被身份验证中间件拒绝。", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "无效或已撤销的 API 密钥，或者该密钥无法删除此应用的用户。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } }, "503": { "description": "在保留或清除生物特征模板时，生物特征存储库不可用。未删除任何内容；请重试相同的请求。重试具有幂等性，并最终收敛至单个模板。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Retryable": { "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } }, "409": { "description": "未删除任何内容。`code` 说明了原因：所选内容包含已定稿监管报告中的人员时为 `in_filed_report`，另一个请求仍在删除所选人员之一时为 `subject_deletion_in_progress`。请在该删除完成后重试请求。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InFiledReportError" }, { "$ref": "#/components/schemas/SubjectDeletionInProgressError" } ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/sessions/delete/": { "post": { "summary": "按 session_number 批量删除 KYC 会话", "description": "通过数字形式的 `session_number` 批量删除用户验证（KYC）会话，或通过 `delete_all: true` 删除您应用中的所有 KYC 会话。\n\n`session_number` 是控制台会话列表中显示的易于阅读的递增计数器，并在创建会话和决策 endpoint 中作为 `session_number` 返回；它**不是** `session_id` UUID。如需通过 UUID 删除会话，或删除企业验证（KYB）会话（本 endpoint 绝不涉及此类会话），请改用 `DELETE /v3/session/{sessionId}/delete/`。\n\n**单次请求最多同步删除 20 个会话，超过则作为后台任务运行。** 无论会话是通过 `session_numbers` 还是 `delete_all` 选定，均由匹配的会话数量决定处理方式：\n- 最多 20 个匹配会话：在返回响应前完成删除，响应状态码为 `200`，并在 `results[]` 中为每个会话包含一个条目。\n- 超过 20 个：响应状态码为 `202` 并返回一个删除任务，会话将在后台删除。请轮询 `GET /v3/sessions/delete/{job_id}/`，直至 `status` 为 `COMPLETED` 或 `FAILED`。任务仅报告每种结果的数量统计，绝不会报告具体删除了哪些会话。`delete_all` 任务仅删除在请求发起前创建的会话；任务运行期间启动的会话不会被删除。\n\n每个被删除的会话均与单会话删除 endpoint 享受完全相同的处理方式：会话本身、其中包含的每次验证尝试、其决策和提取的数据、其相关功能记录（身份证件验证、人脸、活体检测、人脸比对等）以及所有存储的文件均会被删除，它将从所有读取 endpoint 中消失，并且之前签发的多媒体 URL 将停止解析。仍处于队列中等待投递给已删除会话的 Webhook 投递及其重试将被丢弃；已经投递的 Webhook 不受影响。黑名单条目**不会**被移除，已消耗的额度**不会**退还，上级用户实体**不会**被删除（如需删除请使用 `POST /v3/users/delete/`）；删除操作不会触发任何 Webhook。删除为永久性操作且不可逆。\n\n**选择语义：**\n- 使用 `delete_all: true` 时，您可以使用 `GET /v3/sessions/` 的过滤器来缩小选择范围，每个过滤器前缀均为 `filter_`（例如 `filter_status`、`filter_workflow_id`、`filter_date_from`）。在获取会话列表中支持多个值的过滤器（`status`、`workflow_id`、`country`、`region`、`document_type`、`document_name`、`session_type`、`warning`、`organization_name`）可接收逗号分隔的字符串或数组；其余过滤器接收单一值。空值将被忽略。过滤器仅在与 `delete_all` 一起使用时生效，删除任务也会应用相同的过滤器。\n- 未知的 `filter_*` 键或无法读取的过滤器值会在删除任何内容前拒绝整个请求并返回 `400`，因此拼写错误的过滤器绝不会导致删除范围扩大到所有会话。\n- `session_numbers` 中与您应用内有效 KYC 会话不匹配的条目（未知编号、已删除的会话或属于其他应用的会话）将被**静默跳过**：它们不会出现在 `results` 中，也不会计入任务的 `total`。\n- 验证失败（非数字条目、空列表、未提供 `session_numbers` 也未提供 `delete_all`，或者应用无法满足的模板保留设置）将拒绝**整个请求**并返回 `400`，且不会删除任何内容。\n- 会话按组进行删除。如果某个组无法删除（例如存储服务不可用），该组中的每个会话都将被报告为 `face_retention_outcome: failed_retryable` 并保持原样；其他组不受影响。针对这些会话重新发起请求即可。后台任务会自动重试此类分组。\n- 列表长度没有明确的文档上限；下文所述的共享写入速率限制是实际的约束边界。\n\n**人脸生物特征数据：** 可选字段 `retain_face_embeddings`、`face_retention_days`、`face_retention_deadline`、`deletion_instruction` 和 `instruction_id` 的含义与 `DELETE /v3/session/{sessionId}/delete/` 相同，并适用于每个匹配的会话。每个结果都会报告自己的 `face_retention_outcome`。\n\n**响应：** 对于最多 20 个匹配会话返回包含 `results[]` 的 `200 OK`，超过 20 个则返回包含删除任务的 `202 Accepted`。除 `face_retention_outcome: failed_retryable`（表示会话未被删除，应重试）外，每个结果均确认已完成删除。该 endpoint 的早期版本曾返回 `204 No Content`；请更新依赖 `204` 断言的客户端。\n\n**幂等性：** 重复相同的请求不会删除更多内容：不再匹配会话的编号将被跳过。\n\n**`delete_all: true`（破坏性操作）：** 删除应用中**所有**剩余的 KYC 会话；设置此项时将忽略 `session_numbers`。该操作没有确认步骤，且无法撤销。\n\n**认证：** 在 `x-api-key` 请求头中传入 API 密钥。缺少凭据或凭据无效将返回 `403`（`{\"detail\": \"You do not have permission to perform this action.\"}`）；此 API 绝不会返回 `401`。\n\n**速率限制：** 每个 API 密钥在所有 POST/PATCH/DELETE endpoint 间共享 300 次请求/分钟的写入预算；超出限制将返回 `429`。\n\n本 endpoint 仅接受 API 密钥。Business Console 用户 Bearer token 将被拒绝并返回 `403`（与单会话删除不同，后者两者均支持）。\n\n**已提交的监管报告：** 如果选定的数据存在于已定稿的监管报告中，整个请求将被拒绝并返回 `409`，且不会删除任何内容。响应体使用 `code: in_filed_report`，并通过 `uuid`、`report_number`、`report_type` 和 `case_uuid` 指明各个报告。请先删除这些报告，然后重试请求。", "operationId": "batch_delete_sessions", "x-didit-sdk": { "resource": "sessions", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "session_numbers": { "type": "array", "description": "要删除的 KYC 会话的纯数字字符串格式数字 `session_number` 值（也接受 JSON 数字并会进行强制转换）。除非 `delete_all` 为 `true`，否则为必填项；空列表将返回 `400`。任何非数字条目都会导致整个请求以 `400` 被拒绝（除非 `delete_all` 为 `true`，此时将跳过校验并忽略这些条目）。与您应用中的活动会话不匹配的数字将被直接忽略。", "items": { "type": "string", "pattern": "^[0-9]+$", "example": "1001" }, "minItems": 1, "example": [ "1001", "1002", "1003" ] }, "delete_all": { "type": "boolean", "description": "为 `true` 时，调用应用中所有剩余的 KYC 会话都将被删除，并且 `session_numbers` 将被忽略，除非您使用 `filter_*` 键缩小选择范围。匹配超过 20 个会话时将作为删除任务（`202`）运行，仅涵盖请求前创建的会话。默认为 `false`。不可逆；没有确认步骤。", "default": false, "example": false }, "retain_face_embeddings": { "type": "boolean", "nullable": true, "description": "针对本次删除覆盖应用的 `face_retention_policy`。为 `true` 时，在会话删除后保留一个锚定到该会话用户的无图像人脸生物特征模板；为 `false` 时，随会话一同删除人脸特征向量；省略或设为 `null` 则遵循应用策略。对于 KYB 会话以及无人脸特征向量的会话，此项将被忽略。", "example": true }, "face_retention_days": { "type": "integer", "minimum": 1, "maximum": 3650, "description": "保留模板的有限保留时长（以天为单位）。除非应用已设置 `face_retention_days`，否则在保留模板时必填。模板的 `expires_at` 为此保留时长、应用的通用数据保留期和 `face_retention_deadline` 中的最早者。", "example": 365 }, "face_retention_deadline": { "type": "string", "format": "date-time", "description": "保留模板的可选硬性到期时间。必须是将来的时间。", "example": "2027-08-28T00:00:00Z" }, "deletion_instruction": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ], "default": "operational_session_delete", "description": "您发出的指令类别。`operational_session_delete` 会删除会话，并且仅在策略或 `retain_face_embeddings` 要求时才保留模板。`privacy_erasure` 会在删除会话之前清除锚定到该会话用户的每个已保留生物特征模板，此操作不能被应用策略覆盖，也不能与 `retain_face_embeddings: true` 组合使用（`400`）。", "example": "operational_session_delete" }, "instruction_id": { "type": "string", "maxLength": 255, "description": "您对该删除指令的持久化参考标识（例如删除工单 ID）。记录在审计追踪记录和任何保留的模板上。省略时由 Didit 自动生成。", "example": "dsar-2026-0142" }, "filter_status": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `status` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_vendor_data": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `vendor_data` 过滤器匹配的会话，取值相同。单个值，而不是列表：数组会被拼接成一个逗号分隔的文本，因此多个值不会作为备选项进行匹配。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "type": "string" }, "filter_search": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `search` 过滤器匹配的会话，取值相同。单个值，而不是列表：数组会被拼接成一个逗号分隔的文本，因此多个值不会作为备选项进行匹配。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "type": "string" }, "filter_workflow_id": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `workflow_id` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_date_from": { "description": "将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `date_from` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。", "type": "string", "format": "date" }, "filter_date_to": { "description": "将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `date_to` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。", "type": "string", "format": "date" }, "filter_country": { "description": "将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `country` 过滤器匹配且值相同的会话。逗号分隔的字符串或数组。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_document_type": { "description": "将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `document_type` 过滤器匹配且值相同的会话。逗号分隔的字符串或数组。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_document_name": { "description": "将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `document_name` 过滤器匹配且值相同的会话。逗号分隔的字符串或数组。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_region": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `region` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_didit_internal_id": { "description": "将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `didit_internal_id` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。", "type": "string", "format": "uuid" }, "filter_session_type": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `session_type` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_api_service": { "description": "将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `api_service` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。", "type": "string" }, "filter_screened_full_name": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `screened_full_name` 过滤器匹配的会话，取值相同。单个值，而不是列表：数组会被拼接成一个逗号分隔的文本，因此多个值不会作为备选项进行匹配。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "type": "string" }, "filter_warning": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `warning` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] }, "filter_status_initialized_as_in_review": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `status_initialized_as_in_review` 过滤器匹配的会话，取值相同。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "type": "boolean" }, "filter_is_kyc_to_be_reviewed": { "description": "将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `is_kyc_to_be_reviewed` 过滤器匹配且值相同的会话。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。", "type": "boolean" }, "filter_euuid": { "description": "将 `delete_all` 缩小至与[列出会话](/zh/sessions-api/list-sessions)的 `euuid` 过滤器匹配且值相同的会话。单个值，非列表：数组会被连接为一个逗号分隔的值，因此多个值会被拒绝并返回 `400`。若无 `delete_all` 则忽略。空值会被忽略，且不会缩小选择范围。", "type": "string", "format": "uuid" }, "filter_organization_name": { "description": "将 `delete_all` 的范围缩小为与 [List Sessions](/zh/sessions-api/list-sessions) 的 `organization_name` 过滤器匹配的会话，取值相同。逗号分隔的字符串或数组。使用 API 密钥时只能匹配您自己组织的名称，因此它会选择您的所有会话或不选择任何会话。在没有 `delete_all` 时被忽略。空值会被忽略，不会缩小选择范围。", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "examples": { "Specific sessions": { "summary": "按编号删除特定会话", "value": { "session_numbers": [ "1001", "1002", "1003" ] } }, "All sessions": { "summary": "删除应用中的所有 KYC 会话", "value": { "delete_all": true } }, "Delete and retain templates": { "summary": "删除会话但保留无图像的生物特征模板 365 天", "value": { "session_numbers": [ "1001", "1002" ], "retain_face_embeddings": true, "face_retention_days": 365, "instruction_id": "post-approval-cleanup-2026-08" } }, "Privacy erasure": { "summary": "删除会话并清除其用户的所有留存模板", "value": { "session_numbers": [ "1001" ], "deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142" } }, "Filtered delete_all": { "summary": "删除某工作流在 2026 年 9 月创建的所有已拒绝会话", "value": { "delete_all": true, "filter_status": [ "Declined" ], "filter_workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "filter_date_from": "2026-09-01", "filter_date_to": "2026-09-30" } } } } } }, "responses": { "200": { "description": "请求中最多匹配并处理了 20 个会话。每个匹配的会话对应一条结果；未匹配任何内容的编号（未知或已删除）会被跳过且不显示。结果将确认删除，除非 `face_retention_outcome` 为 `failed_retryable`：该会话未被删除，应进行重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "已删除的会话。" }, "session_number": { "type": "integer", "nullable": true, "description": "已删除会话的编号。" }, "face_retention_outcome": { "type": "string", "enum": [ "retained_with_user", "deleted", "none", "ineligible_no_vendor_user", "failed_retryable" ], "description": "会话的人脸生物特征数据的处理结果。`deleted`：人脸特征向量随会话一同被删除（默认）。`retained_with_user`：会话被删除，且一个不含图像的生物特征模板继续锚定到用户；请参阅 `biometric_template_uuid`。`none`：该会话没有人脸特征向量（例如仅验证证件而无需活体自拍照的 KYC 会话；此 endpoint 从不选择 KYB 会话）。`ineligible_no_vendor_user`：已请求保留，但该会话没有关联的用户，因此人脸特征向量随会话一同被删除。`failed_retryable`（仅限批量 endpoint）：此会话所属的批组无法被删除（存储服务、生物特征库或监控提供商不可用）；该会话仍保留在原处，请对其重新发起请求。" }, "biometric_template_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "当 `face_retention_outcome` 为 `retained_with_user` 时保留的生物特征模板 ID；否则为 `null`。可通过 `/v3/biometric-templates/{template_uuid}/` 进行管理。" }, "biometric_template_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "当 `face_retention_outcome` 为 `retained_with_user` 时，保留的生物特征模板被删除的时间；未保留模板时为 `null`。" }, "deleted_child_verifications": { "type": "integer", "description": "在此 endpoint 上始终为 `0`，该 endpoint 仅删除 KYC 会话。使用 `DELETE /v3/session/{sessionId}/delete/` 删除企业验证（KYB）会话会报告由其创建并随之一同删除的验证数量。" } } } } } }, "examples": { "Mixed outcomes": { "value": { "results": [ { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1001, "face_retention_outcome": "deleted", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 }, { "session_id": "b8e1d2c3-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "session_number": 1002, "face_retention_outcome": "retained_with_user", "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "biometric_template_expires_at": "2027-10-09T10:15:00Z", "deleted_child_verifications": 0 }, { "session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c", "session_number": 1003, "face_retention_outcome": "ineligible_no_vendor_user", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 }, { "session_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "session_number": 1004, "face_retention_outcome": "failed_retryable", "biometric_template_uuid": null, "biometric_template_expires_at": null, "deleted_child_verifications": 0 } ] } } } } } }, "202": { "description": "匹配到超过 20 个会话。这些会话正在后台删除；请轮询 `GET /v3/sessions/delete/{job_id}/`，直至 `status` 变为 `COMPLETED` 或 `FAILED`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDeletionJob" }, "examples": { "Job accepted": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "PENDING", "total": 250, "processed": 0, "outcomes": { "deleted": 0, "none": 0, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": null } } } } } }, "400": { "description": "验证错误 — 未删除任何内容。错误值为以字段名为键的消息字符串数组。", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_numbers": { "type": "array", "items": { "type": "string" } } }, "additionalProperties": { "description": "其他键：不属于列出会话（List Sessions）过滤器的 `filter_*` 键（`\"Unknown filter.\"`），或者值无法读取的 `filter_*` 键（以该 `filter_*` 键为键名，值为包含错误消息的数组）。" } }, "examples": { "Missing selector": { "summary": "既未提供 session_numbers 也未提供 delete_all", "value": { "session_numbers": [ "This field is required unless delete_all is true." ] } }, "Empty list": { "summary": "session_numbers 是一个空数组", "value": { "session_numbers": [ "This list may not be empty." ] } }, "Non-numeric entry": { "summary": "session_numbers 包含非数字字符串", "value": { "session_numbers": [ "All session_numbers must be numeric." ] } }, "Privacy erasure cannot retain": { "summary": "deletion_instruction 为 privacy_erasure 且 retain_face_embeddings 为 true 的组合", "value": { "retain_face_embeddings": [ "Privacy erasure cannot retain biometric templates." ] } }, "No finite retention duration": { "summary": "在请求或应用中未包含 face_retention_days 时请求了保留", "value": { "detail": "A finite biometric-template retention duration is required." } }, "Unknown filter": { "summary": "List Sessions 不具备的 filter_* 键", "value": { "filter_reviewer": "Unknown filter." } }, "Unreadable filter value": { "summary": "无法读取的过滤器值", "value": { "filter_date_from": [ "Enter a valid date." ] } } } } } }, "403": { "description": "缺少 API 密钥。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid API key": { "summary": "缺少 x-api-key 请求头，或该密钥无效", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出共享写入速率限制（每个 API 密钥每分钟 300 次 POST/PATCH/DELETE 请求）。重试前请检查 `Retry-After` 和 `X-RateLimit-*` 响应头。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "写入预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } }, "409": { "description": "所选会话属于已定稿的监管报告。未删除任何内容。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/sessions/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"session_numbers\": [\"1001\", \"1002\", \"1003\"]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.batch_delete(\n session_numbers=[\"1001\", \"1002\", \"1003\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.batchDelete({\n session_numbers: [\"1001\", \"1002\", \"1003\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.BatchDelete(ctx, didit.SessionsBatchDeleteParams{\n\tSessionNumbers: didit.Some([]string{\"1001\", \"1002\", \"1003\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().batchDelete(SessionsBatchDeleteParams.builder()\n .sessionNumbers(List.of(\"1001\", \"1002\", \"1003\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->batchDelete([\n 'session_numbers' => ['1001', '1002', '1003'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.batch_delete(session_numbers: [\"1001\", \"1002\", \"1003\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.BatchDeleteAsync(new SessionsBatchDeleteParams\n{\n SessionNumbers = new string[] { \"1001\", \"1002\", \"1003\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/sessions/delete/{job_id}/": { "get": { "summary": "获取批量会话删除任务", "description": "`POST /v3/sessions/delete/` 返回 `202` 时批量删除会话的进度（超过 20 个匹配的会话，通过 `session_numbers` 或 `delete_all` 选择）。当 `status` 为 `PENDING` 或 `PROCESSING` 时每隔几秒轮询一次；当其为 `COMPLETED` 或 `FAILED` 时停止。\n\n该任务会报告以每种结果结束的会话数量以及已处理的会话数量，绝不会报告删除了哪些会话。处于 `FAILED` 状态的任务会在 `error` 中包含失败原因；尚未处理到的会话仍会保留，因此请重复该删除请求以删除它们。\n\n**身份验证：**在 `x-api-key` 请求头中提供 API 密钥。任务仅对创建它的应用可见；任何其他 `job_id` 均返回 `404`。凭据缺失或无效将返回 `403`；此 API 绝不会返回 `401`。", "operationId": "get_session_deletion_job", "x-didit-sdk": { "resource": "sessions", "method": "retrieve_deletion_job", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "`POST /v3/sessions/delete/` 返回 `202` 时携带的 `job_id`。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl 'https://verification.didit.me/v3/sessions/delete/JOB_ID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.retrieve_deletion_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.retrieveDeletionJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.RetrieveDeletionJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().retrieveDeletionJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->retrieveDeletionJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.retrieve_deletion_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.RetrieveDeletionJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "作业。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDeletionJob" }, "examples": { "Processing": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "PROCESSING", "total": 250, "processed": 100, "outcomes": { "deleted": 82, "none": 18, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": null } }, "Completed": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "COMPLETED", "total": 250, "processed": 250, "outcomes": { "deleted": 204, "none": 44, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 2 }, "deleted_child_verifications": 0, "error": null, "created_at": "2026-10-09T10:15:00Z", "completed_at": "2026-10-09T10:16:40Z" } }, "Failed": { "value": { "job_id": "5b8f2c1e-7d3a-4f6b-9e2c-1a0d8f7e6c5b", "status": "FAILED", "total": 250, "processed": 100, "outcomes": { "deleted": 82, "none": 18, "retained_with_user": 0, "ineligible_no_vendor_user": 0, "failed_retryable": 0, "already_deleted": 0 }, "deleted_child_verifications": 0, "error": "The deletion stopped before it finished. The sessions it had not reached are still in place; repeat the request to delete them.", "created_at": "2026-10-09T10:15:00Z", "completed_at": "2026-10-09T10:15:52Z" } } } } } }, "403": { "description": "缺少 API 密钥。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid API key": { "summary": "缺少 x-api-key 请求头，或该密钥无效", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "调用方应用不存在具有此 `job_id` 的删除作业。作业仅对创建它们的应用可见。" } } } }, "/v3/sessions/{session_id}/reviews/": { "get": { "summary": "列出会话审核和活动日志", "description": "返回用户验证（KYC）会话的审计追踪/活动流，按最新优先排序，采用分页封装结构（`count` / `next` / `previous` / `results`，默认每页 50 条）。\n\n活动流条目由操作该会话的每个主体写入：通过 `PATCH /v3/session/{session_id}/update-status/` 作出的人工决策（记录 `previous_status` → `new_status`）、控制台审核员活动（带有 `@email` 提及的评论、KYC/POA 数据编辑、文件上传/删除、标签更改、详情页面查看）、AML 持续监控匹配项，以及通过此路径的 `POST` 请求追加的备注。读取此活动流在 API 端的等效操作是查看 Didit 控制台会话视图中的 **Activity** 面板。\n\n此处仅支持访问用户验证（KYC）会话；企业验证（KYB）会话 ID 将返回 `404`。", "operationId": "list_session_reviews", "x-didit-sdk": { "resource": "sessions.reviews", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "session_id", "in": "path", "required": true, "description": "用户验证（KYC）会话的 UUID。必须属于与 API 密钥相同的应用 — 跨应用 UUID、已删除会话以及企业验证（KYB）会话 ID 均返回 `404`。", "schema": { "type": "string", "format": "uuid", "example": "8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d" } }, { "name": "limit", "in": "query", "required": false, "description": "页面大小。默认为 `50`。", "schema": { "type": "integer", "default": 50, "example": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "从（有序）数据流开头跳过的条目数量。默认为 `0`。响应中的 `next` / `previous` URL 包含遍历数据流的正确值。", "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "ordering", "in": "query", "required": false, "description": "排序顺序。feed 默认按从新到旧排序（`-created_at`）；传入 `created_at` 可按从旧到新读取。无法识别的值会被静默忽略（采用默认顺序）；也支持其他序列化器字段名称。", "schema": { "type": "string", "default": "-created_at", "example": "created_at" } } ], "responses": { "200": { "description": "分页活动源，默认最新的排在前面。`count` 是条目总数；`next` / `previous` 是现成的页面 URL（末尾为 `null`）。`count` 为 `0` 且 `results` 为空表示尚未记录任何活动。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "该会话的动态条目总数（跨所有页面）。", "example": 3 }, "next": { "type": "string", "nullable": true, "description": "下一页的 URL，最后一页为 `null`。", "example": null }, "previous": { "type": "string", "nullable": true, "description": "上一页的 URL，第一页为 `null`。", "example": null }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReviewItem" }, "description": "此页面的动态流条目。" } } }, "examples": { "DecisionTrail": { "summary": "人工批准加上通过 API 添加的备注", "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "de0561bc-5583-4409-9171-1a31a4c8a5f4", "activity_type": "STATUS_UPDATED", "actor_display": "API Client", "actor_email": null, "actor_type": "API_KEY", "new_status": "Approved", "previous_status": "In Review", "comment": "Document re-checked manually; address matches.", "mentioned_emails": [], "previous_value": { "status": "In Review" }, "new_value": { "status": "Approved" }, "changed_fields": [ "status" ], "metadata": null, "created_at": "2026-06-12T00:19:31.918735Z" }, { "uuid": "35370f58-5098-44ee-8a06-8c9af80b2455", "activity_type": "STATUS_UPDATED", "actor_display": "Unknown", "actor_email": null, "actor_type": "CONSOLE_USER", "new_status": null, "previous_status": null, "comment": "Note without status.", "mentioned_emails": [], "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "created_at": "2026-06-12T00:18:44.504157Z" }, { "uuid": "00338f82-f1c5-4f57-8614-c49bb258af1a", "activity_type": "STATUS_UPDATED", "actor_display": "Unknown", "actor_email": null, "actor_type": "CONSOLE_USER", "new_status": "In Review", "previous_status": null, "comment": "Flagging for manual document re-check.", "mentioned_emails": [], "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "created_at": "2026-06-12T00:18:44.466537Z" } ] } }, "PaginatedFirstPage": { "summary": "limit=2 的第一页，next 包含后续 URL", "value": { "count": 4, "next": "https://verification.didit.me/v3/sessions/8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d/reviews/?limit=2&offset=2", "previous": null, "results": [ { "uuid": "de0561bc-5583-4409-9171-1a31a4c8a5f4", "activity_type": "STATUS_UPDATED", "actor_display": "API Client", "actor_email": null, "actor_type": "API_KEY", "new_status": "Approved", "previous_status": "In Review", "comment": "Document re-checked manually; address matches.", "mentioned_emails": [], "previous_value": { "status": "In Review" }, "new_value": { "status": "Approved" }, "changed_fields": [ "status" ], "metadata": null, "created_at": "2026-06-12T00:19:31.918735Z" }, { "uuid": "bd4e6227-bdd2-42b2-a726-1d12f785a457", "activity_type": "STATUS_UPDATED", "actor_display": "Unknown", "actor_email": null, "actor_type": "CONSOLE_USER", "new_status": null, "previous_status": null, "comment": null, "mentioned_emails": [], "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "created_at": "2026-06-12T00:18:44.540238Z" } ] } }, "Empty": { "summary": "尚无活动记录的会话", "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "403": { "description": "缺少、格式错误、已过期或已撤销的 `x-api-key`。身份验证在会话查找之前检查，因此即使会话 UUID 不存在，缺少密钥也会返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." } } }, "examples": { "InvalidKey": { "summary": "x-api-key 请求头缺失或无效", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "您的应用不可见具有此 UUID 的用户验证（KYC）会话：该 UUID 不存在、会话已被删除，或属于其他应用。企业验证（KYB）会话 ID 在此处也返回 `404`，审核动态仅支持 KYC 会话。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Session not found." } } }, "examples": { "NotFound": { "summary": "未知、已删除或跨应用的会话 UUID", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "超出速率限制。请检查 `Retry-After` 和 `X-RateLimit-*` 响应头。参见[速率限制](/zh/integration/rate-limiting)。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -s 'https://verification.didit.me/v3/sessions/8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d/reviews/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.reviews.list(\n \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.reviews.list(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.Reviews.ListAutoPaging(ctx, \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", didit.SessionsReviewsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().reviews().list(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->reviews->list('8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.reviews.list(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.Reviews.ListAsync(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "向会话的审计日志添加审核备注", "description": "向用户验证（KYC）会话的审核 / 活动动态追加一条备注。**此 endpoint 仅记录一条条目，绝不会更改会话。** 会话的 `status` 保持不变，不执行状态流转验证，也不触发任何 Webhook。若要实际通过、拒绝或重新打开会话（这也会向该动态写入一条具有完整归属信息的 `STATUS_UPDATED` 条目），请改用 `PATCH /v3/session/{session_id}/update-status/`。\n\n请求体中的两个字段均为可选，也接受空的 JSON 对象。`new_status` 仅作为条目上的标签存储，接受十个会话状态值中的任意一个（区分大小写）。`comment` 中的 `@email` 提及仅作为纯文本存储，它们不会在此 endpoint 上触发任何通知，并且条目的 `mentioned_emails` 保持为空。\n\n关于归属信息的说明：此处创建的条目不携带任何操作者信息。在动态中，它们显示 `actor_display: \"Unknown\"`、`actor_type: \"CONSOLE_USER\"` 和 `activity_type: \"STATUS_UPDATED\"`（存储默认值），且 `201` 响应体中的 `user` 字段为 `\"Unknown\"`。", "operationId": "create_session_review", "x-didit-sdk": { "resource": "sessions.reviews", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "Content-Type", "in": "header", "required": false, "description": "发送 JSON 请求体时设为 `application/json`。", "schema": { "type": "string", "example": "application/json" } }, { "name": "session_id", "in": "path", "required": true, "description": "用户验证（KYC）会话的 UUID。必须属于与 API 密钥相同的应用 — 跨应用 UUID、已删除会话以及企业验证（KYB）会话 ID 均返回 `404`。", "schema": { "type": "string", "format": "uuid", "example": "8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "new_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "可选的记录在条目上的状态标签。接受任何区分大小写的会话状态值（`\"approved\"` 会被拒绝并返回 `400`）。在此处记录状态**不会**更改会话的实际状态，如需更改请使用更新状态的 endpoint。", "example": "In Review" }, "comment": { "type": "string", "nullable": true, "description": "可选的自由文本备注（无强制长度限制）。按原样存储；此 endpoint 不会处理 `@email` 提及。", "example": "Flagging for manual document re-check." } } }, "examples": { "NoteWithStatusLabel": { "summary": "附带状态标签的备注（会话状态未变更）", "value": { "new_status": "In Review", "comment": "Flagging for manual document re-check." } }, "CommentOnly": { "summary": "无状态标签的普通备注", "value": { "comment": "Customer emailed an updated utility bill; awaiting upload." } } } } } }, "responses": { "201": { "description": "在会话的审计日志中记录的条目。会话本身保持不变，其 `status` 保留先前的值，且不发送 Webhook。新条目还会显示在 `GET …/reviews/` 的顶部（带有 `actor_display: \"Unknown\"`）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "user": { "type": "string", "description": "条目创建者的显示名称。通过此 endpoint 创建的条目始终为 `\"Unknown\"`，因为其不记录操作者归属。", "example": "Unknown" }, "new_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "记录在条目上的状态标签，如果未发送则为 `null`。会话的实际状态不受影响。", "example": "In Review" }, "comment": { "type": "string", "nullable": true, "description": "条目上记录的备注；若未发送任何备注，则为 `null`。", "example": "Flagging for manual document re-check." }, "created_at": { "type": "string", "format": "date-time", "description": "条目写入的时间，ISO 8601 UTC 格式。", "example": "2026-06-12T00:18:44.466537Z" } } }, "examples": { "NoteWithStatusLabel": { "summary": "带有状态标签的备注", "value": { "user": "Unknown", "new_status": "In Review", "comment": "Flagging for manual document re-check.", "created_at": "2026-06-12T00:18:44.466537Z" } }, "CommentOnly": { "summary": "普通备注", "value": { "user": "Unknown", "new_status": null, "comment": "Note without status.", "created_at": "2026-06-12T00:18:44.504157Z" } } } } } }, "400": { "description": "验证错误，作为按字段划分的消息映射返回。通常原因是 `new_status` 值不是十个允许的状态之一 — 该检查区分大小写。", "content": { "application/json": { "schema": { "type": "object", "properties": { "new_status": { "type": "array", "items": { "type": "string" }, "example": [ "\"approved\" is not a valid choice." ] } } }, "examples": { "InvalidStatusChoice": { "summary": "小写/未知的状态值", "value": { "new_status": [ "\"approved\" is not a valid choice." ] } } } } } }, "403": { "description": "缺少、格式错误、已过期或已撤销的 `x-api-key`。身份验证在会话查找之前检查，因此即使会话 UUID 不存在，缺少密钥也会返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "You do not have permission to perform this action." } } }, "examples": { "InvalidKey": { "summary": "x-api-key 请求头缺失或无效", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "您的应用不可见具有此 UUID 的用户验证（KYC）会话：该 UUID 不存在、会话已被删除，或属于其他应用。企业验证（KYB）会话 ID 在此处也返回 `404`，审核动态仅支持 KYC 会话。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "example": "Session not found." } } }, "examples": { "NotFound": { "summary": "未知、已删除或跨应用的会话 UUID", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "超出速率限制。请检查 `Retry-After` 和 `X-RateLimit-*` 响应头。参见[速率限制](/zh/integration/rate-limiting)。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "# Records an audit-trail note only -- the session's status does NOT change.\ncurl -s -X POST https://verification.didit.me/v3/sessions/8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d/reviews/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"new_status\": \"In Review\",\n \"comment\": \"Flagging for manual document re-check.\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.reviews.create(\n \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\",\n new_status=\"In Review\",\n comment=\"Flagging for manual document re-check.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.reviews.create(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", {\n new_status: \"In Review\",\n comment: \"Flagging for manual document re-check.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Reviews.Create(ctx, \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", didit.SessionsReviewsCreateParams{\n\tNewStatus: didit.Some(didit.SessionsReviewsCreateParamsNewStatus(\"In Review\")),\n\tComment: didit.String(\"Flagging for manual document re-check.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsReviewsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().reviews().create(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", SessionsReviewsCreateParams.builder()\n .newStatus(SessionsReviewsCreateParams.NewStatus.of(\"In Review\"))\n .comment(\"Flagging for manual document re-check.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->reviews->create('8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d', [\n 'new_status' => 'In Review',\n 'comment' => 'Flagging for manual document re-check.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.reviews.create(\n \"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\",\n new_status: \"In Review\",\n comment: \"Flagging for manual document re-check.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Reviews.CreateAsync(\"8c2f3a14-7e9b-4d23-9e83-3f7d5e8a1c6d\", new SessionsReviewsCreateParams\n{\n NewStatus = new SessionsReviewsCreateParamsNewStatus(\"In Review\"),\n Comment = \"Flagging for manual document re-check.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/billing/balance/": { "get": { "summary": "获取额度余额", "description": "获取组织当前以美元计的预付费额度余额以及自动充值配置。金额为十进制字符串，请使用十进制库进行解析。", "operationId": "get_billing_balance", "x-didit-sdk": { "resource": "billing", "method": "retrieve_balance", "auth": "api_key", "server": true }, "tags": [ "Billing" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/billing/balance/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.billing.retrieve_balance()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.billing.retrieveBalance();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Billing.RetrieveBalance(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.billing().retrieveBalance();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "billing->retrieveBalance();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.billing.retrieve_balance\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Billing.RetrieveBalanceAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "当前额度余额以及组织的自动充值配置。", "content": { "application/json": { "schema": { "type": "object", "required": [ "balance", "auto_refill_enabled" ], "properties": { "balance": { "type": "string", "description": "以 USD 计的当前预付费额度余额，表示为定点十进制字符串。随验证计费而扣减，在充值结算后增加。" }, "auto_refill_enabled": { "type": "boolean", "description": "为 `true` 时，一旦余额越过 `auto_refill_threshold`，Didit 将自动通过已保存的支付方式扣款以充值额度。在控制台 → 计费中配置。" }, "auto_refill_amount": { "type": "string", "nullable": true, "description": "每次自动充值时按面额扣除并添加到余额中的美元金额。在 Console → Billing 中设置为 \\$50 至 \\$20,000。禁用或未设置自动充值时为 `null`。" }, "auto_refill_threshold": { "type": "string", "nullable": true, "description": "以美元（USD）计的触发阈值。当 `balance` 低于该值时触发自动充值。未启用或未设置自动充值时为 `null`。" } } }, "examples": { "Healthy balance with auto-refill": { "value": { "balance": "1234.5600", "auto_refill_enabled": true, "auto_refill_amount": "500.00", "auto_refill_threshold": "100.00" } }, "Low balance, manual top-up only": { "value": { "balance": "12.0000", "auto_refill_enabled": false, "auto_refill_amount": null, "auto_refill_threshold": null } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法读取此组织的计费数据。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/billing/top-up/": { "post": { "summary": "充值额度", "description": "通过托管的 Stripe Checkout 会话添加额度（每次充值 **\\$50 至 \\$20,000**）。Free、Growth 和 Scale 套餐支持充值，按面值添加且无折扣或赠送，有效期为 12 个月；Enterprise 年度合约无法充值。将客户重定向至返回的 `checkout_session_url`。", "operationId": "billing_top_up", "x-didit-sdk": { "resource": "billing", "method": "top_up", "auth": "api_key", "server": true }, "tags": [ "Billing" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount_in_dollars" ], "properties": { "amount_in_dollars": { "type": "number", "minimum": 50, "maximum": 20000, "description": "扣款金额，以 USD 计。**必须在 50 到 20,000 之间。** 余额将增加相同金额，无任何折扣或奖励。结账时将根据客户的账单地址自动加计税费。" }, "success_url": { "type": "string", "format": "uri", "description": "支付成功后托管结账将客户重定向到的 URL。当前默认为 `https://console.didit.me`。请显式传入可用 URL；默认主机不可用。如果您希望托管结账替换会话 ID，请附加字面量占位符 `{CHECKOUT_SESSION_ID}`。" }, "cancel_url": { "type": "string", "format": "uri", "description": "当客户中止或关闭结账窗口时，托管结账将客户重定向到的 URL。当前默认为 `https://console.didit.me`。请显式传入可用 URL；默认主机不可用。" } } }, "examples": { "Minimum top-up": { "value": { "amount_in_dollars": 50 } }, "Custom amount with redirects": { "value": { "amount_in_dollars": 500, "success_url": "https://yourapp.com/billing/top-up/success", "cancel_url": "https://yourapp.com/billing/top-up/cancel" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/billing/top-up/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"amount_in_dollars\": 500,\n \"success_url\": \"https://yourapp.com/billing/success\",\n \"cancel_url\": \"https://yourapp.com/billing/cancel\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.billing.top_up(\n amount_in_dollars=50.0,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.billing.topUp({\n amount_in_dollars: 50.0,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Billing.TopUp(ctx, didit.BillingTopUpParams{\n\tAmountInDollars: 50.0,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BillingTopUpParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.billing().topUp(BillingTopUpParams.builder()\n .amountInDollars(50.0)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "billing->topUp([\n 'amount_in_dollars' => 50.0,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.billing.top_up(amount_in_dollars: 50.0)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Billing.TopUpAsync(new BillingTopUpParams\n{\n AmountInDollars = 50.0,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "托管结账会话已创建。将用户重定向至 `checkout_session_url` 以完成支付。", "content": { "application/json": { "schema": { "type": "object", "required": [ "checkout_session_id", "checkout_session_url" ], "properties": { "checkout_session_id": { "type": "string", "description": "托管结账会话标识符（例如 `cs_test_a1B2c3...`）。用于服务端对账。" }, "checkout_session_url": { "type": "string", "format": "uri", "description": "单次使用的托管支付页面 URL。将客户重定向至此处以完成支付。" } } }, "examples": { "Created": { "value": { "checkout_session_id": "cs_test_a1B2c3D4e5F6g7H8i9J0", "checkout_session_url": "https://checkout.example.com/c/pay/cs_test_a1B2c3D4e5F6g7H8i9J0" } } } } } }, "400": { "description": "无效的 payload：缺少金额、金额不是数字、低于 \\$50 的最低限额或高于 \\$20,000 的最高限额，或者该组织使用的是企业年度合同。错误体为 JSON 数组。", "content": { "application/json": { "examples": { "Missing amount": { "value": [ "amount_in_dollars is required." ] }, "Not a number": { "value": [ "amount_in_dollars must be a number." ] }, "Below minimum": { "value": [ "Amount must be at least $50." ] }, "Above maximum": { "value": [ "Amount must be at most $20,000." ] }, "Annual plan": { "value": [ "You have an annual plan. Contact your account manager to top up." ] } } } } }, "403": { "description": "API 密钥缺失、无效或已撤销，或者该密钥无法为此组织创建充值会话。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/": { "get": { "summary": "列出 Webhook 目标", "description": "列出所有 Webhook 目标（未分页数组，最早的优先）。每项包含目标的配置、过去 30 天的投递指标（`metrics_window_days`，每天一个 `daily_points` 条目）以及其健康状态（`health_status`、`failing_streak`、`failing_since`、`last_success_at`）。列表没有 `summary` 对象，且绝不包含签名密钥：每项仅显示 `secret_last4`。获取单个目标（`GET /v3/webhook/destinations/{destination_uuid}/`）以读取 `secret_shared_key`。", "operationId": "list_webhook_destinations", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.list()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.list();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.List(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().list();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->list();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.webhooks.destinations.list.each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.ListAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Webhook 目标列表（未分页，最早的优先）。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "目标的稳定标识符；在更新/删除时用作 `{destination_uuid}`。" }, "label": { "type": "string", "description": "在 Console 中显示的便于人类阅读的名称。" }, "url": { "type": "string", "format": "uri", "description": "接收包含 Webhook payload 的 `POST` 请求的目标 URL。" }, "enabled": { "type": "boolean", "description": "为 `false` 时，Didit 会静默跳过向此目标的投递。" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "发送至该目标的 payload 架构版本。`v3` 为当前/推荐格式。" }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "subscribed_events_count": { "type": "integer", "description": "已缓存的 `subscribed_events` 长度，便于 UI 渲染。" }, "deliveries_count": { "type": "integer", "description": "过去 30 天内向此目标发起的投递尝试次数（包括重试）。" }, "failed_deliveries_count": { "type": "integer", "description": "过去 30 天内该目标以 HTTP 400 或更高状态码响应、或未作响应（超时、连接被拒或地址被屏蔽）的投递尝试次数。" }, "average_response_time_ms": { "type": "integer", "nullable": true, "description": "过去 30 天内的平均响应时间（毫秒），四舍五入为整数。在该时间窗口内没有投递时为 `null`。" }, "error_rate_percentage": { "type": "integer", "description": "过去 30 天内的 `round(failed_deliveries_count / deliveries_count * 100)`；无投递记录时为 `0`。" }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true, "description": "最近一次投递尝试的时间戳（成功或失败）。如果从未投递则为 `null`。" }, "metrics_window_days": { "type": "integer", "description": "`deliveries_count`、`failed_deliveries_count`、`average_response_time_ms`、`error_rate_percentage` 和 `daily_points` 所覆盖的时间窗口长度（天）。始终为 `30`。" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "投递健康状态。`failing`：自该目标上次成功响应以来，已有 3 个或更多连续事件在首次投递尝试时失败（参见 `failing_streak`）。`degraded`：非 failing 状态，但在过去 24 小时内有一次投递尝试失败，且后续没有尝试成功投递该事件；成功投递该事件的重试或重新发送会清除此状态。`healthy`：均非上述情况。独立于 `enabled`。失败的尝试是指响应 HTTP 400 或以上，或者完全没有响应的尝试。" }, "failing_streak": { "type": "integer", "description": "在最近 30 天内，自该目标上次成功响应以来，首次投递尝试失败的连续事件数量。重试不计入，任何成功的尝试（包括重试或重新发送）都会结束该连续记录。自上次成功以来没有事件失败时为 `0`。" }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "当前 `failing_streak` 中第一次失败尝试的时间。当 `failing_streak` 为 `0` 时为 `null`。" }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在过去 30 天内，目标上次以低于 400 的 HTTP 状态响应投递的时间。如果在此时间窗口内没有以低于 400 的 HTTP 状态响应，则为 `null`。" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "拥有该目标的应用的环境。" }, "daily_points": { "type": "array", "description": "过去 30 天内每个 UTC 天对应一个条目，按时间从早到晚排列，包含没有投递的日期。统计每一次尝试，包括重试在内。", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date", "description": "UTC 日期。" }, "total_deliveries": { "type": "integer", "description": "当天进行的投递尝试次数。" }, "failed_deliveries": { "type": "integer", "description": "当天收到 HTTP 400 或更高状态码响应、或者根本未收到响应的尝试次数。" } } } }, "secret_last4": { "type": "string", "description": "目标当前签名密钥的最后四位字符，以便您区分不同的密钥。不足以用于验证签名。" }, "created_by_email": { "type": "string", "nullable": true, "description": "创建该目标的 Business Console 成员的邮箱。通过 API 密钥创建的目标为 `null`。" }, "created_by_name": { "type": "string", "nullable": true, "description": "创建该目标的 Business Console 成员姓名。使用 API 密钥创建的目标为 `null`。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } }, "examples": { "Two destinations": { "value": [ { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "subscribed_events": [ "status.updated", "data.updated" ], "subscribed_events_count": 2, "deliveries_count": 12453, "failed_deliveries_count": 14, "average_response_time_ms": 187, "error_rate_percentage": 0, "last_delivery_at": "2026-05-17T09:21:18Z", "metrics_window_days": 30, "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": "2026-05-17T09:21:18Z", "environment": "live", "daily_points": [ { "date": "2026-04-18", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-19", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-20", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-21", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-22", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-23", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-24", "total_deliveries": 415, "failed_deliveries": 9 }, { "date": "2026-04-25", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-26", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-27", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-28", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-29", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-04-30", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-01", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-02", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-03", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-04", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-05", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-06", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-07", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-08", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-09", "total_deliveries": 415, "failed_deliveries": 5 }, { "date": "2026-05-10", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-11", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-12", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-13", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-14", "total_deliveries": 415, "failed_deliveries": 0 }, { "date": "2026-05-15", "total_deliveries": 416, "failed_deliveries": 0 }, { "date": "2026-05-16", "total_deliveries": 416, "failed_deliveries": 0 }, { "date": "2026-05-17", "total_deliveries": 416, "failed_deliveries": 0 } ], "secret_last4": "0xnQ", "created_by_email": null, "created_by_name": null, "created_at": "2026-01-04T08:00:00Z", "updated_at": "2026-04-22T14:09:11Z" }, { "uuid": "22222222-3333-4444-5555-666666666666", "label": "Staging mirror", "url": "https://staging.yourapp.com/webhooks/didit", "enabled": false, "webhook_version": "v3", "subscribed_events": [ "status.updated" ], "subscribed_events_count": 1, "deliveries_count": 0, "failed_deliveries_count": 0, "average_response_time_ms": null, "error_rate_percentage": 0, "last_delivery_at": null, "metrics_window_days": 30, "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": null, "environment": "live", "daily_points": [ { "date": "2026-04-18", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-19", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-20", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-21", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-22", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-23", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-24", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-25", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-26", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-27", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-28", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-29", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-04-30", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-01", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-02", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-03", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-04", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-05", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-06", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-07", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-08", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-09", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-10", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-11", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-12", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-13", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-14", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-15", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-16", "total_deliveries": 0, "failed_deliveries": 0 }, { "date": "2026-05-17", "total_deliveries": 0, "failed_deliveries": 0 } ], "secret_last4": "k9Qe", "created_by_email": "reviewer@example.com", "created_by_name": "Example Reviewer", "created_at": "2026-03-12T10:15:02Z", "updated_at": "2026-03-12T10:15:02Z" } ] } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。密钥缺失返回 `403`；密钥错误、已撤销或已过期返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并重试。", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建 Webhook 目标", "description": "创建 Webhook 目标。响应中包含自动生成的 `secret_shared_key` HMAC 签名密钥（稍后也可通过 `GET /v3/webhook/destinations/{destination_uuid}/` 读取）。发送 `subscribed_events` 时必须始终包含至少一个事件（不支持通配符）：显式传递空列表会被拒绝并返回 400，而省略该字段则会创建一个未订阅任何内容的目标，该目标将永远无法接收 Webhook。`(application, url)` 对在应用的目标中必须唯一。", "operationId": "create_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/webhook/destinations/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"label\": \"Production session webhooks\",\n \"url\": \"https://yourapp.com/webhooks/didit\",\n \"webhook_version\": \"v3\",\n \"subscribed_events\": [\"status.updated\", \"data.updated\"]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.create(\n label=\"Production session webhooks\",\n url=\"https://yourapp.com/webhooks/didit\",\n webhook_version=\"v3\",\n subscribed_events=[\"status.updated\", \"data.updated\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.create({\n label: \"Production session webhooks\",\n url: \"https://yourapp.com/webhooks/didit\",\n webhook_version: \"v3\",\n subscribed_events: [\"status.updated\", \"data.updated\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Create(ctx, didit.WebhooksDestinationsCreateParams{\n\tLabel: \"Production session webhooks\",\n\tURL: \"https://yourapp.com/webhooks/didit\",\n\tWebhookVersion: didit.Some(didit.WebhooksDestinationsCreateParamsWebhookVersion(\"v3\")),\n\tSubscribedEvents: didit.Some([]didit.WebhookEvent{didit.WebhookEvent(\"status.updated\"), didit.WebhookEvent(\"data.updated\")}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.WebhookEvent;\nimport me.didit.types.WebhooksDestinationsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().create(WebhooksDestinationsCreateParams.builder()\n .label(\"Production session webhooks\")\n .url(\"https://yourapp.com/webhooks/didit\")\n .webhookVersion(WebhooksDestinationsCreateParams.WebhookVersion.of(\"v3\"))\n .subscribedEvents(List.of(WebhookEvent.of(\"status.updated\"), WebhookEvent.of(\"data.updated\")))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->create([\n 'label' => 'Production session webhooks',\n 'url' => 'https://yourapp.com/webhooks/didit',\n 'webhook_version' => 'v3',\n 'subscribed_events' => ['status.updated', 'data.updated'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.create(\n label: \"Production session webhooks\",\n url: \"https://yourapp.com/webhooks/didit\",\n webhook_version: \"v3\",\n subscribed_events: [\"status.updated\", \"data.updated\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.CreateAsync(new WebhooksDestinationsCreateParams\n{\n Label = \"Production session webhooks\",\n Url = \"https://yourapp.com/webhooks/didit\",\n WebhookVersion = new WebhooksDestinationsCreateParamsWebhookVersion(\"v3\"),\n SubscribedEvents = new WebhookEvent[] { \"status.updated\", \"data.updated\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "label", "url" ], "properties": { "label": { "type": "string", "maxLength": 255, "description": "在 Console → Webhooks 中显示的便于人类阅读的名称。当您有多个目标时有助于进行区分（例如 \"Prod\"、\"Staging mirror\"）。" }, "url": { "type": "string", "format": "uri", "description": "接收 `POST` 请求的 HTTPS URL。在应用的目标中必须唯一。请使用稳定且经过强化的 endpoint：Didit 会按退避计划重试失败的投递。", "maxLength": 2000 }, "enabled": { "type": "boolean", "default": true, "description": "为 `false` 时，目标会被保存，但 Didit 不会向其推送任何 Webhook。适用于您希望保留但暂不启用的配置。" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "Didit 将发送的 payload 架构版本。`v3` 为当前/推荐格式；保留较旧版本是为了向后兼容历史集成。" }, "subscribed_events": { "allOf": [ { "$ref": "#/components/schemas/WebhookSubscribedEvents" } ], "description": "要投递的事件。实际上为必填项：显式传入 `[]` 将被拒绝并返回 400，而省略该字段会创建一个没有任何订阅的目标，该目标不会接收任何内容。" } } }, "examples": { "session_updates": { "summary": "会话状态与数据更新", "value": { "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "subscribed_events": [ "status.updated", "data.updated" ] } }, "transaction_updates": { "summary": "交易监控更新", "value": { "label": "Transaction monitoring webhooks", "url": "https://yourapp.com/webhooks/didit-transactions", "webhook_version": "v3", "subscribed_events": [ "transaction.created", "transaction.status.updated" ] } }, "entity_updates": { "summary": "用户和企业实体更新", "value": { "label": "Entity lifecycle webhooks", "url": "https://yourapp.com/webhooks/didit-entities", "webhook_version": "v3", "subscribed_events": [ "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created" ] } } } } } }, "responses": { "201": { "description": "目标已创建。`secret_shared_key` 是 HMAC 签名密钥，请立即保存。", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "目标稳定标识符。在后续调用中用作 `{destination_uuid}`。" }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ] }, "secret_shared_key": { "type": "string", "description": "与该目标绑定的自动生成的 HMAC 签名密钥（43 个字符的 URL 安全 token）。用于验证传入 Webhook 的签名请求头。对于使用 API 密钥的调用方始终完整返回；控制台用户需要具备 `read:webhooks` 权限，否则将看到空字符串。" }, "secret_last4": { "type": "string", "description": "目标当前签名密钥的最后四位字符，以便您区分不同的密钥。不足以用于验证签名。" }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在 Business Console 中轮换目标的签名密钥后设置 24 小时。在此期间，向该目标进行的每次投递还会携带使用被替换密钥生成的 `X-Signature-Previous`、`X-Signature-V2-Previous` 和 `X-Signature-Simple-Previous`（请参阅[签名验证](/zh/integration/webhooks#签名验证)）。如果在过去 24 小时内未发生轮换，则为 `null`。" }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "created_by_email": { "type": "string", "nullable": true, "description": "创建该目标的 Business Console 成员的邮箱。通过 API 密钥创建的目标为 `null`。" }, "created_by_name": { "type": "string", "nullable": true, "description": "创建该目标的 Business Console 成员姓名。使用 API 密钥创建的目标为 `null`。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "投递健康状态。`failing`：自该目标上次成功响应以来，已有 3 个或更多连续事件在首次投递尝试时失败（参见 `failing_streak`）。`degraded`：非 failing 状态，但在过去 24 小时内有一次投递尝试失败，且后续没有尝试成功投递该事件；成功投递该事件的重试或重新发送会清除此状态。`healthy`：均非上述情况。独立于 `enabled`。失败的尝试是指响应 HTTP 400 或以上，或者完全没有响应的尝试。" }, "failing_streak": { "type": "integer", "description": "在最近 30 天内，自该目标上次成功响应以来，首次投递尝试失败的连续事件数量。重试不计入，任何成功的尝试（包括重试或重新发送）都会结束该连续记录。自上次成功以来没有事件失败时为 `0`。" }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "当前 `failing_streak` 中第一次失败尝试的时间。当 `failing_streak` 为 `0` 时为 `null`。" }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在过去 30 天内，目标上次以低于 400 的 HTTP 状态响应投递的时间。如果在此时间窗口内没有以低于 400 的 HTTP 状态响应，则为 `null`。" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "拥有该目标的应用的环境。" }, "summary": { "type": "object", "description": "最近 `metrics_window_days`（30）天的投递指标。`last_delivery_at` 为最近一次尝试的时间，无论其何时发生。", "properties": { "total_deliveries": { "type": "integer" }, "failed_deliveries": { "type": "integer" }, "error_rate_percentage": { "type": "integer" }, "min_response_time_ms": { "type": "integer", "nullable": true }, "avg_response_time_ms": { "type": "integer", "nullable": true }, "max_response_time_ms": { "type": "integer", "nullable": true }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "metrics_window_days": { "type": "integer", "description": "其他汇总指标所覆盖的时间窗口长度（天）。始终为 `30`。" } } } } }, "examples": { "Created": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ", "secret_last4": "0xnQ", "previous_secret_expires_at": null, "subscribed_events": [ "status.updated", "data.updated" ], "created_by_email": null, "created_by_name": null, "created_at": "2026-05-17T10:00:00Z", "updated_at": "2026-05-17T10:00:00Z", "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": null, "environment": "live", "summary": { "total_deliveries": 0, "failed_deliveries": 0, "error_rate_percentage": 0, "min_response_time_ms": null, "avg_response_time_ms": null, "max_response_time_ms": null, "last_delivery_at": null, "metrics_window_days": 30 } } } } } } }, "400": { "description": "验证失败 — 通常是因为 URL 重复、`subscribed_events` 缺失/无效或未知的事件名称。", "content": { "application/json": { "examples": { "Duplicate URL": { "value": { "url": [ "This webhook destination already exists for the application." ] } }, "Empty events list": { "value": { "subscribed_events": [ "At least one subscribed event is required." ] } }, "Unknown event": { "value": { "subscribed_events": [ "Unsupported webhook events: foo.bar" ] } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。密钥缺失返回 `403`；密钥错误、已撤销或已过期返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并重试。", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/": { "get": { "summary": "获取 Webhook 目标", "description": "获取单个 Webhook 目标，包含其 `secret_shared_key` 签名密钥、健康状态（`health_status`、`failing_streak`、`failing_since`、`last_success_at`）以及过去 30 天的投递 `summary`。API 密钥调用方始终会收到完整的密钥；没有 `read:webhooks` 权限的控制台用户将看到空字符串。", "operationId": "get_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "目标的 UUID（创建/列出时返回的 `uuid`）。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Webhook 目标详情。", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ] }, "secret_shared_key": { "type": "string", "description": "HMAC 签名密钥（43 个字符的 URL 安全 token）。对于使用 API 密钥的调用方始终完整返回；控制台用户需要 `read:webhooks` 权限，否则返回空字符串。" }, "secret_last4": { "type": "string", "description": "目标当前签名密钥的最后四位字符，以便您区分不同的密钥。不足以用于验证签名。" }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在 Business Console 中轮换目标的签名密钥后设置 24 小时。在此期间，向该目标进行的每次投递还会携带使用被替换密钥生成的 `X-Signature-Previous`、`X-Signature-V2-Previous` 和 `X-Signature-Simple-Previous`（请参阅[签名验证](/zh/integration/webhooks#签名验证)）。如果在过去 24 小时内未发生轮换，则为 `null`。" }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "created_by_email": { "type": "string", "nullable": true, "description": "创建该目标的 Business Console 成员的邮箱。通过 API 密钥创建的目标为 `null`。" }, "created_by_name": { "type": "string", "nullable": true, "description": "创建该目标的 Business Console 成员姓名。使用 API 密钥创建的目标为 `null`。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "投递健康状态。`failing`：自该目标上次成功响应以来，已有 3 个或更多连续事件在首次投递尝试时失败（参见 `failing_streak`）。`degraded`：非 failing 状态，但在过去 24 小时内有一次投递尝试失败，且后续没有尝试成功投递该事件；成功投递该事件的重试或重新发送会清除此状态。`healthy`：均非上述情况。独立于 `enabled`。失败的尝试是指响应 HTTP 400 或以上，或者完全没有响应的尝试。" }, "failing_streak": { "type": "integer", "description": "在最近 30 天内，自该目标上次成功响应以来，首次投递尝试失败的连续事件数量。重试不计入，任何成功的尝试（包括重试或重新发送）都会结束该连续记录。自上次成功以来没有事件失败时为 `0`。" }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "当前 `failing_streak` 中第一次失败尝试的时间。当 `failing_streak` 为 `0` 时为 `null`。" }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在过去 30 天内，目标上次以低于 400 的 HTTP 状态响应投递的时间。如果在此时间窗口内没有以低于 400 的 HTTP 状态响应，则为 `null`。" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "拥有该目标的应用的环境。" }, "summary": { "type": "object", "description": "最近 `metrics_window_days`（30）天的投递指标。`last_delivery_at` 为最近一次尝试的时间，无论其何时发生。", "properties": { "total_deliveries": { "type": "integer" }, "failed_deliveries": { "type": "integer" }, "error_rate_percentage": { "type": "integer" }, "min_response_time_ms": { "type": "integer", "nullable": true }, "avg_response_time_ms": { "type": "integer", "nullable": true }, "max_response_time_ms": { "type": "integer", "nullable": true }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "metrics_window_days": { "type": "integer", "description": "其他汇总指标所覆盖的时间窗口长度（天）。始终为 `30`。" } } } } }, "examples": { "Healthy destination": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ", "secret_last4": "0xnQ", "previous_secret_expires_at": null, "subscribed_events": [ "status.updated", "data.updated" ], "created_by_email": null, "created_by_name": null, "created_at": "2026-01-04T08:00:00Z", "updated_at": "2026-04-22T14:09:11Z", "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": "2026-05-17T09:21:18Z", "environment": "live", "summary": { "total_deliveries": 12453, "failed_deliveries": 14, "error_rate_percentage": 0, "min_response_time_ms": 41, "avg_response_time_ms": 187, "max_response_time_ms": 2103, "last_delivery_at": "2026-05-17T09:21:18Z", "metrics_window_days": 30 } } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。密钥缺失返回 `403`；密钥错误、已撤销或已过期返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "不存在具有此 UUID 的目标，或者它属于不同的应用，或者已被删除。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "超出速率限制；请退避并重试。", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新 Webhook 目标", "description": "更新 Webhook 目标。**`subscribed_events` 将被整项替换，而非合并**：请先获取、追加然后再重新发送。密钥不会轮换。请求体中的 `uuid` 将被忽略：以路径指定的 Webhook 目标为准。", "operationId": "update_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "要更新的 Webhook 目标的 UUID。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "label": { "type": "string", "description": "新的人类可读名称。" }, "url": { "type": "string", "format": "uri", "description": "新目标 URL。在应用内必须唯一。" }, "enabled": { "type": "boolean", "description": "设为 `false` 可暂停向此目标的投递而无需将其删除。" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "用于未来投递的新 payload 模式版本。" }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" } } }, "examples": { "Pause destination": { "value": { "enabled": false } }, "Add transaction events": { "value": { "subscribed_events": [ "status.updated", "data.updated", "transaction.created", "transaction.status.updated" ] } }, "Move target URL": { "value": { "label": "Production session webhooks v2", "url": "https://api.yourapp.com/webhooks/didit/v2" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"subscribed_events\": [\n \"status.updated\",\n \"data.updated\",\n \"transaction.created\"\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.update(\n \"11111111-2222-3333-4444-555555555555\",\n enabled=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.update(\"11111111-2222-3333-4444-555555555555\", {\n enabled: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsUpdateParams{\n\tEnabled: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WebhooksDestinationsUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().update(\"11111111-2222-3333-4444-555555555555\", WebhooksDestinationsUpdateParams.builder()\n .enabled(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->update('11111111-2222-3333-4444-555555555555', [\n 'enabled' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.update(\n \"11111111-2222-3333-4444-555555555555\",\n enabled: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new WebhooksDestinationsUpdateParams\n{\n Enabled = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新 Webhook 目标。响应体结构与 `GET /v3/webhook/destinations/{destination_uuid}/` 相同。", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "enabled": { "type": "boolean" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ] }, "secret_shared_key": { "type": "string" }, "secret_last4": { "type": "string", "description": "目标当前签名密钥的最后四位字符，以便您区分不同的密钥。不足以用于验证签名。" }, "previous_secret_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在 Business Console 中轮换目标的签名密钥后设置 24 小时。在此期间，向该目标进行的每次投递还会携带使用被替换密钥生成的 `X-Signature-Previous`、`X-Signature-V2-Previous` 和 `X-Signature-Simple-Previous`（请参阅[签名验证](/zh/integration/webhooks#签名验证)）。如果在过去 24 小时内未发生轮换，则为 `null`。" }, "subscribed_events": { "$ref": "#/components/schemas/WebhookSubscribedEvents" }, "created_by_email": { "type": "string", "nullable": true, "description": "创建该目标的 Business Console 成员的邮箱。通过 API 密钥创建的目标为 `null`。" }, "created_by_name": { "type": "string", "nullable": true, "description": "创建该目标的 Business Console 成员姓名。使用 API 密钥创建的目标为 `null`。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "health_status": { "type": "string", "enum": [ "healthy", "degraded", "failing" ], "description": "投递健康状态。`failing`：自该目标上次成功响应以来，已有 3 个或更多连续事件在首次投递尝试时失败（参见 `failing_streak`）。`degraded`：非 failing 状态，但在过去 24 小时内有一次投递尝试失败，且后续没有尝试成功投递该事件；成功投递该事件的重试或重新发送会清除此状态。`healthy`：均非上述情况。独立于 `enabled`。失败的尝试是指响应 HTTP 400 或以上，或者完全没有响应的尝试。" }, "failing_streak": { "type": "integer", "description": "在最近 30 天内，自该目标上次成功响应以来，首次投递尝试失败的连续事件数量。重试不计入，任何成功的尝试（包括重试或重新发送）都会结束该连续记录。自上次成功以来没有事件失败时为 `0`。" }, "failing_since": { "type": "string", "format": "date-time", "nullable": true, "description": "当前 `failing_streak` 中第一次失败尝试的时间。当 `failing_streak` 为 `0` 时为 `null`。" }, "last_success_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在过去 30 天内，目标上次以低于 400 的 HTTP 状态响应投递的时间。如果在此时间窗口内没有以低于 400 的 HTTP 状态响应，则为 `null`。" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "拥有该目标的应用的环境。" }, "summary": { "type": "object", "properties": { "total_deliveries": { "type": "integer" }, "failed_deliveries": { "type": "integer" }, "error_rate_percentage": { "type": "integer" }, "min_response_time_ms": { "type": "integer", "nullable": true }, "avg_response_time_ms": { "type": "integer", "nullable": true }, "max_response_time_ms": { "type": "integer", "nullable": true }, "last_delivery_at": { "type": "string", "format": "date-time", "nullable": true }, "metrics_window_days": { "type": "integer", "description": "其他汇总指标所覆盖的时间窗口长度（天）。始终为 `30`。" } }, "description": "最近 `metrics_window_days`（30）天的投递指标。`last_delivery_at` 为最近一次尝试的时间，无论其何时发生。" } } }, "examples": { "Paused": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": false, "webhook_version": "v3", "secret_shared_key": "tno2NTeRC1ZK3sBOYlBJDyEzBVENl3pQ1AcZyAW0xnQ", "secret_last4": "0xnQ", "previous_secret_expires_at": null, "subscribed_events": [ "status.updated", "data.updated" ], "created_by_email": null, "created_by_name": null, "created_at": "2026-01-04T08:00:00Z", "updated_at": "2026-05-17T11:02:55Z", "health_status": "healthy", "failing_streak": 0, "failing_since": null, "last_success_at": "2026-05-17T09:21:18Z", "environment": "live", "summary": { "total_deliveries": 12453, "failed_deliveries": 14, "error_rate_percentage": 0, "min_response_time_ms": 41, "avg_response_time_ms": 187, "max_response_time_ms": 2103, "last_delivery_at": "2026-05-17T09:21:18Z", "metrics_window_days": 30 } } } } } } }, "400": { "description": "验证失败（重复的 URL、事件列表为空/未知、请求体格式错误）。", "content": { "application/json": { "examples": { "Duplicate URL": { "value": { "url": [ "This webhook destination already exists for the application." ] } }, "Empty events": { "value": { "subscribed_events": [ "At least one subscribed event is required." ] } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。密钥缺失返回 `403`；密钥错误、已撤销或已过期返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "具有此 UUID 的目标不存在（或已被删除，或属于其他应用）。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "超出速率限制；请退避并重试。", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "删除 Webhook 目标", "description": "永久删除一个 Webhook 目标、其签名密钥及其整个投递日志。此操作无法撤销。系统不会向该目标的 URL 发送新的 Webhook；订阅相同事件的其他目标将继续接收这些事件。删除后，该目标不再出现在 `GET /v3/webhook/destinations/` 中，且 `/v3/webhook/destinations/{destination_uuid}/` 下的所有路由（包括其投递记录、某次投递的详情及其重新发送）均返回 404。该应用的旧版 `webhook_url` 将设置为保留的最早启用的目标的 URL，若无启用的目标保留则清空。再次调用 DELETE 返回 404。", "operationId": "delete_webhook_destination", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "要删除的 Webhook 目标的 UUID。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.webhooks.destinations.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.webhooks.destinations.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Webhooks.Destinations.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.webhooks().destinations().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.webhooks.destinations.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Webhooks.Destinations.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "目标、签名密钥和投递日志已永久删除。无响应体。" }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。密钥缺失返回 `403`；密钥错误、已撤销或已过期返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "应用不存在具有此 UUID 的目标（已删除或从未存在）。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "超出速率限制；请退避并重试。", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/wallet-screening/": { "post": { "summary": "筛查地址", "description": "为单个加密货币钱包/地址运行按需 AML 筛查，而无需创建交易。解析您应用配置的区块链分析提供商，同步筛查该地址，并返回规范化风险结果。LIGHTNING 仅在使用通过 Marketplace 添加的 Elliptic 或 Chainalysis BYOK 连接时可用。不会向交易表写入任何内容。每次成功的筛查将计费一次 AML 监控用量（沙盒应用不计费）。", "operationId": "screenWallet", "x-didit-sdk": { "resource": "wallet_screening", "method": "screen", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet_address" ], "properties": { "wallet_address": { "type": "string", "description": "要筛查的加密货币地址或网络标识符。必须与所选网络匹配（例如 EVM 链上以 `0x` 开头的 40 位十六进制字符地址）。别名：`address`。", "example": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a" }, "blockchain": { "type": "string", "description": "可选的网络标识符。省略时，网络将根据地址格式读取：`bc1`、`1` 和 `3` 开头的地址为比特币（BTC），`T` 开头的地址为波场（TRX），base58 公钥为 Solana（SOL）。`0x` 开头的地址在所有 EVM 网络上均有效，因此省略 `blockchain` 会返回 422 状态码，并在 `candidate_chains` 中列出候选网络。托管筛查支持 BTC、ETH、LTC、XRP、BCH、DOGE、TRX、SOL、MATIC、BNB、BASE (Base)、OP (Optimism)、ARB (Arbitrum One)、AVAX (Avalanche C-Chain)、ADA (Cardano)、XLM (Stellar) 和 HBAR (Hedera)。USDT 和 USDC 为旧版以太坊别名，不支持多网络搜索。关联提供商的覆盖范围各有不同。LIGHTNING 需要受支持的关联提供商。CELO (Celo)、MODE (Mode) 和 PLUME (Plume) 通过关联的 TRM Labs 账户进行筛查；托管筛查对它们会返回 400。别名：`currency`。", "enum": [ "BTC", "LIGHTNING", "ETH", "LTC", "XRP", "BCH", "DOGE", "TRX", "SOL", "MATIC", "BNB", "USDT", "USDC", "BASE", "OP", "ARB", "AVAX", "ADA", "XLM", "HBAR", "CELO", "MODE", "PLUME" ], "example": "ETH" }, "direction": { "type": "string", "description": "可选。该地址是作为入账（充值）还是出账（提现）交易对手进行筛查。接受 `inbound`、`outbound`、`deposit` 或 `withdrawal`。省略时默认为中立的转账前筛查。该参数仅作为上下文传递给提供商；它不会改变返回的 `risk_score`、`severity` 或 `source_of_funds`/`destination_of_funds` 明细，无论 `direction` 为何值，这两项明细均会返回。因此，更改或省略 `direction` 无需对地址重新进行筛查。", "enum": [ "inbound", "outbound", "deposit", "withdrawal" ] } } }, "example": { "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", "blockchain": "ETH" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/wallet-screening/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"wallet_address\": \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n \"blockchain\": \"ETH\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.wallet_screening.screen(\n wallet_address=\"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n blockchain=\"ETH\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.walletScreening.screen({\n wallet_address: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n blockchain: \"ETH\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.WalletScreening.Screen(ctx, didit.WalletScreeningScreenParams{\n\tWalletAddress: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n\tBlockchain: didit.Some(didit.WalletScreeningScreenParamsBlockchain(\"ETH\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WalletScreeningScreenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.walletScreening().screen(WalletScreeningScreenParams.builder()\n .walletAddress(\"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\")\n .blockchain(WalletScreeningScreenParams.Blockchain.of(\"ETH\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "walletScreening->screen([\n 'wallet_address' => '0x94f1b9b64e2932f6a2db338f616844400cd58e8a',\n 'blockchain' => 'ETH',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.wallet_screening.screen(\n wallet_address: \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n blockchain: \"ETH\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.WalletScreening.ScreenAsync(new WalletScreeningScreenParams\n{\n WalletAddress = \"0x94f1b9b64e2932f6a2db338f616844400cd58e8a\",\n Blockchain = new WalletScreeningScreenParamsBlockchain(\"ETH\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "标准化的钱包筛查结果。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletScreeningResult" }, "example": { "provider": "merklescience", "screening_type": "WALLET_SCREENING", "risk_score": 95, "severity": "CRITICAL", "status": "SCREENED", "summary": "Merkle Science risk: Critical (5/5). SANCTIONS HIT. Dominant risk: sanctioned. Driven by: the address is attributed to Sanctions / OFAC (Example Sanctions)", "wallet_address": "0x94f1b9b64e2932f6a2db338f616844400cd58e8a", "transaction_hash": null, "blockchain": "ETH", "block_timestamp": null, "total_value_usd": null, "fee_usd": null, "sender_rows": [], "receiver_rows": [], "transaction_flows": [], "transaction_flows_status": null, "transaction_flows_error": null, "source_of_funds": [ { "category": "sanctioned", "percentage": 100.0, "amount_usd": 9813695.0, "entity_name": "Example Sanctions", "entity_type": "Sanctions", "entity_subtype": "OFAC", "hops": null, "description": "Sanctions / OFAC", "is_direct": true, "exposure_direction": "incoming", "exposure_type": "direct", "provider_entity_id": "118885", "provider_entity_type_id": "30", "provider_entity_subtype_id": "125", "country": "", "raw_amount": null, "raw_currency": null } ], "destination_of_funds": [ { "category": "defi", "percentage": 84.824453, "amount_usd": 7783414.38, "entity_name": "Example DeFi 7", "entity_type": "DeFi", "entity_subtype": "Bridges", "hops": null, "description": "DeFi / Bridges", "is_direct": false, "exposure_direction": "outgoing", "exposure_type": "indirect", "provider_entity_id": "118459", "provider_entity_type_id": "33", "provider_entity_subtype_id": "143", "country": "", "raw_amount": null, "raw_currency": null }, { "category": "defi", "percentage": 15.175547, "amount_usd": 1392494.37, "entity_name": "Example DeFi 2", "entity_type": "DeFi", "entity_subtype": "Yield Aggregator", "hops": null, "description": "DeFi / Yield Aggregator", "is_direct": false, "exposure_direction": "outgoing", "exposure_type": "indirect", "provider_entity_id": "90192", "provider_entity_type_id": "33", "provider_entity_subtype_id": "142", "country": "", "raw_amount": null, "raw_currency": null } ], "counterparty_connections": [ { "entity_name": "Example Sanctions", "entity_type": "Sanctions", "entity_subtype": "OFAC", "risk_level": "critical", "categories": [ "sanctioned" ], "received_usd": null, "sent_usd": null, "received_hops": null, "sent_hops": null, "percentage": 0.0, "is_direct": true, "country": null, "provider_entity_id": null }, { "entity_name": "Example Sanctions", "entity_type": "Sanctions", "entity_subtype": "OFAC", "risk_level": "critical", "categories": [ "sanctioned" ], "received_usd": null, "sent_usd": null, "received_hops": null, "sent_hops": null, "percentage": 0.0, "is_direct": true, "country": null, "provider_entity_id": null } ], "network_nodes": [], "network_edges": [], "sanctions_hit": true, "pep_counterparty": null, "dominant_risk_category": "sanctioned", "risk_factors": [ { "source": "attribution", "category": "sanctioned", "label": "Sanctions / OFAC", "entity_name": "Example Sanctions", "direction": "attribution", "exposure_type": "attribution", "amount_usd": null, "percentage": 0.0, "is_high_risk": true, "description": "the address is attributed to Sanctions / OFAC (Example Sanctions)" }, { "source": "exposure", "category": "sanctioned", "label": "Sanctions / OFAC", "entity_name": "Example Sanctions", "direction": "incoming", "exposure_type": "direct", "amount_usd": 9813695.0, "percentage": 51.679304, "is_high_risk": true, "description": "51.6793% direct incoming exposure to Sanctions / OFAC (Example Sanctions)" }, { "source": "exposure", "category": "defi", "label": "DeFi / Bridges", "entity_name": "Example DeFi 7", "direction": "outgoing", "exposure_type": "indirect", "amount_usd": 7783414.38, "percentage": 40.987766, "is_high_risk": false, "description": "40.9878% indirect outgoing exposure to DeFi / Bridges (Example DeFi 7)" }, { "source": "exposure", "category": "defi", "label": "DeFi / Yield Aggregator", "entity_name": "Example DeFi 2", "direction": "outgoing", "exposure_type": "indirect", "amount_usd": 1392494.37, "percentage": 7.33293, "is_high_risk": false, "description": "7.33293% indirect outgoing exposure to DeFi / Yield Aggregator (Example DeFi 2)" } ], "raw_response": { "...": "provider-specific details" }, "report_signature": "" } } } }, "400": { "description": "验证错误 — 钱包地址格式错误、缺少 `wallet_address`、不受支持的 `blockchain`、地址格式未指明网络时省略了 `blockchain`，或者在未建立 Elliptic 或 Chainalysis BYOK Marketplace 连接的情况下使用了 LIGHTNING。" }, "401": { "description": "`x-api-key` 缺失或无效。" }, "409": { "description": "该应用未配置 AML 提供商，或配置的提供商尚不支持钱包筛查。请先配置交易监控。" }, "422": { "description": "对于 `0x` 地址省略了 `blockchain`，所有 EVM 网络均共享该地址格式。未进行任何筛查或计费；请将 `blockchain` 设置为 `candidate_chains` 之一后重新发送。", "content": { "application/json": { "schema": { "type": "object", "properties": { "blockchain": { "type": "array", "items": { "type": "string" }, "example": [ "A 0x address is valid on every EVM chain. Send blockchain as one of: ETH, BNB, MATIC, BASE, ARB, OP, CELO, MODE, PLUME." ] }, "candidate_chains": { "type": "array", "items": { "type": "string" }, "example": [ "ETH", "BNB", "MATIC", "BASE", "ARB", "OP", "CELO", "MODE", "PLUME" ] } } } } } }, "502": { "description": "AML 提供商无法完成筛查。请稍后重试。" } } } }, "/v3/wallet-screening/pdf/": { "post": { "summary": "将钱包筛查结果渲染为 PDF", "description": "`POST /v3/wallet-screening/` 的无状态配套接口：重新提交该 endpoint 返回的完全相同的 JSON 请求体（包括其添加的 `report_signature`），即可获取相同结果的 Didit 品牌 PDF。此操作不会调用任何服务商，不产生计费，也不会持久化存储；仅重新渲染 Didit 已经生成的结果。该签名将 PDF 与未修改的结果绑定：在重新提交前修改 `risk_score`、`severity`、`sanctions_hit` 或任何其他签名字段将导致请求失败并返回 `400`。", "operationId": "screenWalletPdf", "x-didit-sdk": { "resource": "wallet_screening", "method": "screen_pdf", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "description": "由 `POST /v3/wallet-screening/` 返回的未经修改的 JSON 对象，包括 `report_signature`。", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/WalletScreeningResult" } ], "required": [ "report_signature" ], "description": "数据结构与 `POST /v3/wallet-screening/` 响应相同，请逐字传回该响应主体，包括 `report_signature`。" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "# $RESULT is the saved JSON body from POST /v3/wallet-screening/\ncurl -X POST 'https://verification.didit.me/v3/wallet-screening/pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d \"$RESULT\" \\\n -o wallet_screening_report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.wallet_screening.screen_pdf(\n provider=\"your-provider\",\n screening_type=\"WALLET_SCREENING\",\n risk_score=1,\n severity=\"UNKNOWN\",\n status=\"SCREENED\",\n summary=\"your-summary\",\n wallet_address=\"your-wallet-address\",\n blockchain=\"your-blockchain\",\n source_of_funds=[{}],\n destination_of_funds=[{}],\n counterparty_connections=[{}],\n sanctions_hit=True,\n dominant_risk_category=\"your-dominant-risk-category\",\n report_signature=\"your-report-signature\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.walletScreening.screenPdf({\n provider: \"your-provider\",\n screening_type: \"WALLET_SCREENING\",\n risk_score: 1,\n severity: \"UNKNOWN\",\n status: \"SCREENED\",\n summary: \"your-summary\",\n wallet_address: \"your-wallet-address\",\n blockchain: \"your-blockchain\",\n source_of_funds: [{}],\n destination_of_funds: [{}],\n counterparty_connections: [{}],\n sanctions_hit: true,\n dominant_risk_category: \"your-dominant-risk-category\",\n report_signature: \"your-report-signature\",\n});\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.WalletScreening.ScreenPDF(ctx, didit.WalletScreeningResultParam{\n\tProvider: \"your-provider\",\n\tScreeningType: \"WALLET_SCREENING\",\n\tRiskScore: 1,\n\tSeverity: \"UNKNOWN\",\n\tStatus: \"SCREENED\",\n\tSummary: \"your-summary\",\n\tWalletAddress: \"your-wallet-address\",\n\tBlockchain: \"your-blockchain\",\n\tSourceOfFunds: []didit.WalletScreeningResultParamSourceOfFunds{{}},\n\tDestinationOfFunds: []didit.WalletScreeningResultParamDestinationOfFunds{{}},\n\tCounterpartyConnections: []didit.WalletScreeningResultParamCounterpartyConnections{{}},\n\tSanctionsHit: true,\n\tDominantRiskCategory: didit.String(\"your-dominant-risk-category\"),\n\tReportSignature: \"your-report-signature\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.WalletScreeningResult;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.walletScreening().screenPdf(WalletScreeningResult.builder()\n .provider(\"your-provider\")\n .screeningType(WalletScreeningResult.ScreeningType.of(\"WALLET_SCREENING\"))\n .riskScore(1L)\n .severity(WalletScreeningResult.Severity.of(\"UNKNOWN\"))\n .status(WalletScreeningResult.Status.of(\"SCREENED\"))\n .summary(\"your-summary\")\n .walletAddress(\"your-wallet-address\")\n .blockchain(\"your-blockchain\")\n .sourceOfFunds(List.of(WalletScreeningResult.SourceOfFunds.builder()\n .build()))\n .destinationOfFunds(List.of(WalletScreeningResult.DestinationOfFunds.builder()\n .build()))\n .counterpartyConnections(List.of(WalletScreeningResult.CounterpartyConnections.builder()\n .build()))\n .sanctionsHit(true)\n .dominantRiskCategory(\"your-dominant-risk-category\")\n .reportSignature(\"your-report-signature\")\n .build())\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "walletScreening->screenPdf([\n 'provider' => 'your-provider',\n 'screening_type' => 'WALLET_SCREENING',\n 'risk_score' => 1,\n 'severity' => 'UNKNOWN',\n 'status' => 'SCREENED',\n 'summary' => 'your-summary',\n 'wallet_address' => 'your-wallet-address',\n 'blockchain' => 'your-blockchain',\n 'source_of_funds' => [[]],\n 'destination_of_funds' => [[]],\n 'counterparty_connections' => [[]],\n 'sanctions_hit' => true,\n 'dominant_risk_category' => 'your-dominant-risk-category',\n 'report_signature' => 'your-report-signature',\n]);\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.wallet_screening.screen_pdf(\n provider: \"your-provider\",\n screening_type: \"WALLET_SCREENING\",\n risk_score: 1,\n severity: \"UNKNOWN\",\n status: \"SCREENED\",\n summary: \"your-summary\",\n wallet_address: \"your-wallet-address\",\n blockchain: \"your-blockchain\",\n source_of_funds: [{}],\n destination_of_funds: [{}],\n counterparty_connections: [{}],\n sanctions_hit: true,\n dominant_risk_category: \"your-dominant-risk-category\",\n report_signature: \"your-report-signature\"\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.WalletScreening.ScreenPdfAsync(new WalletScreeningResult\n{\n Provider = \"your-provider\",\n ScreeningType = \"WALLET_SCREENING\",\n RiskScore = 1,\n Severity = \"UNKNOWN\",\n Status = \"SCREENED\",\n Summary = \"your-summary\",\n WalletAddress = \"your-wallet-address\",\n Blockchain = \"your-blockchain\",\n SourceOfFunds = new WalletScreeningResultSourceOfFunds[] { new() },\n DestinationOfFunds = new WalletScreeningResultDestinationOfFunds[] { new() },\n CounterpartyConnections = new WalletScreeningResultCounterpartyConnections[] { new() },\n SanctionsHit = true,\n DominantRiskCategory = \"your-dominant-risk-category\",\n ReportSignature = \"your-report-signature\",\n});\nawait content.SaveToAsync(\"download.pdf\");" } ], "responses": { "200": { "description": "渲染生成的 PDF 文档，直接以二进制 `application/pdf` 形式返回，没有 JSON 包装。", "headers": { "Content-Disposition": { "description": "`attachment; filename=wallet_screening_{address}.pdf`，派生自重新提交的结果中的 `wallet_address`（或 `transaction_hash`）。", "schema": { "type": "string", "example": "attachment; filename=wallet_screening_0x28c6c06298d514db0899.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "请求体不是与钱包筛查结果结构匹配的 JSON 对象，或者 `report_signature` 缺失或与重新提交的字段不匹配（在重新提交前被编辑或截断）。", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Not an object": { "value": { "non_field_errors": [ "Expected a JSON object matching a wallet-screening result." ] } }, "Missing or invalid signature": { "value": { "report_signature": [ "This wallet-screening result is missing or fails its report signature - repost the exact JSON returned by the wallet-screening endpoint, unmodified." ] } } } } } }, "401": { "description": "`x-api-key` 缺失或无效。" } } } }, "/v3/transactions/": { "get": { "summary": "列出交易", "description": "分页的受监控交易列表，最新优先（`txn_date` 降序）。`count` 上限为 100；请使用 `total_transactions` 获取真实的行计数。此 endpoint 不支持过滤或搜索参数。", "operationId": "listTransactions", "x-didit-sdk": { "resource": "transactions", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "页面大小。省略时默认为 50。虽无强制上限，但为降低延迟建议保持较小的页面大小。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "要返回的第一条记录的从零开始的偏移量。建议跟随上一页的 `next` URL。" }, { "name": "travel_rule_status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "仅返回其 Travel Rule 转账处于此确切状态（例如 `ON_HOLD` 或 `AWAITING_COUNTERPARTY`）的交易。`count` 会遵循此过滤器；`total_transactions` 仍会统计应用中的所有交易。" }, { "name": "assignee", "in": "query", "required": false, "schema": { "type": "string" }, "description": "以逗号分隔；交易满足其中任意值即匹配。`unassigned` 表示尚未被任何人领取的案件，`rules` 表示规则在没有审核员的情况下自行做出的决策，成员邮箱则匹配分配给该审核员的案件。`me` 代表当前登录的控制台审核员，因此 API 密钥发送 `me` 将收到 `400`。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.ListAutoPaging(ctx, didit.TransactionsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页交易摘要列表，最新优先。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "匹配交易的上限计数（100 笔以内准确，超过则设上限）。分页时请使用 `total_transactions` 获取真实计数。" }, "next": { "type": "string", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "total_transactions": { "type": "integer", "description": "该应用（未删除的）交易的确切总数。在分页响应中提供。" }, "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Didit 交易的稳定标识符。在详情/备注/关联调用中用作 `{transaction_id}`。" }, "transaction_number": { "type": "integer", "description": "控制台中显示的应用范围内连续交易序号（例如 `4123`）。" }, "txn_id": { "type": "string", "description": "创建调用时由客户提供的标识符（最多 128 个字符）。每个应用唯一。" }, "transaction_type": { "type": "string", "description": "存储的顶级类别：`finance`、`kyc`、`travelRule`、`userPlatformEvent`、`gamblingBet`、`gamblingLimitChange`、`gamblingBonusChange`、`auditTrailEvent`。请注意，即使以 snake_case 提交，包含多个单词的值也会以 camelCase 形式返回。" }, "action_type": { "type": "string", "description": "类别内的子类型（例如 `deposit`、`withdrawal`、`transfer`）。" }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "当前监控裁决结果。" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "相对于主体的方向。无论提交时的大小写如何，均以大写形式存储。" }, "amount": { "type": "string", "description": "作为十进制字符串的交易金额，已去除末尾零（例如 `\"1500\"`、`\"0.5\"`、`\"0.123456789012345678\"`）。最多 18 位小数。" }, "currency": { "type": "string", "description": "`amount` 的货币代码。接受任何 ISO 4217 字母代码（例如 `EUR`、`USD`、`NGN`）以及加密资产符号（例如 `BTC`）。建议使用当前流通的代码。并非每个接受的代码都有汇率：当该代码没有可用汇率时（例如 ISO 会计单位 `XSU`，或 Didit 未定价的加密资产符号），自动换算将失败，并且 `preferred_currency_amount` 将返回 null，除非请求提供了预先换算的 `amount_in_default_currency`。" }, "preferred_currency_amount": { "type": "string", "nullable": true, "description": "`amount` 在可用时折算为应用的首选货币。" }, "preferred_currency_code": { "type": "string", "nullable": true, "description": "用于 `preferred_currency_amount` 的首选币种代码：应用的基准币种，任何当前流通的 ISO 4217 代码。若该币种代码没有可用的汇率，`preferred_currency_amount` 将保持为 null，除非请求中提供了预先换算的 `amount_in_default_currency`。" }, "payment_details": { "type": "string", "nullable": true, "description": "提交内容中的自由文本付款参考号或附言。" }, "score": { "type": "integer", "description": "风险评分（通常为 0–100）。数值越高 = 风险越大。" }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "由规则/提供商设置的分类风险严重程度（`UNKNOWN`、`LOW`、`MEDIUM`、`HIGH`、`CRITICAL`）。在设置该值之前为 `null`。" }, "subject_name": { "type": "string", "nullable": true, "description": "`APPLICANT` 方的姓名。" }, "subject_vendor_data": { "type": "string", "nullable": true, "description": "您为申请人指定的内部用户/企业标识符。" }, "subject_country": { "type": "string", "nullable": true, "description": "申请人的国家/地区代码，来自提交的 `address.country`（通常为 ISO 3166-1 alpha-3）。" }, "counterparty_name": { "type": "string", "nullable": true, "description": "`COUNTERPARTY` 方的姓名（若有）。" }, "counterparty_vendor_data": { "type": "string", "nullable": true, "description": "您为交易对手指定的内部标识符。" }, "counterparty_country": { "type": "string", "nullable": true, "description": "交易对手的国家/地区代码，来自提交的 `address.country`。" }, "tags": { "type": "array", "description": "附加到交易的标签（手动或通过规则）。", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "该标签是 Didit 预设还是自定义标签。" } } } }, "txn_date": { "type": "string", "format": "date-time", "description": "交易发生的时间（来自创建时的 `transaction_at`）。" }, "created_at": { "type": "string", "format": "date-time", "description": "Didit 记录提交的时间。" }, "decision_reason_code": { "type": "string", "nullable": true, "description": "当前 `status` 的机器可读原因（例如 `WALLET_HIGH_RISK`）。" }, "decision_reason_label": { "type": "string", "nullable": true, "description": "`decision_reason_code` 的便于人类阅读的标签。" }, "assigned_to_name": { "type": "string", "nullable": true, "description": "分配给此交易的 Console 审核员显示名称。" }, "travel_rule_status": { "type": "string", "nullable": true, "description": "交易的 Travel Rule 转账状态（例如 `COMPLETED`），若无则为 `null`。" }, "travel_rule": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TransactionTravelRule" } ], "description": "交易的 Travel Rule 转账，与 `GET /v3/transactions/{transaction_id}/` 中的 `travel_rule` 数据块相同；当交易没有该项时为 `null`。" } } } } } }, "examples": { "Single transaction": { "value": { "count": 1, "next": null, "previous": null, "total_transactions": 1, "results": [ { "uuid": "abcdef12-3456-4890-abcd-ef1234567890", "transaction_number": 4123, "txn_id": "your-txn-2026-05-17-001", "transaction_type": "finance", "action_type": "withdrawal", "status": "IN_REVIEW", "direction": "OUTBOUND", "amount": "1500", "currency": "EUR", "preferred_currency_amount": "1620.45", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "txn_date": "2026-05-17T08:42:00Z", "created_at": "2026-05-17T08:42:11Z", "score": 78, "severity": "HIGH", "decision_reason_code": "WALLET_HIGH_RISK", "decision_reason_label": "Destination wallet flagged as high risk", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "Manual review", "color": "#F59E0B", "description": null, "source": "custom" } ], "subject_name": "Maria Garcia", "subject_vendor_data": "user-12345", "counterparty_name": null, "counterparty_vendor_data": null, "counterparty_country": null, "subject_country": null, "assigned_to_name": "Alex Reviewer", "travel_rule_status": null, "travel_rule": null } ] } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法列出此应用的交易。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建交易", "description": "提交交易以进行同步 AML/风险监控。交易创建时的状态为 `APPROVED`，随后您的规则（以及适用的加密货币筛查）以内联方式运行，并可能将返回的 `status` 更改为 `IN_REVIEW` 或 `DECLINED`。**`transaction_id` 是您的幂等性密钥**（最多 128 个字符，每个应用唯一）；重复使用将返回 400。生产环境应用在成功时会派发 `transaction.created` Webhook。沙盒应用不计费，且不会发出 `transaction.created` 或 `transaction.status.updated` Webhook。沙盒 Travel Rule 交换确实会发出带有 `environment: sandbox` 的 `travel_rule.status.updated` Webhook。在联系任何交易对手之前，Travel Rule 转账即已存储并返回：`travel_rule.status` 返回为 `AWAITING_COUNTERPARTY`（低于阈值时为 `NOT_APPLICABLE`，声明的自托管钱包为 `UNCONFIRMED_OWNERSHIP`，当对方钱包是您自己的已验证钱包时为 `COMPLETED`），且 `travel_rule.protocol` 为 null。随后 Didit 选择通道并发送交换信息，转账后续的每一次状态变更（包括没有通道能触达交易对手时的 `COUNTERPARTY_VASP_NOT_FOUND`）都会以 `travel_rule.status.updated` Webhook 形式送达。当通道或状态发生变化时，您的规则会再次运行。", "operationId": "createTransaction", "tags": [ "Transactions" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"transaction_id\": \"your-txn-2026-05-17-001\",\n \"transaction_category\": \"finance\",\n \"transaction_details\": {\n \"direction\": \"outbound\",\n \"amount\": 1500,\n \"currency\": \"EUR\",\n \"action_type\": \"withdrawal\"\n },\n \"subject\": {\n \"entity_type\": \"individual\",\n \"vendor_data\": \"user-12345\",\n \"full_name\": \"Maria Garcia\"\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.create(\n transaction_id=\"your-txn-2026-05-17-001\",\n transaction_category=\"finance\",\n transaction_details={\n \"direction\": \"outbound\",\n \"amount\": 1500.0,\n \"currency\": \"EUR\",\n \"action_type\": \"withdrawal\",\n },\n subject={\n \"entity_type\": \"individual\",\n \"vendor_data\": \"user-12345\",\n \"full_name\": \"Maria Garcia\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.create({\n transaction_id: \"your-txn-2026-05-17-001\",\n transaction_category: \"finance\",\n transaction_details: {\n direction: \"outbound\",\n amount: 1500.0,\n currency: \"EUR\",\n action_type: \"withdrawal\",\n },\n subject: {\n entity_type: \"individual\",\n vendor_data: \"user-12345\",\n full_name: \"Maria Garcia\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Create(ctx, didit.TransactionsCreateParams{\n\tTransactionID: \"your-txn-2026-05-17-001\",\n\tTransactionCategory: \"finance\",\n\tTransactionDetails: didit.TransactionsCreateParamsTransactionDetails{\n\t\tDirection: \"outbound\",\n\t\tAmount: 1500.0,\n\t\tCurrency: \"EUR\",\n\t\tActionType: didit.String(\"withdrawal\"),\n\t},\n\tSubject: didit.TransactionsCreateParamsSubject{\n\t\tEntityType: didit.String(\"individual\"),\n\t\tVendorData: \"user-12345\",\n\t\tFullName: \"Maria Garcia\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().create(TransactionsCreateParams.builder()\n .transactionId(\"your-txn-2026-05-17-001\")\n .transactionCategory(TransactionsCreateParams.TransactionCategory.of(\"finance\"))\n .transactionDetails(TransactionsCreateParams.TransactionDetails.builder()\n .direction(TransactionsCreateParams.TransactionDetails.Direction.of(\"outbound\"))\n .amount(1500.0)\n .currency(\"EUR\")\n .actionType(\"withdrawal\")\n .build())\n .subject(TransactionsCreateParams.Subject.builder()\n .entityType(\"individual\")\n .vendorData(\"user-12345\")\n .fullName(\"Maria Garcia\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->create([\n 'transaction_id' => 'your-txn-2026-05-17-001',\n 'transaction_category' => 'finance',\n 'transaction_details' => [\n 'direction' => 'outbound',\n 'amount' => 1500.0,\n 'currency' => 'EUR',\n 'action_type' => 'withdrawal',\n ],\n 'subject' => [\n 'entity_type' => 'individual',\n 'vendor_data' => 'user-12345',\n 'full_name' => 'Maria Garcia',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.create(\n transaction_id: \"your-txn-2026-05-17-001\",\n transaction_category: \"finance\",\n transaction_details: {\n direction: \"outbound\",\n amount: 1500.0,\n currency: \"EUR\",\n action_type: \"withdrawal\",\n },\n subject: {\n entity_type: \"individual\",\n vendor_data: \"user-12345\",\n full_name: \"Maria Garcia\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.CreateAsync(new TransactionsCreateParams\n{\n TransactionId = \"your-txn-2026-05-17-001\",\n TransactionCategory = \"finance\",\n TransactionDetails = new()\n {\n Direction = \"outbound\",\n Amount = 1500.0,\n Currency = \"EUR\",\n ActionType = \"withdrawal\",\n },\n Subject = new()\n {\n EntityType = \"individual\",\n VendorData = \"user-12345\",\n FullName = \"Maria Garcia\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "description": "您对此交易的唯一标识符（最多 128 个字符）。", "example": "your-txn-2026-05-17-001" }, "transaction_at": { "type": "string", "format": "date-time", "description": "交易发生的时间。如果省略，则默认为当前时间。" }, "time_zone": { "type": "string", "description": "IANA 时区标识符，例如 `Europe/Madrid`。" }, "transaction_category": { "type": "string", "description": "交易类别。也接受驼峰命名别名（`travelRule`、`userPlatformEvent`、`gamblingBet` 等）；对于多词类别，存储/回显的值为 camelCase。", "example": "finance", "enum": [ "finance", "kyc", "travel_rule", "user_event", "audit_trail_event", "gambling_bet", "gambling_limit_change", "gambling_bonus_change", "travelRule" ] }, "transaction_details": { "type": "object", "description": "交易的核心财务详情。", "required": [ "direction", "amount", "currency" ], "properties": { "direction": { "type": "string", "description": "相对于主体的交易方向。不区分大小写；接受 `in`/`out` 作为别名。以大写形式返回（`INBOUND`/`OUTBOUND`）。", "example": "outbound", "enum": [ "inbound", "outbound", "in", "out" ] }, "amount": { "type": "number", "description": "交易金额（最多 18 位小数）。如果需要精确度，请将其作为十进制字符串发送（例如 `\"0.123456789012345678\"`）：JSON 数字会先解析为二进制浮点数，因此在存储金额之前，超过约 15 位有效数字的位数会被四舍五入。必须为零或更大：方向包含符号，负金额将返回 `400`。", "example": 1500 }, "currency": { "type": "string", "description": "货币代码。接受任何 ISO 4217 字母代码（例如 `EUR`、`USD`、`NGN`）以及加密资产符号（例如 `BTC`）。建议使用当前流通的代码。并非每个接受的代码都有汇率：当该代码没有可用汇率时（例如 ISO 会计单位 `XSU`，或 Didit 未定价的加密资产符号），自动换算将失败，并且 `preferred_currency_amount` 将返回 null，除非请求提供了预先换算的 `amount_in_default_currency`。", "example": "EUR" }, "currency_kind": { "type": "string", "description": "币种是 `fiat` 还是 `crypto`。" }, "amount_in_default_currency": { "type": "number", "nullable": true, "description": "以默认币种计的预先换算金额。若省略，将尝试自动进行外汇换算。必须为零或更大值。" }, "default_currency": { "type": "string", "description": "转换金额的默认货币代码。任何当前流通的 ISO 4217 代码。" }, "payment_details": { "type": "string", "nullable": true, "description": "自由文本付款参考号或附言。" }, "payment_reference_id": { "type": "string", "nullable": true, "description": "外部支付系统参考标识。对于加密货币 AML 交易哈希筛查，请发送区块链交易哈希，并在 `subject.payment_method.account_id` 中提供相关地址。" }, "action_type": { "type": "string", "nullable": true, "description": "交易的子类型，例如 `deposit`、`withdrawal`、`transfer`。" }, "crypto_params": { "type": "object", "description": "加密网络选择，独立于货币（资产符号）。记录自定义 token 符号并不能保证其合约的交易哈希覆盖率。", "properties": { "crypto_chain": { "type": "string", "description": "用于筛查的实际网络。托管筛查支持 BTC、ETH、LTC、XRP、BCH、DOGE、TRX、SOL、MATIC、BNB、BASE (Base)、OP (Optimism)、ARB (Arbitrum One)、AVAX (Avalanche C-Chain)、ADA (Cardano)、XLM (Stellar) 以及 HBAR (Hedera)。也接受常见网络名称，例如针对 MATIC 的 POLYGON 或 POL、针对 BNB 的 BSC 以及针对 TRX 的 TRON。对于多网络代币，请务必指定此项。当带有 0x 交易哈希的 USDT、USDC 或 ETH 缺失此项时，Didit 会在 Ethereum、BNB Chain、Polygon、Base、Arbitrum 和 Optimism 上查找该哈希，并在找到它的网络上进行筛查；如果所有网络均未找到，则不对该交易进行筛查，custom_values.aml_screening_status 为 FAILED，原因记录在 custom_values.aml_screening_error 中。当通过钱包筛查（无交易哈希）的 USDT 或 USDC 缺失此项时，Tron 地址在 Tron 上筛查，Solana 地址在 Solana 上筛查，0x 地址则在上述六个网络中首个发送过交易或持有该代币的网络上筛查，若在所有这些网络上均不活跃，则在 Ethereum 上筛查。已连接提供商的覆盖范围各不相同；LIGHTNING 需要受支持的已连接提供商。", "example": "BASE" } } } } }, "subject": { "type": "object", "description": "交易的主体（申请人）。", "required": [ "vendor_data", "full_name" ], "properties": { "entity_type": { "type": "string", "description": "主体类型：`individual` 或 `company`。" }, "vendor_data": { "type": "string", "description": "您的内部用户/企业标识符。", "example": "user-12345" }, "full_name": { "type": "string", "description": "主体的姓名。", "example": "Maria Garcia" }, "first_name": { "type": "string", "description": "主体的名。" }, "last_name": { "type": "string", "description": "主体的姓氏。" }, "date_of_birth": { "type": "string", "format": "date", "description": "出生日期（YYYY-MM-DD）。" }, "address": { "type": "object", "description": "地址对象。", "properties": { "country": { "type": "string", "description": "国家/地区代码（推荐使用 ISO 3166-1 alpha-3）。复制到该主体的 `country_code`。" }, "town": { "type": "string" }, "state": { "type": "string" }, "street": { "type": "string" }, "post_code": { "type": "string" } } }, "institution_details": { "type": "object", "description": "机构详情（针对机构主体）。", "properties": { "name": { "type": "string" }, "code": { "type": "string" }, "address": { "type": "object" } } }, "device_context": { "type": "object", "description": "在交易时采集的设备上下文。browser_family 和 platform 必须作为明确的顶级键发送，它们不是从 user_agent 派生的。请求上也接受驼峰命名别名 device。", "properties": { "fingerprint": { "type": "string", "description": "唯一设备指纹。" }, "persistent_device_id": { "type": "string", "description": "跨会话的稳定设备标识符（v2 指纹架构）。" }, "user_agent": { "type": "string", "description": "浏览器或应用的 user agent 字符串。驼峰式命名别名：userAgent。" }, "browser_family": { "type": "string", "description": "浏览器家族（例如 Chrome、Firefox、Safari）。必须显式发送 — 它不会从 user_agent 推导。驼峰式命名别名：browserFamily。" }, "browser_version": { "type": "string", "description": "浏览器版本字符串。必须显式发送。驼峰式命名别名：browserVersion。" }, "platform": { "type": "string", "description": "平台标识符（web、ios、android、macos、windows、linux）。必须显式发送 — 不会从 user_agent 推断得出。" }, "os_family": { "type": "string", "description": "操作系统系列（例如 iOS、Android、Windows）。驼峰命名别名：osFamily。" }, "os_version": { "type": "string", "description": "操作系统版本字符串。驼峰命名别名：osVersion。" }, "accept_language": { "type": "string", "description": "Accept-Language 请求头的值。CamelCase 别名：acceptLang。" }, "session_id": { "type": "string", "description": "用户当前会话的会话标识符。存储在元数据中。CamelCase 别名：sessionId。" }, "session_age_ms": { "type": "number", "description": "交易发生时用户会话的时长（毫秒）。驼峰式别名：sessionAgeMs。" }, "network_context": { "type": "object", "description": "包含 IP 地址和地理位置的网络上下文。顶层 ipInfo 块也会合并到此对象中。", "properties": { "ip_address": { "type": "string", "description": "客户端 IP 地址。驼峰命名别名：ip。" }, "ip_country_code": { "type": "string", "description": "基于地理位置解析的 IP 所在国家/地区（ISO 3166-1 alpha-3）。驼峰命名别名：countryCode3。" }, "latitude": { "type": "number", "description": "该 IP 的地理纬度。大驼峰（CamelCase）别名：lat。" }, "longitude": { "type": "number", "description": "该 IP 的地理经度。大驼峰（CamelCase）别名：lon。" } } } } }, "payment_method": { "type": "object", "description": "主体使用的支付方式。", "properties": { "method_type": { "type": "string", "description": "支付方式类型：`bank_card`、`bank_account`、`crypto_wallet`、`ewallet`、`unhosted_wallet`、`other`。" }, "account_id": { "type": "string", "description": "账户标识符（例如 IBAN、地址）。对于加密筛查，此处应包含该参与者的地址。入站交易哈希筛查需要该主体的服务/客户充值地址。出站筛查使用交易对手的目标钱包。在比特币或 Lightning 上的加密转账中，它可能是 Lightning 付款请求（BOLT11 发票、BOLT12 报价、LNURL）或 Lightning 地址：Didit 将其指定的收款人存储为账户（未指定时为 \"\"），并将请求内容存储在 Travel Rule 转账的 `chain_details.lightning` 上。存储后最多 255 个字符。在比特币或 Lightning 上的加密转账中，它可能是 Lightning 付款请求（BOLT11 发票、BOLT12 报价、LNURL）或 Lightning 地址：Didit 将其指定的收款人存储为账户（未指定时为 \"\"），并将请求内容存储在 Travel Rule 转账的 `chain_details.lightning` 上。存储后最多 255 个字符。" }, "memo": { "type": "string", "maxLength": 256, "description": "在 memo 网络（XRP、XLM、EOS、ATOM、HBAR）上作为钱包一部分的目标标签或 memo。在单个共享交易所地址上，每个 memo 都是独立的支付方式。XRP：目标标签，0 到 4294967295 之间的整数（接受 JSON 数字）。XLM：最多 28 字节的文本 memo、64 位 ID 或十六进制的 32 字节哈希。EOS：最多 256 字节。ATOM：最多 256 个字符。HBAR：最多 100 字节。Bitcoin、EVM、Solana、Tron、Litecoin、Bitcoin Cash、Dogecoin 和 Lightning 钱包不接受 memo：传入 memo 会返回 `400`。别名：`destinationTag` 或 `destination_tag`。" }, "issuing_country": { "type": "string", "description": "签发方的 ISO 3166-1 alpha-3 国家/地区代码。" } } } } }, "counterparty": { "type": "object", "description": "交易对手（可选）。", "properties": { "entity_type": { "type": "string", "description": "主体类型：`individual` 或 `company`。" }, "vendor_data": { "type": "string", "description": "您为交易对手指定的内部标识符。" }, "full_name": { "type": "string", "description": "交易对手的姓名。" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "address": { "type": "object", "description": "包含 `country`（ISO 3166-1 alpha-3）的地址对象。" }, "institution_details": { "type": "object" }, "device_context": { "type": "object", "description": "交易对手的设备上下文。browser_family 和 platform 必须作为显式顶层键发送，它们不会从 user_agent 中派生。", "properties": { "fingerprint": { "type": "string", "description": "唯一设备指纹。" }, "persistent_device_id": { "type": "string", "description": "跨会话的稳定设备标识符（v2 指纹架构）。" }, "user_agent": { "type": "string", "description": "浏览器或应用的 user agent 字符串。驼峰式命名别名：userAgent。" }, "browser_family": { "type": "string", "description": "浏览器家族（例如 Chrome、Firefox、Safari）。必须显式发送 — 它不会从 user_agent 推导。驼峰式命名别名：browserFamily。" }, "browser_version": { "type": "string", "description": "浏览器版本字符串。必须显式发送。驼峰式命名别名：browserVersion。" }, "platform": { "type": "string", "description": "平台标识符（web、ios、android、macos、windows、linux）。必须显式发送 — 不会从 user_agent 推断得出。" }, "os_family": { "type": "string", "description": "操作系统系列（例如 iOS、Android、Windows）。驼峰命名别名：osFamily。" }, "os_version": { "type": "string", "description": "操作系统版本字符串。驼峰命名别名：osVersion。" }, "accept_language": { "type": "string", "description": "Accept-Language 请求头的值。CamelCase 别名：acceptLang。" }, "session_id": { "type": "string", "description": "交易对手会话的会话标识符。存储在元数据中。CamelCase 别名：sessionId。" }, "session_age_ms": { "type": "number", "description": "交易发生时用户会话的时长（毫秒）。驼峰式别名：sessionAgeMs。" }, "network_context": { "type": "object", "description": "包含 IP 地址和地理位置的网络上下文。顶层 ipInfo 块也会合并到此对象中。", "properties": { "ip_address": { "type": "string", "description": "客户端 IP 地址。驼峰命名别名：ip。" }, "ip_country_code": { "type": "string", "description": "基于地理位置解析的 IP 所在国家/地区（ISO 3166-1 alpha-3）。驼峰命名别名：countryCode3。" }, "latitude": { "type": "number", "description": "该 IP 的地理纬度。大驼峰（CamelCase）别名：lat。" }, "longitude": { "type": "number", "description": "该 IP 的地理经度。大驼峰（CamelCase）别名：lon。" } } } } }, "payment_method": { "type": "object", "description": "交易对手使用的支付方式。在 travelRule 交易中，`method_type: \"unhosted_wallet\"` 将交易对手钱包声明为自托管钱包：转账将跳过交易对手 VASP 路由，直接以 `UNCONFIRMED_OWNERSHIP` 状态创建，并且（当启用 `auto_wallet_verification` 时）会自动生成钱包所有权微件会话并在交易的 `action_required` 块中返回。", "properties": { "method_type": { "type": "string", "description": "支付方式类型：`bank_card`、`bank_account`、`crypto_wallet`、`ewallet`、`unhosted_wallet`、`other`。使用 `unhosted_wallet` 声明用于 Travel Rule 的自托管钱包。" }, "account_id": { "type": "string", "description": "账户标识符（例如 IBAN 或地址）。在比特币或 Lightning 上的加密转账中，它可能是 Lightning 付款请求（BOLT11 发票、BOLT12 报价、LNURL）或 Lightning 地址：Didit 将其指定的收款人存储为账户（未指定时为 \"\"），并将请求内容存储在 Travel Rule 转账的 `chain_details.lightning` 上。存储后最多 255 个字符。在比特币或 Lightning 上的加密转账中，它可能是 Lightning 付款请求（BOLT11 发票、BOLT12 报价、LNURL）或 Lightning 地址：Didit 将其指定的收款人存储为账户（未指定时为 \"\"），并将请求内容存储在 Travel Rule 转账的 `chain_details.lightning` 上。存储后最多 255 个字符。" }, "memo": { "type": "string", "maxLength": 256, "description": "在 memo 网络（XRP、XLM、EOS、ATOM、HBAR）上作为钱包一部分的目标标签或 memo。在单个共享交易所地址上，每个 memo 都是独立的支付方式。XRP：目标标签，0 到 4294967295 之间的整数（接受 JSON 数字）。XLM：最多 28 字节的文本 memo、64 位 ID 或十六进制的 32 字节哈希。EOS：最多 256 字节。ATOM：最多 256 个字符。HBAR：最多 100 字节。Bitcoin、EVM、Solana、Tron、Litecoin、Bitcoin Cash、Dogecoin 和 Lightning 钱包不接受 memo：传入 memo 会返回 `400`。别名：`destinationTag` 或 `destination_tag`。" }, "issuing_country": { "type": "string" } } } } }, "custom_properties": { "type": "object", "description": "附加到交易的任意键值对。可以在规则条件中通过字段路径 `custom_values.` 引用每个键。", "additionalProperties": true, "example": { "merchant_id": "test", "bank_name": "test_2" } }, "travel_rule_details": { "type": "object", "description": "Travel Rule 数据。启用 Travel Rule 且 transaction_category 为 travel_rule 时，Didit 会自行执行信息交换：忽略 status、protocol、required 和 obligations_count，并使用 originator_data、beneficiary_data 和 metadata。否则 Didit 会将这些值存储为被动的 Travel Rule 记录。开启 Travel Rule 期间，达到或超过您阈值的出账转账必须携带其制度所要求的信息（欧盟 TFR 或 FATF 第 16 号建议），并在您发送的一侧进行检查：缺少字段会在 `travel_rule_details.originator_data` 或 `travel_rule_details.beneficiary_data` 下返回 400，例如“欧盟 TFR 要求提供汇款人姓名。”", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "每当您发送 travel_rule_details 时必填。Travel Rule 转账状态之一（例如 AWAITING_COUNTERPARTY、COMPLETED、NOT_APPLICABLE）；同样接受并映射小写和驼峰拼写以及旧版值 UNKNOWN、COMPLIANT、PENDING_ACTION、PENDING_COUNTERPARTY、FAILED 和 EXEMPT。任何其他值均返回 400。" }, "protocol": { "type": "string" }, "required": { "type": "boolean" }, "obligations_count": { "type": "integer" }, "originator_data": { "type": "object", "description": "汇款人方，表示为扁平字段或单个 IVMS 101 人员。对于已通过 KYC 验证的用户，Didit 会将验证中包含的字段替换为已核验的值（参见 `metadata.originator_provenance`）。必须是一个对象：传入其他类型将返回 `400`。在支持 memo 的网络上，`memo` 键指定汇款人钱包的 memo 或标签。" }, "beneficiary_data": { "type": "object", "description": "收款人方，以扁平字段或单个 IVMS 101 人员形式呈现。必须是一个对象：其他任何类型都会返回 `400`。为了对转账进行路由，Didit 会读取 `wallet_address`（若为空则从 `counterparty.payment_method.account_id` 填充）、`chain`（从 `transaction_details.crypto_params.crypto_chain` 填充，或者当 `currency` 指明支持的链时从其填充）、`name`（回退为 `counterparty.full_name`）、`travel_address`、`counterparty_vasp_name`、`counterparty_vasp_lei` 和 `counterparty_vasp_email`。在 memo 网络上，`memo` 指定收款人钱包的 memo 或标签；`wallet_address` 和 `memo` 优先于交易对手的支付方式。" }, "metadata": { "type": "object" }, "utxo": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleUtxo" } ], "description": "可选，仅限 UTXO 链（BTC、LTC、BCH、DOGE）。交易的输入和输出，当您未明确声明时，Didit 会据此推断汇款人钱包和收款人输出。" }, "originator": { "type": "object", "description": "IVMS 101 汇款人数据块：`originatorPersons`（一个 `naturalPerson` 或 `legalPerson`；法人使该方成为企业）和 `accountNumber`（地址）。当 `originator_data` 对象为空时使用。格式错误的数据块将返回 400 响应，错误键为其路径，例如 `originator.originatorPersons`。" }, "beneficiary": { "type": "object", "description": "IVMS 101 收款人数据块：`beneficiaryPersons`（一个 `naturalPerson` 或 `legalPerson`；法人使该方成为企业）和 `accountNumber`（地址）。当 `beneficiary_data` 对象为空时使用。格式错误的数据块将返回以其路径为键的 400 响应，例如 `beneficiary.beneficiaryPersons`。" }, "ivms101": { "type": "object", "description": "封装在一个 IVMS 101 对象中的 `originator` 和 `beneficiary` 块（也接受 `IVMS101`）。顶层块优先于包装器内的块。" } } }, "network_snapshot": { "type": "object", "description": "预计算的网络图谱快照。", "properties": { "nodes": { "type": "array", "items": { "type": "object" } }, "edges": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "object" } } }, "include_crypto_screening": { "type": "boolean", "nullable": true, "description": "用于加密货币区块链分析筛查的逐笔交易覆盖项。当为 `true` 时，无论应用默认设置如何，都会执行加密货币筛查。当为 `false` 时，即使在应用设置中已启用，也会跳过加密货币筛查。省略或为 `null` 时，使用在控制台中配置的应用级默认设置。加密货币筛查需要 `transaction_details.direction`、`currency_kind: \"crypto\"`、一条链/币种，以及根据交易方向选取的钱包地址：入账转账前筛查使用 `counterparty.payment_method.account_id`，入账交易哈希筛查使用 `subject.payment_method.account_id`，出账筛查使用 `counterparty.payment_method.account_id`。当 `transaction_details.payment_reference_id` 包含区块链交易哈希时，Didit 会执行交易筛查并在可用时返回交易摘要增强信息。" } }, "required": [ "transaction_id", "transaction_category", "transaction_details", "subject" ] }, "examples": { "Minimal fiat withdrawal": { "summary": "法定货币出站转账可接受的最小 payload", "value": { "transaction_id": "your-txn-2026-05-17-001", "transaction_category": "finance", "transaction_details": { "direction": "outbound", "amount": 1500, "currency": "EUR", "action_type": "withdrawal" }, "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia" } } }, "Crypto outbound with screening": { "summary": "向非托管钱包的出向加密货币提现，可选筛查", "value": { "transaction_id": "your-txn-2026-05-17-002", "transaction_category": "finance", "include_crypto_screening": true, "transaction_details": { "direction": "outbound", "amount": 0.5, "currency": "BTC", "currency_kind": "crypto", "amount_in_default_currency": 32500, "default_currency": "USD", "action_type": "withdrawal" }, "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "payment_method": { "method_type": "crypto_wallet", "account_id": "bc1qexampleexchangewalletaddressxyz", "issuing_country": "ESP" } }, "counterparty": { "entity_type": "individual", "payment_method": { "method_type": "unhosted_wallet", "account_id": "bc1qexampleexternalwalletaddressabc" } } } }, "Travel Rule transfer": { "summary": "包含 Travel Rule 汇款人/收款人数据的出向加密货币转账", "value": { "transaction_id": "your-txn-2026-05-17-003", "transaction_category": "travel_rule", "transaction_details": { "direction": "outbound", "amount": 25000, "currency": "USDT", "currency_kind": "crypto", "action_type": "transfer" }, "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "date_of_birth": "1992-03-14", "address": { "country": "ESP", "town": "Madrid", "street": "Calle Mayor 1", "post_code": "28013" } }, "counterparty": { "entity_type": "individual", "full_name": "John Beneficiary", "institution_details": { "name": "Beneficiary VASP, Inc.", "code": "BVASP-US" } }, "travel_rule_details": { "status": "AWAITING_COUNTERPARTY", "protocol": "IVMS101", "required": true, "originator_data": { "name": "Maria Garcia" }, "beneficiary_data": { "name": "John Beneficiary" } } } } } } } }, "responses": { "201": { "description": "交易已提交并受监控。响应体为完整的交易详情（结构与 `GET /v3/transactions/{transaction_id}/` 相同），反映已应用的规则结果。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "examples": { "Approved with no rule hits": { "value": { "uuid": "abcdef12-3456-4890-abcd-ef1234567890", "environment": "live", "transaction_number": 4123, "txn_id": "your-txn-2026-05-17-001", "txn_date": "2026-05-17T08:42:00Z", "zone_id": "Europe/Madrid", "transaction_type": "finance", "action_type": "withdrawal", "direction": "OUTBOUND", "status": "APPROVED", "source": "LIVE", "amount": "1500", "currency": "EUR", "currency_type": "fiat", "amount_in_default_currency": "1620.45", "default_currency_code": "USD", "preferred_currency_amount": "1620.45", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "payment_txn_id": null, "score": 0, "severity": null, "decision_reason_code": null, "decision_reason_label": null, "vendor_data": "user-12345", "metadata": { "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "address": {}, "institution_details": {}, "device_context": {} }, "counterparty": {} }, "props": {}, "tags": [], "parties": [ { "uuid": "b1111111-2222-4333-8444-555555555555", "role": "APPLICANT", "entity_type": "individual", "kind": "USER", "vendor_data": "user-12345", "full_name": "Maria Garcia", "first_name": null, "last_name": null, "country_code": null, "dob": null, "address": {}, "institution_info": {}, "device": {}, "external_party_snapshot": null } ], "payment_methods": [], "documents": [], "activities": [ { "uuid": "d4e5f6a7-8901-4bcd-9ef0-123456789abc", "activity_type": "TRANSACTION_CREATED", "source": "TRANSACTION", "status": "APPROVED", "title": "withdrawal", "description": "Transaction recorded.", "metadata": {}, "occurred_at": "2026-05-17T08:42:11Z" } ], "alerts": [], "rule_runs": [], "provider_results": [], "travel_rule": null, "network_snapshot": null, "remediation": null, "action_required": null, "cost_breakdown": null } }, "Flagged for review": { "value": { "uuid": "abcdef12-3456-4890-abcd-ef1234567891", "environment": "live", "transaction_number": 4124, "txn_id": "your-txn-2026-05-17-002", "txn_date": "2026-05-17T08:42:00Z", "zone_id": "Europe/Madrid", "transaction_type": "finance", "action_type": "withdrawal", "direction": "OUTBOUND", "status": "IN_REVIEW", "source": "LIVE", "amount": "0.5", "currency": "BTC", "currency_type": "crypto", "amount_in_default_currency": "32500", "default_currency_code": "USD", "preferred_currency_amount": "32500", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "payment_txn_id": null, "score": 78, "severity": "HIGH", "decision_reason_code": "WALLET_HIGH_RISK", "decision_reason_label": "Destination wallet flagged as high risk", "vendor_data": "user-12345", "metadata": { "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "address": {}, "institution_details": {}, "device_context": {} }, "counterparty": {} }, "props": { "order_id": "ord-9988" }, "tags": [], "parties": [ { "uuid": "b1111111-2222-4333-8444-555555555555", "role": "APPLICANT", "entity_type": "individual", "kind": "USER", "vendor_data": "user-12345", "full_name": "Maria Garcia", "first_name": null, "last_name": null, "country_code": null, "dob": null, "address": {}, "institution_info": {}, "device": {}, "external_party_snapshot": null } ], "payment_methods": [], "documents": [], "activities": [], "alerts": [ { "uuid": "a7b8c9d0-1234-4abc-9def-567890abcdef", "title": "Destination wallet flagged as high risk", "description": "Provider risk score exceeded the configured threshold.", "severity": "HIGH", "status": "OPEN", "source": "RULE", "metadata": {}, "created_at": "2026-05-17T08:42:12Z", "due_at": null } ], "rule_runs": [ { "uuid": "e5f6a7b8-9012-4cde-af01-23456789abcd", "rule": "f6a7b8c9-0123-4def-b012-3456789abcde", "rule_title": "High-risk wallet screening", "rule_description": null, "rule_category": "crypto", "matched": true, "is_test": false, "mode": "ACTIVE", "severity": "HIGH", "score_delta": 78, "status_target": "IN_REVIEW", "action_summary": "score +78; change_status:IN_REVIEW", "metadata": {}, "created_at": "2026-05-17T08:42:12Z" } ], "provider_results": [], "travel_rule": null, "network_snapshot": null, "remediation": null, "action_required": null, "cost_breakdown": null } } } } } }, "400": { "description": "验证失败（缺少必填字段、重复的 `transaction_id`、未知的枚举值、无效的货币等）。", "content": { "application/json": { "examples": { "Missing required field": { "value": { "transaction_details": { "amount": [ "This field is required." ] } } }, "Duplicate transaction_id": { "value": { "transaction_id": [ "A transaction with this transaction_id already exists." ] } }, "Invalid category": { "value": { "non_field_errors": [ "Unsupported transaction category." ] } }, "Missing subject identity": { "value": { "subject": [ "subject.vendor_data and subject.full_name are required." ] } }, "Blocklisted participant": { "value": { "vendor_data": [ "The individual 'user-12345' is in the blocklist and cannot participate in transactions." ] } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法为此应用提交交易。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "409": { "description": "在处理当前请求时，另一个具有相同 `transaction_id` 的请求创建了交易，因此两个同时发起的提交中只有一个会成功。请读取现有交易，而不是重新提交。", "content": { "application/json": { "examples": { "Concurrent duplicate": { "value": { "detail": "A transaction with this transaction_id already exists." } } } } } }, "429": { "description": "超出速率限制：交易创建和事件摄入（`POST /v3/transactions/`、`POST /v3/events/`、`POST /v3/events/batch/`）共享每个 API 密钥每分钟 600 次请求的配额，独立于所有其他写入请求共享的 300 次配额。请等待 `Retry-After` 秒，然后重试。", "headers": { "Retry-After": { "description": "重试前需等待的秒数，向上取整以确保重试落在下一个时间窗口内。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Ingestion rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-didit-sdk": { "resource": "transactions", "method": "create", "auth": "api_key", "server": true } } }, "/v3/transactions/{transaction_id}/": { "get": { "summary": "获取交易", "description": "获取单笔交易的完整监控记录：各方主体、评分/严重程度、规则执行记录、警报、Travel Rule 结果、补救会话。", "operationId": "getTransaction", "x-didit-sdk": { "resource": "transactions", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Didit 稳定的交易 UUID（从创建/列出接口返回的 `uuid`，**不是**您的 `txn_id`）。", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.retrieve(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.retrieve(\"abcdef12-3456-7890-abcd-ef1234567890\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Retrieve(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().retrieve(\"abcdef12-3456-7890-abcd-ef1234567890\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->retrieve('abcdef12-3456-7890-abcd-ef1234567890');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.retrieve(\"abcdef12-3456-7890-abcd-ef1234567890\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.RetrieveAsync(\"abcdef12-3456-7890-abcd-ef1234567890\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "完整交易详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "examples": { "In review with an alert": { "value": { "uuid": "abcdef12-3456-4890-abcd-ef1234567890", "environment": "live", "transaction_number": 4123, "txn_id": "your-txn-2026-05-17-001", "txn_date": "2026-05-17T08:42:00Z", "zone_id": "Europe/Madrid", "transaction_type": "finance", "action_type": "withdrawal", "direction": "OUTBOUND", "status": "IN_REVIEW", "source": "LIVE", "amount": "1500", "currency": "EUR", "currency_type": "fiat", "amount_in_default_currency": "1620.45", "default_currency_code": "USD", "preferred_currency_amount": "1620.45", "preferred_currency_code": "USD", "payment_details": "Withdrawal to crypto wallet", "payment_txn_id": null, "score": 78, "severity": "HIGH", "decision_reason_code": "WALLET_HIGH_RISK", "decision_reason_label": "Destination wallet flagged as high risk", "vendor_data": "user-12345", "metadata": { "subject": { "entity_type": "individual", "vendor_data": "user-12345", "full_name": "Maria Garcia", "address": {}, "institution_details": {}, "device_context": {} }, "counterparty": {} }, "props": { "order_id": "ord-9988" }, "tags": [], "parties": [ { "uuid": "b1111111-2222-4333-8444-555555555555", "role": "APPLICANT", "entity_type": "individual", "kind": "USER", "vendor_data": "user-12345", "full_name": "Maria Garcia", "first_name": null, "last_name": null, "country_code": null, "dob": null, "address": {}, "institution_info": {}, "device": {}, "external_party_snapshot": null } ], "payment_methods": [], "documents": [], "activities": [], "alerts": [ { "uuid": "a7b8c9d0-1234-4abc-9def-567890abcdef", "title": "Destination wallet flagged as high risk", "description": "Provider risk score exceeded the configured threshold.", "severity": "HIGH", "status": "OPEN", "source": "RULE", "metadata": {}, "created_at": "2026-05-17T08:42:12Z", "due_at": null } ], "rule_runs": [], "provider_results": [], "travel_rule": null, "network_snapshot": null, "remediation": null, "action_required": null, "cost_breakdown": null } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法读取此应用的交易。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "该应用不存在具有此 UUID 的交易（已删除、从未创建、属于另一个应用，或路径片段不是有效的 UUID）。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/sdk-token/": { "post": { "summary": "生成 SDK 交易 token", "description": "生成一个短期受限 token，您的应用可将其传递给 Didit SDK，以便直接通过 `POST /v1/transactions/` 从终端用户的设备提交交易。该 token 与单个 `vendor_data`（您的用户 ID）绑定：使用该 token 提交的每笔交易，其主体身份都会在服务端根据该绑定关系强制生效，从而防止被篡改的客户端代表其他用户提交交易。请仅从后端生成 token，切勿在应用中直接包含 API 密钥本身。接口同样支持驼峰命名别名（`vendorData`、`ttlSeconds`、`maxUses`）。", "operationId": "createTransactionSdkToken", "x-didit-sdk": { "resource": "transactions", "method": "create_sdk_token", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendor_data": { "type": "string", "description": "您为此 token 作用域所限定的终端用户的内部标识符。强制作为使用该 token 提交的每笔交易的主体身份。", "example": "user-042" }, "ttl_seconds": { "type": "integer", "default": 900, "maximum": 86400, "description": "token 生命周期，以秒为单位。默认为 900（15 分钟）；最大值为 86400（24 小时）。" }, "max_uses": { "type": "integer", "nullable": true, "description": "使用此 token 允许的最大成功提交次数。省略或设为 null 表示在 TTL 内不限使用次数。" } }, "required": [ "vendor_data" ] }, "example": { "vendor_data": "user-042", "ttl_seconds": 900, "max_uses": 3 } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/transactions/sdk-token/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"vendor_data\": \"user-042\", \"ttl_seconds\": 900, \"max_uses\": 3}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.create_sdk_token(\n vendor_data=\"user-042\",\n ttl_seconds=900,\n max_uses=3,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.createSdkToken({\n vendor_data: \"user-042\",\n ttl_seconds: 900,\n max_uses: 3,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.CreateSDKToken(ctx, didit.TransactionsCreateSDKTokenParams{\n\tVendorData: \"user-042\",\n\tTTLSeconds: didit.Int(900),\n\tMaxUses: didit.Int(3),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionsCreateSdkTokenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().createSdkToken(TransactionsCreateSdkTokenParams.builder()\n .vendorData(\"user-042\")\n .ttlSeconds(900L)\n .maxUses(3L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->createSdkToken([\n 'vendor_data' => 'user-042',\n 'ttl_seconds' => 900,\n 'max_uses' => 3,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.create_sdk_token(\n vendor_data: \"user-042\",\n ttl_seconds: 900,\n max_uses: 3\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.CreateSdkTokenAsync(new TransactionsCreateSdkTokenParams\n{\n VendorData = \"user-042\",\n TtlSeconds = 900,\n MaxUses = 3,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "已签发的 token。将 `sdk_token` 传递给您的应用；它在 `expires_at` 之前通过 `X-Transaction-Token` 请求头对面向设备的 `/v1/transactions/` endpoint 进行身份验证。", "content": { "application/json": { "schema": { "type": "object", "properties": { "sdk_token": { "type": "string", "description": "要传递给 SDK 的作用域交易 token。" }, "expires_at": { "type": "string", "format": "date-time", "description": "token 停止被接受的时间。" } } }, "example": { "sdk_token": "q7Zt...urlsafe", "expires_at": "2026-07-07T12:15:00Z" } } } }, "400": { "description": "验证失败：缺少 `vendor_data`，或 `ttl_seconds` 超出允许范围。", "content": { "application/json": { "examples": { "Missing vendor_data": { "value": { "vendor_data": [ "This field is required." ] } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥。", "content": { "application/json": { "examples": { "Invalid API Key": { "value": { "detail": "Invalid API Key." } } } } } } } } }, "/v1/transactions/": { "post": { "summary": "从 SDK 提交交易", "description": "面向设备的 endpoint，Didit SDK 调用它直接从终端用户的设备提交交易。身份验证使用的是来自 `POST /v3/transactions/sdk-token/` 的作用域受限的 token，并在 `X-Transaction-Token` 请求头中发送，而非使用 API 密钥；该 endpoint 已启用 CORS，因此浏览器可以跨域调用。payload 使用下方所示的 camelCase 格式字段别名（SDK 的 `submitTransaction` 方法会自动为您构建）。服务端提供三项保证：应用始终取自 token；主体身份（`externalUserId`）始终根据 token 的 `vendor_data` 强制确定，从而忽略伪造的 payload 值；以及设备情报（SDK 设备指纹加上服务端派生的 IP 和 user agent）会自动附加到主体上。", "operationId": "submitTransactionFromSdk", "x-didit-sdk": { "resource": "transactions", "method": "submit_from_device", "auth": "device_token", "server": false }, "tags": [ "Transactions" ], "security": [ { "TransactionTokenAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "txnId": { "type": "string", "description": "您对此交易的唯一标识符（映射到 `transaction_id`，最多 128 个字符）。", "example": "wd-2026-07-07-0042" }, "txnDate": { "type": "string", "format": "date-time", "description": "交易发生的时间（映射到 `transaction_at`）。如果省略，则默认为当前时间。" }, "zoneId": { "type": "string", "description": "IANA 时区标识符（映射至 `time_zone`），例如 `Europe/Madrid`。" }, "type": { "type": "string", "description": "交易类别（映射到 `transaction_category`），例如 `finance`、`kyc`、`travelRule`、`userPlatformEvent`、`gamblingBet`。", "example": "travelRule" }, "info": { "type": "object", "description": "交易的核心财务详情（映射至 `transaction_details`）。", "required": [ "direction", "amount", "currency" ], "properties": { "direction": { "type": "string", "description": "相对于主体的方向。不区分大小写；接受 `in`/`out` 作为别名。以大写形式返回（`INBOUND`/`OUTBOUND`）。", "example": "out" }, "amount": { "type": "number", "description": "交易金额（最多 18 位小数）。也接受十进制字符串，这也是保留超过约 15 位有效数字的唯一方法：JSON 数字会先解析为二进制浮点数，因此 `0.123456789012345678` 会存储为 `0.12345678901234568`。", "example": 0.25 }, "currency": { "type": "string", "description": "货币代码。接受任何 ISO 4217 字母代码（例如 `EUR`、`USD`、`NGN`）以及加密资产符号（例如 `BTC`）。建议使用当前流通的代码。并非每个接受的代码都有汇率：当该代码没有可用汇率时（例如 ISO 会计单位 `XSU`，或 Didit 未定价的加密资产符号），自动换算将失败，并且 `preferred_currency_amount` 将返回 null，除非请求提供了预先换算的 `amountInDefaultCurrency`。", "example": "ETH" }, "currencyType": { "type": "string", "description": "币种是 `fiat` 还是 `crypto`（映射到 `currency_kind`）。" }, "amountInDefaultCurrency": { "type": "number", "nullable": true, "description": "以默认币种计的预先换算金额（映射至 `amount_in_default_currency`）。若省略，将尝试自动进行外汇换算。" }, "defaultCurrencyCode": { "type": "string", "description": "转换金额的默认货币代码（映射到 `default_currency`）。任何当前流通的 ISO 4217 代码。" }, "paymentDetails": { "type": "string", "nullable": true, "description": "自由文本付款参考号或附言（映射至 `payment_details`）。" }, "paymentTxnId": { "type": "string", "nullable": true, "description": "外部支付参考标识（映射到 `payment_reference_id`）；对于加密货币交易，则为链上交易哈希。" }, "type": { "type": "string", "nullable": true, "description": "交易的子类型（映射到 `action_type`），例如 `deposit`、`withdrawal`、`transfer`。" }, "cryptoParams": { "type": "object", "description": "加密货币特定参数，例如 `{\"crypto_chain\": \"ETH\"}`。" } } }, "subject": { "type": "object", "description": "交易的主体（申请人）。此处忽略 `externalUserId`：主体身份始终强制使用 token 的 `vendor_data`。", "required": [ "fullName" ], "properties": { "type": { "type": "string", "description": "主体类型（映射到 `entity_type`）：`individual`（默认）或 `company`。" }, "externalUserId": { "type": "string", "description": "对主体忽略 - 在服务端根据 token 的 `vendor_data` 强制执行。" }, "fullName": { "type": "string", "example": "Jane Doe" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dob": { "type": "string", "format": "date", "description": "出生日期（YYYY-MM-DD；映射至 `date_of_birth`）。" }, "address": { "type": "object", "description": "包含 `country`（ISO 3166-1 alpha-3）、`town`、`state`、`street`、`post_code` 的地址对象。" }, "institutionInfo": { "type": "object", "description": "机构参与者的机构详情（映射到 `institution_details`）。" }, "device": { "type": "object", "description": "可选的显式设备上下文。会与自动采集的设备情报进行合并；发生冲突时以服务端派生的字段为准。" }, "paymentMethod": { "type": "object", "description": "主体使用的支付方式（映射至 `payment_method`）。", "properties": { "type": { "type": "string", "description": "支付方式类型（映射至 `method_type`），例如 `bank_card`、`bank_account`、`crypto_wallet`、`ewallet`、`unhosted_wallet`、`other`。" }, "accountId": { "type": "string", "description": "账户标识符（映射到 `account_id`）：IBAN、银行卡指纹或地址。" }, "issuingCountry": { "type": "string", "description": "签发方的 ISO 3166-1 alpha-3 国家/地区代码（映射至 `issuing_country`）。" } } } } }, "counterparty": { "type": "object", "description": "交易对手（可选）。结构与 `subject` 相同；此处 `externalUserId` 有意义。", "properties": { "type": { "type": "string", "description": "主体类型（映射到 `entity_type`）：`individual` 或 `company`。" }, "externalUserId": { "type": "string", "description": "您为交易对手指定的内部标识符（映射到 `vendor_data`）。" }, "fullName": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "dob": { "type": "string", "format": "date" }, "address": { "type": "object" }, "institutionInfo": { "type": "object" }, "device": { "type": "object" }, "paymentMethod": { "type": "object", "description": "交易对手使用的支付方式（映射至 `payment_method`）。在 travelRule 交易中，`type: \"unhosted_wallet\"` 将交易对手钱包声明为自托管钱包：转账将跳过交易对手 VASP 路由，直接以 `UNCONFIRMED_OWNERSHIP` 状态创建，并且（当启用 `auto_wallet_verification` 时）会自动生成钱包所有权微件会话并在 `action_required` 中返回，以便 SDK 可以启动它。", "properties": { "type": { "type": "string", "description": "支付方式类型（映射至 `method_type`），例如 `bank_card`、`bank_account`、`crypto_wallet`、`ewallet`、`unhosted_wallet`、`other`。使用 `unhosted_wallet` 可声明 Travel Rule 的自托管钱包。" }, "accountId": { "type": "string", "description": "账户标识符（映射到 `account_id`）：IBAN、银行卡指纹或地址。" }, "issuingCountry": { "type": "string" } } } } }, "props": { "type": "object", "additionalProperties": true, "description": "自定义键值对（映射到 `custom_properties`）。每个键都可以在规则条件中作为 `custom_values.` 引用。" }, "travelRule": { "type": "object", "description": "Travel Rule 详情（映射到 `travel_rule_details`）。当为应用启用 Travel Rule 时，Didit 会忽略您发送的任何 `status` 并自行驱动信息交换。", "required": [ "status" ], "properties": { "status": { "type": "string" }, "protocol": { "type": "string" }, "required": { "type": "boolean" }, "obligationsCount": { "type": "integer" }, "originatorData": { "type": "object" }, "beneficiaryData": { "type": "object" }, "metadata": { "type": "object" } } }, "includeCryptoScreening": { "type": "boolean", "nullable": true, "description": "用于加密货币区块链分析筛查的逐笔交易覆盖项（映射到 `include_crypto_screening`）。" }, "fingerprint_v2": { "type": "object", "description": "`didit-fp-v2` 设备指纹 payload。由 SDK 自动注入；仅在直接调用 wire API 时才相关。" } }, "required": [ "txnId", "type", "info", "subject" ] }, "example": { "txnId": "wd-2026-07-07-0042", "type": "travelRule", "info": { "direction": "out", "amount": "0.25", "currency": "ETH", "currencyType": "crypto", "cryptoParams": { "crypto_chain": "ETH" } }, "subject": { "fullName": "Jane Doe" }, "counterparty": { "fullName": "Ana Diaz", "paymentMethod": { "type": "unhosted_wallet", "accountId": "0xBeneficiaryWallet01" } }, "travelRule": { "status": "AWAITING_COUNTERPARTY", "beneficiaryData": { "wallet_address": "0xBeneficiaryWallet01", "name": "Ana Diaz" } }, "includeCryptoScreening": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v1/transactions/ \\\n -H 'X-Transaction-Token: SDK_TOKEN' -H 'Content-Type: application/json' \\\n -d '{\"txnId\": \"wd-2026-07-07-0042\", \"type\": \"travelRule\", \"info\": {\"direction\": \"out\", \"amount\": \"0.25\", \"currency\": \"ETH\", \"currencyType\": \"crypto\"}, \"subject\": {\"fullName\": \"Jane Doe\"}, \"counterparty\": {\"fullName\": \"Ana Diaz\", \"paymentMethod\": {\"type\": \"unhosted_wallet\", \"accountId\": \"0xBeneficiaryWallet01\"}}, \"travelRule\": {\"status\": \"AWAITING_COUNTERPARTY\", \"beneficiaryData\": {\"wallet_address\": \"0xBeneficiaryWallet01\", \"name\": \"Ana Diaz\"}}, \"includeCryptoScreening\": true}'" }, { "lang": "javascript", "label": "Web SDK", "source": "import { DiditSdk } from '@didit-protocol/sdk-web';\n\nconst result = await DiditSdk.shared.submitTransaction({\n transactionToken: sdkToken,\n transaction: {\n txnId: 'wd-2026-07-07-0042',\n category: 'travelRule',\n details: { direction: 'out', amount: '0.25', currency: 'ETH', currencyType: 'crypto' },\n subject: { fullName: 'Jane Doe' },\n counterparty: { fullName: 'Ana Diaz', paymentMethod: { type: 'unhosted_wallet', accountId: '0xBeneficiaryWallet01' } },\n travelRule: { status: 'AWAITING_COUNTERPARTY', beneficiaryData: { wallet_address: '0xBeneficiaryWallet01', name: 'Ana Diaz' } },\n includeCryptoScreening: true\n },\n onActionCompleted: (refreshed) => console.log(refreshed.status)\n});" } ], "responses": { "201": { "description": "交易已提交并受监控。详情结构与 `GET /v3/transactions/{transaction_id}/` 相同，包括终端用户必须完成后续操作时的 `action_required` 块（各 SDK 默认自动启动该操作）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "examples": { "Wallet ownership required": { "value": { "uuid": "22222222-3333-4444-5555-666666666666", "txn_id": "wd-2026-07-07-0042", "transaction_type": "travelRule", "direction": "OUTBOUND", "status": "APPROVED", "amount": "0.25", "currency": "ETH", "travel_rule": { "uuid": "33333333-4444-5555-6666-777777777777", "status": "UNCONFIRMED_OWNERSHIP", "required": true }, "action_required": { "type": "wallet_ownership", "url": "https://verify.didit.me/wallet-ownership/3s9x...urlsafe", "widget_session_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb", "expires_at": "2026-07-07T13:00:00Z" } } } } } } }, "400": { "description": "验证失败（缺少必填字段、重复的 `txnId`、未知类别）。", "content": { "application/json": { "examples": { "Missing fields": { "value": { "transaction_details": { "currency": [ "This field is required." ] } } }, "Duplicate txnId": { "value": { "transaction_id": [ "A transaction with this transaction_id already exists." ] } } } } } }, "401": { "description": "交易 token 被拒绝：缺失、未知、已撤回、超出 `max_uses` 或已过期。过期 token 的响应在详情中始终包含单词 `expired`，SDK 据此区分 `expired_token` 与 `invalid_token` 错误。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "Invalid transaction token." } }, "Expired token": { "value": { "detail": "Transaction token expired." } } } } } }, "409": { "description": "在处理当前请求时，另一个具有相同 `txnId` 的请求创建了交易，因此两个同时发起的提交中只有一个会成功。请读取现有交易，而不是重新提交。", "content": { "application/json": { "examples": { "Concurrent duplicate": { "value": { "detail": "A transaction with this transaction_id already exists." } } } } } } } } }, "/v1/transactions/{transaction_id}/": { "get": { "summary": "从 SDK 获取交易", "description": "面向设备的读取 endpoint，使用与提交时相同的 `X-Transaction-Token` 进行身份验证。在自动启动的操作流程完成或其窗口关闭后，SDK 会对其进行轮询，因此最终状态绝不依赖于单次通知。返回与提交响应相同的交易详情，包括当前的 `action_required` 块（操作解决后为 `null`）。", "operationId": "getTransactionFromSdk", "x-didit-sdk": { "resource": "transactions", "method": "retrieve_from_device", "auth": "device_token", "server": false }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Didit 稳定的交易 UUID（来自提交响应的 `uuid`，**不是**您的 `txnId`）。", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" } ], "security": [ { "TransactionTokenAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v1/transactions/22222222-3333-4444-5555-666666666666/' \\\n -H 'X-Transaction-Token: SDK_TOKEN'" } ], "responses": { "200": { "description": "完整的交易详情，包括 `action_required`（待处理操作解决后为 `null`）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" } } } }, "401": { "description": "交易 token 被拒绝：缺失、未知、已撤回、超出 `max_uses` 或已过期。", "content": { "application/json": { "examples": { "Expired token": { "value": { "detail": "Transaction token expired." } } } } } }, "404": { "description": "该 token 对应的应用中不存在具有此 UUID 的交易，或者路径片段不是有效的 UUID。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } } } } }, "/v3/businesses/": { "get": { "summary": "列出企业", "description": "列出 Didit 根据共享相同 `vendor_data`（自由格式字符串，非 UUID）的 KYB 会话汇编的[企业](/entities/businesses)，以及通过 API 创建的企业。支持分页，按 `last_session_at` 降序排列。该 endpoint 不支持过滤或搜索参数，请获取分页并在客户端进行过滤。", "operationId": "list_businesses", "x-didit-sdk": { "resource": "businesses", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "页面大小。省略时默认为 50。虽无强制上限，但为降低延迟建议保持较小的页面大小。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "要返回的第一条记录的从零开始的偏移量。建议跟随上一页的 `next` URL，而不是手动计算。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/businesses/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.businesses.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.businesses.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Businesses.ListAutoPaging(ctx, didit.BusinessesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.businesses().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "businesses->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.businesses.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Businesses.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页的企业列表，包含状态、会话计数和功能明细。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "匹配行数，出于性能考虑，不超过 100 时为精确值，超过 100 时上限为 100。请勿使用它来检测最后一页；应依靠 `next` 为 `null` 进行判断。" }, "next": { "type": "string", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BusinessListItem" } } } }, "examples": { "Example": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": null, "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Trading Ltd", "status": "ACTIVE", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z" } ] } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法列出此应用的企业。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/customization/": { "get": { "summary": "获取品牌定制", "description": "返回根据 API 密钥解析的应用白标品牌定制信息：颜色、字体、边框圆角、logo URL 以及 UI/UX 选项。自定义域名和白标邮件设置仅在 Business Console 中管理，不属于此响应的一部分。", "operationId": "get_customization", "x-didit-sdk": { "resource": "customization", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Customization" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/customization/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.customization.retrieve()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.customization.retrieve();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Customization.Retrieve(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.customization().retrieve();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "customization->retrieve();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.customization.retrieve\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Customization.RetrieveAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "应用的当前品牌定制。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingCustomization" }, "examples": { "Default branding": { "value": { "color_primary": "#000000", "color_secondary": "#9DA1A1", "color_background": "#FFFFFF", "color_panel": "#2567FF", "color_panel_10": "#1A1A1A", "color_on_panel_1": "#9DA1A1", "color_on_panel_2": "#F4F4F6", "color_on_background": "#000000", "color_button_1": "#2567FF", "color_button_2": "#F8F8F8", "color_button_text_1": "#FFFFFF", "color_button_text_2": "#000000", "color_pill_text": "#111827", "border_radius_panel": 10, "border_radius_buttons": 12, "font_family": "Inter", "font_weight": "regular", "font_url": "https://fonts.googleapis.com/css2?family=Inter", "logo_square": null, "logo_rectangular": null, "logo_rectangular_dark": null, "favicon": null, "app_public_name": "Acme Verify", "privacy_policy_url": "https://acme.com/privacy", "skip_welcome_screen": false, "disable_login_with_didit": false, "hide_progress_bar": false, "callback_seconds": 3 } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。密钥缺失返回 `403`；密钥错误、已撤销或已过期返回 `401`。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制。请使用指数退避重试。" } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新品牌定制", "description": "部分更新应用的白标品牌化。发送 `application/json` 以更改颜色、字体、圆角半径和 UI 选项，或发送 `multipart/form-data` 以上传徽标图像。仅更改您包含的字段。自定义域名和白标邮箱无法通过此 endpoint 进行设置，请在 Business Console 中配置这些项。", "operationId": "update_customization", "x-didit-sdk": { "resource": "customization", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Customization" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingCustomizationUpdate" }, "examples": { "Update colors and font": { "summary": "更改品牌颜色和字体", "value": { "color_primary": "#123456", "color_button_1": "#2567FF", "font_family": "AR One Sans", "border_radius_buttons": 16 } }, "Update UI options": { "summary": "更改公开名称和流程选项", "value": { "app_public_name": "Acme Verify", "privacy_policy_url": "https://acme.com/privacy", "skip_welcome_screen": true, "hide_progress_bar": true, "callback_seconds": 5 } }, "Remove a logo": { "summary": "删除当前的矩形 Logo", "value": { "delete_logo_rectangular": true } }, "Remove the dark-mode logo": { "summary": "删除当前的深色模式 Logo", "value": { "delete_logo_rectangular_dark": true } } } }, "multipart/form-data": { "schema": { "type": "object", "description": "仅在上传 Logo 图片时使用 multipart/form-data。上述品牌设置字段也可以在同一请求中作为表单字段发送。", "properties": { "image_square": { "type": "string", "format": "binary", "description": "正方形 logo（1:1 宽高比）。PNG、JPG 或 WebP 格式，长边至少 512 px，最大 **1 MB**。" }, "image_rectangular": { "type": "string", "format": "binary", "description": "矩形徽标（2:1 宽高比）。PNG、JPG 或 WebP 格式，长边至少 512 px，最大 **1 MB**。" }, "image_rectangular_dark": { "type": "string", "format": "binary", "description": "深色模式矩形徽标（2:1 宽高比），显示在深色背景上。PNG、JPG 或 WebP 格式，长边至少 512 px，最大 **1 MB**。作为 `logo_rectangular_dark` 返回。" }, "image_favicon": { "type": "string", "format": "binary", "description": "网站图标（Favicon）图像。最大 **500 KB**。" } } }, "example": { "image_rectangular": "(binary PNG logo, 2:1)", "image_rectangular_dark": "(binary PNG logo for dark mode, 2:1)", "image_favicon": "(binary favicon)" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/customization/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"color_primary\": \"#123456\", \"font_family\": \"AR One Sans\"}'" }, { "lang": "curl", "label": "curl (logo upload)", "source": "curl -X PATCH 'https://verification.didit.me/v3/customization/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'image_rectangular=@logo.png' \\\n -F 'image_rectangular_dark=@logo-dark.png' \\\n -F 'image_favicon=@favicon.ico'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.customization.update(\n image_rectangular=open(\"image_rectangular.jpg\", \"rb\"),\n image_rectangular_dark=open(\"image_rectangular_dark.jpg\", \"rb\"),\n image_favicon=open(\"image_favicon.jpg\", \"rb\"),\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.customization.update({\n image_rectangular: await fileFromPath(\"image_rectangular.jpg\"),\n image_rectangular_dark: await fileFromPath(\"image_rectangular_dark.jpg\"),\n image_favicon: await fileFromPath(\"image_favicon.jpg\"),\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Customization.Update(ctx, didit.CustomizationUpdateParams{\n\tImageRectangular: didit.Some(didit.FileFromPath(\"image_rectangular.jpg\")),\n\tImageRectangularDark: didit.Some(didit.FileFromPath(\"image_rectangular_dark.jpg\")),\n\tImageFavicon: didit.Some(didit.FileFromPath(\"image_favicon.jpg\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.CustomizationUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.customization().update(CustomizationUpdateParams.builder()\n .imageRectangular(Path.of(\"image_rectangular.jpg\"))\n .imageRectangularDark(Path.of(\"image_rectangular_dark.jpg\"))\n .imageFavicon(Path.of(\"image_favicon.jpg\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "customization->update([\n 'image_rectangular' => File::fromPath('image_rectangular.jpg'),\n 'image_rectangular_dark' => File::fromPath('image_rectangular_dark.jpg'),\n 'image_favicon' => File::fromPath('image_favicon.jpg'),\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.customization.update(\n image_rectangular: Pathname(\"image_rectangular.jpg\"),\n image_rectangular_dark: Pathname(\"image_rectangular_dark.jpg\"),\n image_favicon: Pathname(\"image_favicon.jpg\")\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Customization.UpdateAsync(new CustomizationUpdateParams\n{\n ImageRectangular = FileUpload.FromPath(\"image_rectangular.jpg\"),\n ImageRectangularDark = FileUpload.FromPath(\"image_rectangular_dark.jpg\"),\n ImageFavicon = FileUpload.FromPath(\"image_favicon.jpg\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "品牌形象已更新。返回完整的品牌形象对象（所有字段，不仅是您更改的字段）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrandingCustomization" }, "examples": { "Updated": { "value": { "color_primary": "#123456", "color_secondary": "#9DA1A1", "color_background": "#FFFFFF", "color_panel": "#2567FF", "color_panel_10": "#1A1A1A", "color_on_panel_1": "#9DA1A1", "color_on_panel_2": "#F4F4F6", "color_on_background": "#000000", "color_button_1": "#2567FF", "color_button_2": "#F8F8F8", "color_button_text_1": "#FFFFFF", "color_button_text_2": "#000000", "color_pill_text": "#111827", "border_radius_panel": 10, "border_radius_buttons": 16, "font_family": "AR One Sans", "font_weight": "400", "font_url": "https://fonts.googleapis.com/css2?family=AR+One+Sans", "logo_square": null, "logo_rectangular": "https://cdn.didit.me/white_label/logo_rectangular/...", "logo_rectangular_dark": null, "favicon": null, "app_public_name": "Acme Verify", "privacy_policy_url": "https://acme.com/privacy", "skip_welcome_screen": true, "disable_login_with_didit": false, "hide_progress_bar": false, "callback_seconds": 3 } } } } } }, "400": { "description": "无效的请求体。例如：格式错误的十六进制颜色、未知的字体系列或粗细、仅限 Business Console 的字段（`domain`、`from_email`、`verify_domain`、`force_remove_domain`、`verify_email_domain`、`force_remove_email_domain` 及其只读对应字段），或者上传的 Logo 不是 PNG、JPG 或 WebP 图像、长边小于 512 px、超过 1 MB 或宽高比错误。在配置了自定义域名的同时将 `disable_login_with_didit` 设置为 `false` 也会返回此错误。", "content": { "application/json": { "examples": { "Bad color": { "value": { "color_primary": [ "Invalid color format. Use '#RRGGBB' or '#RRGGBBAA' format." ] } }, "Bad logo": { "value": { "image_rectangular": [ "Image aspect ratio must be 2:1. Got 1024x1024 image dimensions" ] } }, "Unsupported logo format": { "summary": "不是 PNG、JPG 或 WebP 图像（例如 SVG）", "value": { "image_rectangular_dark": [ "Upload a PNG, JPG or WebP image." ] } }, "Logo too small": { "summary": "长边小于 512 px", "value": { "image_rectangular": [ "Image must be at least 512 px on its long side. Got 400x200 image dimensions" ] } }, "Logo too large": { "summary": "超过 1 MB", "value": { "image_square": [ "File size should not exceed 1 MB" ] } }, "Console-only field": { "value": { "domain": [ "Manage this field in the Business Console." ] } }, "Bad font weight": { "value": { "font_weight": [ "Font weight 950 is not available for Inter. Available weights are: 100, 200, 300, 400, 500, 600, 700, 800, 900" ] } } } } } }, "403": { "description": "API 密钥缺失、格式错误、已过期或作用域属于其他应用。密钥缺失返回 `403`；密钥错误、已撤销或已过期返回 `401`。", "content": { "application/json": { "examples": { "Invalid token": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制。请使用指数退避重试。" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/{vendor_data}/": { "get": { "summary": "获取企业", "description": "通过 `vendor_data`（精确匹配）获取单个[企业](/entities/businesses)。向列表视图添加 `metadata` 和 `updated_at`。已删除的企业返回 404。", "operationId": "get_business", "x-didit-sdk": { "resource": "businesses", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "您对该企业的唯一标识符，为自由格式字符串（非 UUID），按发送的内容精确匹配。", "example": "company-123" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/businesses/company-123/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.retrieve(\n \"company-123\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.retrieve(\"company-123\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Retrieve(ctx, \"company-123\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().retrieve(\"company-123\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->retrieve('company-123');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.retrieve(\"company-123\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.RetrieveAsync(\"company-123\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "完整企业详情，包含元数据和聚合会话数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Active business": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": null, "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Trading Ltd", "status": "ACTIVE", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z", "metadata": { "industry": "fintech" }, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法读取此应用的企业。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "该应用下不存在带有提供的 `vendor_data` 的（未删除）企业。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新企业", "description": "企业的部分更新：`display_name`、`legal_name`、`registration_number`、`country_code`、`status`、`metadata`。`metadata` 将完全替换。将 `status` 设置为 `BLOCKED` 会将 `vendor_data` 添加到系统黑名单；移出 `BLOCKED` 则会移除该条目。每次修改都会记录在企业的活动记录中：状态变更带有可选的 `reason`，而对 `display_name`、`legal_name`、`registration_number`、`country_code` 或 `metadata` 的更改则记录为资料更新。", "operationId": "update_business", "x-didit-sdk": { "resource": "businesses", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "您对该企业的唯一标识符（自由格式字符串，非 UUID）。", "example": "company-123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "部分更新请求体。仅提供您想要更改的字段。", "properties": { "display_name": { "type": "string", "nullable": true, "description": "控制台中显示的易读显示名称（在界面显示时优先级高于 `legal_name`）。" }, "legal_name": { "type": "string", "nullable": true, "description": "来自登记处或手动输入的官方法定名称。" }, "registration_number": { "type": "string", "nullable": true, "description": "企业注册号或成立号。" }, "country_code": { "type": "string", "nullable": true, "description": "注册国家/地区（ISO 3166-1 alpha-2，例如 `GB`、`US`）。" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "企业生命周期状态。设置为 `BLOCKED` 会自动将 `vendor_data` 添加至系统黑名单；从 `BLOCKED` 切出则会移除该黑名单条目。" }, "metadata": { "type": "object", "nullable": true, "description": "您附加到企业的任意 JSON 对象。更新时将**完全替换**现有元数据。如果仅想添加键，请在客户端进行合并。" }, "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "状态变更的原因。仅在状态实际变更时，记录在 Business Console 中该企业的 **Activity** 状态变更条目上。Webhook 不包含此项。" } } }, "examples": { "Update name": { "summary": "更新显示名称", "value": { "display_name": "Acme Corp" } }, "Flag for review": { "summary": "切换状态", "value": { "status": "FLAGGED" } }, "Add metadata": { "summary": "替换元数据 JSON", "value": { "metadata": { "industry": "fintech", "risk_level": "low" } } }, "Fix registry data": { "summary": "提取的字段正确", "value": { "legal_name": "Acme Trading International Ltd", "registration_number": "12345678", "country_code": "GB" } }, "Flag with reason": { "summary": "标记企业并记录原因", "value": { "status": "FLAGGED", "reason": "Ownership structure under review" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/businesses/company-123/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"display_name\": \"Acme Corp\", \"status\": \"FLAGGED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.update(\n \"company-123\",\n display_name=\"Acme Corp\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.update(\"company-123\", {\n display_name: \"Acme Corp\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Update(ctx, \"company-123\", didit.BusinessesUpdateParams{\n\tDisplayName: didit.String(\"Acme Corp\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BusinessesUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().update(\"company-123\", BusinessesUpdateParams.builder()\n .displayName(\"Acme Corp\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->update('company-123', [\n 'display_name' => 'Acme Corp',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.update(\n \"company-123\",\n display_name: \"Acme Corp\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.UpdateAsync(\"company-123\", new BusinessesUpdateParams\n{\n DisplayName = \"Acme Corp\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "企业已更新。返回完整的已更新企业记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Updated": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": "Acme Corp", "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Corp", "status": "FLAGGED", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z", "metadata": { "industry": "fintech", "risk_level": "low" }, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "400": { "description": "无效的请求体：通常是未知的 `status`、格式错误的 `metadata` 或超过 1000 个字符的 `reason`。", "content": { "application/json": { "examples": { "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Bad metadata": { "value": { "metadata": [ "Metadata must be a JSON object." ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法更新此应用的企业。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "该应用下不存在带有提供的 `vendor_data` 的（未删除）企业。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/{vendor_data}/update-status/": { "patch": { "summary": "更新企业状态", "description": "仅切换企业的生命周期 `status`：`ACTIVE`、`FLAGGED` 或 `BLOCKED`（非会话状态）。`BLOCKED` 会将 `vendor_data` 添加到系统黑名单中；脱离 `BLOCKED` 状态则会移除该条目。每次变更都会记录在企业的活动中，并附带可选的 `reason`。发送当前状态不会产生任何更改，也不会记录 `reason`。`business.status.updated` Webhook 不包含 `reason`。", "operationId": "update_business_status", "x-didit-sdk": { "resource": "businesses", "method": "update_status", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "您对该企业的唯一标识符（自由格式字符串，非 UUID）。", "example": "company-123" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityStatusUpdateRequest" }, { "type": "object", "properties": { "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "状态变更的原因。仅在状态实际变更时，记录在 Business Console 中该企业的 **Activity** 状态变更条目上。Webhook 不包含此项。" } } } ] }, "examples": { "Flag": { "summary": "标记企业以待审核", "value": { "status": "FLAGGED" } }, "Block": { "summary": "拉黑该企业（添加到系统黑名单）", "value": { "status": "BLOCKED" } }, "Reactivate": { "summary": "重新激活企业", "value": { "status": "ACTIVE" } }, "Block with reason": { "summary": "拉黑该企业并记录原因", "value": { "status": "BLOCKED", "reason": "Registry shows the company dissolved" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/businesses/company-123/update-status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"status\": \"BLOCKED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.update_status(\n \"company-123\",\n status=\"FLAGGED\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.updateStatus(\"company-123\", {\n status: \"FLAGGED\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.UpdateStatus(ctx, \"company-123\", didit.BusinessesUpdateStatusParams{\n\tStatus: \"FLAGGED\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BusinessesUpdateStatusParams;\nimport me.didit.types.EntityStatusUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().updateStatus(\"company-123\", BusinessesUpdateStatusParams.builder()\n .status(EntityStatusUpdateRequest.Status.of(\"FLAGGED\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->updateStatus('company-123', [\n 'status' => 'FLAGGED',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.update_status(\n \"company-123\",\n status: \"FLAGGED\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.UpdateStatusAsync(\"company-123\", new BusinessesUpdateStatusParams\n{\n Status = \"FLAGGED\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "企业状态已更新。返回完整的企业记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Blocked": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-123", "display_name": null, "legal_name": "Acme Trading Ltd", "registration_number": "12345678", "country_code": "GB", "effective_name": "Acme Trading Ltd", "status": "BLOCKED", "session_count": 2, "approved_count": 1, "declined_count": 0, "in_review_count": 1, "features": { "KYB": "Approved" }, "features_list": [ { "feature": "KYB", "status": "Approved" } ], "last_session_at": "2026-03-15T10:30:00Z", "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": "2026-01-10T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "name": "VIP", "color": "#2567FF" } ], "created_at": "2026-01-10T08:00:00Z", "metadata": { "industry": "fintech" }, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "400": { "description": "`status` 缺失或无效，或 `reason` 超过 1000 个字符。", "content": { "application/json": { "examples": { "Missing status": { "value": { "status": [ "This field is required." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法更新此应用的企业。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "该应用下不存在带有提供的 `vendor_data` 的（未删除）企业。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/delete/": { "post": { "summary": "批量删除企业", "description": "**永久删除**企业 — 此操作无法撤销。若需阻止企业，建议使用 [Update Business Status](#patch-/v3/businesses/-vendor_data-/update-status/) 并传入 `BLOCKED`。\n\n**已归档的监管报告：**如果选定的数据包含在已定稿的监管报告中，整个请求将被拒绝并返回 `409`，且不会删除任何内容。响应体使用 `code: in_filed_report`，并通过 `uuid`、`report_number`、`report_type` 和 `case_uuid` 列出每份报告。请先删除这些报告，然后重试请求。", "operationId": "batch_delete_businesses", "x-didit-sdk": { "resource": "businesses", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "提供 `vendor_data_list`、`didit_internal_id_list` 或 `delete_all: true`。传入多项时的优先级：`delete_all` > `vendor_data_list` > `didit_internal_id_list`（仅使用优先级最高的一个选择器）。", "properties": { "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "您要删除的自身标识符，完全按照发送的内容进行匹配。" }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "要删除的 Didit 内部 UUID（`didit_internal_id`）。" }, "delete_all": { "type": "boolean", "default": false, "description": "若为 `true`，则删除该应用中的所有企业。不能与列表选择器结合使用。" } } }, "examples": { "Specific businesses": { "summary": "按 vendor_data 删除", "value": { "vendor_data_list": [ "company-123", "company-456" ] } }, "Specific internal IDs": { "summary": "按 didit_internal_id 删除", "value": { "didit_internal_id_list": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "b2c3d4e5-f6a7-8901-bcde-f12345678901" ] } }, "All businesses": { "summary": "清空此应用中的所有企业", "value": { "delete_all": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/businesses/delete/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data_list\": [\"company-123\", \"company-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.batch_delete(\n vendor_data_list=[\"company-123\", \"company-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.batchDelete({\n vendor_data_list: [\"company-123\", \"company-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.BatchDelete(ctx, didit.BusinessesBatchDeleteParams{\n\tVendorDataList: didit.Some([]string{\"company-123\", \"company-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BusinessesBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().batchDelete(BusinessesBatchDeleteParams.builder()\n .vendorDataList(List.of(\"company-123\", \"company-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->batchDelete([\n 'vendor_data_list' => ['company-123', 'company-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.batch_delete(vendor_data_list: [\"company-123\", \"company-456\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.BatchDeleteAsync(new BusinessesBatchDeleteParams\n{\n VendorDataList = new string[] { \"company-123\", \"company-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "企业已删除。返回实际移除的行数。", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "integer", "description": "已删除的企业数量（不包括未匹配任何内容的 vendor_data 值）。" } } }, "examples": { "Deleted some": { "value": { "deleted": 2 } }, "Nothing matched": { "value": { "deleted": 0 } } } } } }, "400": { "description": "未提供选择器（`vendor_data_list`、`didit_internal_id_list` 和 `delete_all` 全部缺失或为空）。错误正文为 JSON 数组。", "content": { "application/json": { "examples": { "Missing selector": { "value": [ "Provide vendor_data_list, didit_internal_id_list, or set delete_all=true." ] } } } } }, "403": { "description": "缺少、无效或已撤销的 API 密钥，或者该密钥无法删除此应用的企业。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } }, "409": { "description": "未删除任何内容。`code` 说明了原因：所选内容包含已定稿监管报告中的企业时为 `in_filed_report`，另一个请求仍在删除所选企业之一时为 `subject_deletion_in_progress`。请在该删除完成后重试请求。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/InFiledReportError" }, { "$ref": "#/components/schemas/SubjectDeletionInProgressError" } ] } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/users/aml-monitoring/": { "post": { "summary": "为用户启用或停用持续 AML 监控", "description": "为所选用户开启或关闭持续 AML 监控，语义与 Business Console 相同。每个用户恰好保留一份受监控的 AML 筛查，因此即使某个档案验证了多次，也仅监控一次并计费一次；禁用则会关闭该档案所有筛查的监控。没有任何 AML 筛查的用户，在具备所需的姓名、出生日期和国家/地区时会先进行筛查（按常规 AML 筛查计费）；否则将报告为 `skipped_no_identity_data`。\n\n设置 `estimate_only: true` 可预览数量和费用而无需写入任何内容。20 个或更少档案的选择将以内联方式解析，并在任务完成后返回 `200`；更大的选择将返回 `202` 并在后台运行：使用返回的 `job_id` 轮询 [Get AML monitoring job](#get-/v3/aml-monitoring/jobs/-job_id-/)。当组织余额不足以支付预估费用时，开启操作将被拒绝并返回 `403`。未匹配到任何内容的标识符列在 `unmatched` 中，绝不会导致请求失败：未匹配到任何内容的选择将作为空任务完成（`total` 为 0），这与批量删除 endpoint 的约定一致。", "operationId": "toggle_users_aml_monitoring", "x-didit-sdk": { "resource": "users", "method": "set_aml_monitoring", "auth": "api_key", "server": true }, "tags": [ "AML Ongoing Monitoring" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_enabled" ], "description": "使用 `vendor_data_list`、`didit_internal_id_list` 或两者同时选择用户（两个列表为“或”逻辑）。两个列表合计每次请求最多 1000 个标识符。", "properties": { "is_enabled": { "type": "boolean", "description": "为 true 表示启用监控，为 false 表示停用监控。" }, "estimate_only": { "type": "boolean", "default": false, "description": "为 true 时，返回费用估算且不执行任何写入：不进行筛查、不计费、不创建任务。" }, "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "您要切换的用户自身标识符，完全按照发送的内容进行匹配。" }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "要切换状态的用户的 Didit 内部 ID，即创建、获取和列表 endpoint 返回的 `didit_internal_id`。" } } }, "examples": { "Estimate first": { "summary": "预览费用而不进行写入", "value": { "is_enabled": true, "estimate_only": true, "vendor_data_list": [ "user-123", "user-456" ] } }, "Enable": { "summary": "为两名用户启用监控", "value": { "is_enabled": true, "vendor_data_list": [ "user-123", "user-456" ] } }, "Disable": { "summary": "按 Didit 内部 ID 禁用监控", "value": { "is_enabled": false, "didit_internal_id_list": [ "3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11" ] } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/users/aml-monitoring/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"is_enabled\": true, \"vendor_data_list\": [\"user-123\", \"user-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.set_aml_monitoring(\n is_enabled=True,\n estimate_only=True,\n vendor_data_list=[\"user-123\", \"user-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.setAmlMonitoring({\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"user-123\", \"user-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.SetAMLMonitoring(ctx, didit.UsersSetAMLMonitoringParams{\n\tIsEnabled: true,\n\tEstimateOnly: didit.Bool(true),\n\tVendorDataList: didit.Some([]string{\"user-123\", \"user-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.UsersSetAmlMonitoringParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().setAmlMonitoring(UsersSetAmlMonitoringParams.builder()\n .isEnabled(true)\n .estimateOnly(true)\n .vendorDataList(List.of(\"user-123\", \"user-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->setAmlMonitoring([\n 'is_enabled' => true,\n 'estimate_only' => true,\n 'vendor_data_list' => ['user-123', 'user-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.set_aml_monitoring(\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"user-123\", \"user-456\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.SetAmlMonitoringAsync(new UsersSetAmlMonitoringParams\n{\n IsEnabled = true,\n EstimateOnly = true,\n VendorDataList = new string[] { \"user-123\", \"user-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "估算结果（当 `estimate_only` 为 true 时）或以内联方式处理的选择的已完成任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringToggleResult" } } } }, "202": { "description": "较大的选择集将在后台处理。使用 `job_id` 轮询 job endpoint；随着档案的处理，`results` 会逐步填充。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringJob" } } } }, "400": { "description": "验证错误：`is_enabled` 缺失、无选择器，或者两个列表中的标识符总数超过 1000 个。" }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "余额不足，无法为此项选择启用监控。响应包含 `estimate`，以便您充值正确的金额。", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "estimate": { "type": "object", "description": "费用预览。当 estimate_only 为 true 时直接返回（不写入任何内容）。", "properties": { "users_total": { "type": "integer", "description": "所选条件匹配的档案。" }, "already_enabled": { "type": "integer", "description": "已处于监控状态的档案（启用时无需操作；禁用时将关闭这些档案的监控）。" }, "with_existing_aml": { "type": "integer", "description": "现有 AML 筛查将被切换为受监控状态的档案（不进行新的筛查）。" }, "needing_screening": { "type": "integer", "description": "没有任何 AML 筛查记录、将首先进行筛查的档案（按常规 AML 筛查计费）。" }, "skipped_no_identity_data": { "type": "integer", "description": "因缺少身份数据而无法进行筛查的档案。" }, "skipped_blocked": { "type": "integer", "description": "将被跳过的已拉黑用户（对于企业始终为 0）。" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "新增筛查的一次性费用。" }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "即将纳入监控的档案的年度监控成本。" }, "balance_sufficient": { "type": "boolean", "description": "组织余额是否足以支付筛查以及第一年的监控费用。" } } } } } } } } } } }, "/v3/businesses/aml-monitoring/": { "post": { "summary": "为企业启用或停用持续 AML 监控", "description": "为所选企业开启或关闭持续 AML 监控，语义与 Business Console 相同。每个企业恰好保留一份受监控的 AML 筛查，因此即使某个档案验证了多次，也仅监控一次并计费一次；禁用则会关闭该档案所有筛查的监控。没有任何 AML 筛查的企业，在具备所需的法定名称或显示名称时会先进行筛查（按常规 AML 筛查计费）；否则将报告为 `skipped_no_identity_data`。\n\n设置 `estimate_only: true` 可预览数量和费用而无需写入任何内容。20 个或更少档案的选择将以内联方式解析，并在任务完成后返回 `200`；更大的选择将返回 `202` 并在后台运行，请使用返回的 `job_id` 轮询 [Get AML monitoring job](#get-/v3/aml-monitoring/jobs/-job_id-/)。当组织余额不足以支付预估费用时，开启操作将被拒绝并返回 `403`。未匹配到任何内容的标识符列在 `unmatched` 中，绝不会导致请求失败：未匹配到任何内容的选择将作为空任务完成（`total` 为 0），这与批量删除 endpoint 的约定一致。", "operationId": "toggle_businesses_aml_monitoring", "x-didit-sdk": { "resource": "businesses", "method": "set_aml_monitoring", "auth": "api_key", "server": true }, "tags": [ "AML Ongoing Monitoring" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_enabled" ], "description": "使用 `vendor_data_list`、`didit_internal_id_list` 或两者同时选择企业（两个列表为“或”逻辑）。两个列表合计每次请求最多 1000 个标识符。", "properties": { "is_enabled": { "type": "boolean", "description": "为 true 表示启用监控，为 false 表示停用监控。" }, "estimate_only": { "type": "boolean", "default": false, "description": "为 true 时，返回费用估算且不执行任何写入：不进行筛查、不计费、不创建任务。" }, "vendor_data_list": { "type": "array", "items": { "type": "string" }, "description": "您要切换的企业自身标识符，完全按照发送的内容进行匹配。" }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "要切换状态的企业 Didit 内部 ID，即创建、获取和列表 endpoint 返回的 `didit_internal_id`。" } } }, "examples": { "Estimate first": { "summary": "预览费用而不进行写入", "value": { "is_enabled": true, "estimate_only": true, "vendor_data_list": [ "company-123", "company-456" ] } }, "Enable": { "summary": "为两家企业启用监控", "value": { "is_enabled": true, "vendor_data_list": [ "company-123", "company-456" ] } }, "Disable": { "summary": "按 Didit 内部 ID 禁用监控", "value": { "is_enabled": false, "didit_internal_id_list": [ "3f1c0d3e-8f0a-4c2e-9a3d-9b1f5f4a2c11" ] } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/businesses/aml-monitoring/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"is_enabled\": true, \"vendor_data_list\": [\"company-123\", \"company-456\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.set_aml_monitoring(\n is_enabled=True,\n estimate_only=True,\n vendor_data_list=[\"company-123\", \"company-456\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.setAmlMonitoring({\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"company-123\", \"company-456\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.SetAMLMonitoring(ctx, didit.BusinessesSetAMLMonitoringParams{\n\tIsEnabled: true,\n\tEstimateOnly: didit.Bool(true),\n\tVendorDataList: didit.Some([]string{\"company-123\", \"company-456\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BusinessesSetAmlMonitoringParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().setAmlMonitoring(BusinessesSetAmlMonitoringParams.builder()\n .isEnabled(true)\n .estimateOnly(true)\n .vendorDataList(List.of(\"company-123\", \"company-456\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->setAmlMonitoring([\n 'is_enabled' => true,\n 'estimate_only' => true,\n 'vendor_data_list' => ['company-123', 'company-456'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.set_aml_monitoring(\n is_enabled: true,\n estimate_only: true,\n vendor_data_list: [\"company-123\", \"company-456\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.SetAmlMonitoringAsync(new BusinessesSetAmlMonitoringParams\n{\n IsEnabled = true,\n EstimateOnly = true,\n VendorDataList = new string[] { \"company-123\", \"company-456\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "估算结果（当 `estimate_only` 为 true 时）或以内联方式处理的选择的已完成任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringToggleResult" } } } }, "202": { "description": "较大的选择集将在后台处理。使用 `job_id` 轮询 job endpoint；随着档案的处理，`results` 会逐步填充。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AMLMonitoringJob" } } } }, "400": { "description": "验证错误：`is_enabled` 缺失、无选择器，或者两个列表中的标识符总数超过 1000 个。" }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "余额不足，无法为此项选择启用监控。响应包含 `estimate`，以便您充值正确的金额。", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "estimate": { "type": "object", "description": "费用预览。当 estimate_only 为 true 时直接返回（不写入任何内容）。", "properties": { "users_total": { "type": "integer", "description": "所选条件匹配的档案。" }, "already_enabled": { "type": "integer", "description": "已处于监控状态的档案（启用时无需操作；禁用时将关闭这些档案的监控）。" }, "with_existing_aml": { "type": "integer", "description": "现有 AML 筛查将被切换为受监控状态的档案（不进行新的筛查）。" }, "needing_screening": { "type": "integer", "description": "没有任何 AML 筛查记录、将首先进行筛查的档案（按常规 AML 筛查计费）。" }, "skipped_no_identity_data": { "type": "integer", "description": "因缺少身份数据而无法进行筛查的档案。" }, "skipped_blocked": { "type": "integer", "description": "将被跳过的已拉黑用户（对于企业始终为 0）。" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "新增筛查的一次性费用。" }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "即将纳入监控的档案的年度监控成本。" }, "balance_sufficient": { "type": "boolean", "description": "组织余额是否足以支付筛查以及第一年的监控费用。" } } } } } } } } } } }, "/v3/aml-monitoring/jobs/{job_id}/": { "get": { "summary": "获取 AML 持续监控任务", "description": "从 `POST /v3/users/aml-monitoring/` 或 `POST /v3/businesses/aml-monitoring/` 启动的监控切换任务的状态、结果计数器及逐条记录结果。当 `status` 为 `PENDING` 或 `PROCESSING` 时，每隔几秒轮询一次；一旦变为 `COMPLETED`，`results` 即完整。", "operationId": "get_aml_monitoring_job", "x-didit-sdk": { "resource": "aml_monitoring", "method": "retrieve_job", "auth": "api_key", "server": true }, "tags": [ "AML Ongoing Monitoring" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "开关切换 endpoint 返回的 `job_id`。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl 'https://verification.didit.me/v3/aml-monitoring/jobs/JOB_ID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.aml_monitoring.retrieve_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.amlMonitoring.retrieveJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AMLMonitoring.RetrieveJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.amlMonitoring().retrieveJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "amlMonitoring->retrieveJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.aml_monitoring.retrieve_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.AmlMonitoring.RetrieveJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "作业。", "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean", "description": "当任务启用监控时为 true，停用监控时为 false。" }, "target_type": { "type": "string", "enum": [ "user", "business" ], "description": "该作业切换哪个配置文件系列。" }, "total": { "type": "integer", "description": "该任务处理的档案。" }, "processed": { "type": "integer", "description": "截至目前已处理的档案。" }, "outcomes": { "type": "object", "description": "每条记录的结果计数器。每个选定的个人资料都会准确归入一个计数器；不会静默跳过任何内容。", "properties": { "enabled": { "type": "integer", "description": "已在现有 AML 筛查上启用监控。" }, "screened_and_enabled": { "type": "integer", "description": "已创建新的 AML 筛查（已计费）并对其启用了监控。" }, "already_enabled": { "type": "integer", "description": "监控已处于活动状态；未发生任何更改，也未计费。" }, "disabled": { "type": "integer", "description": "已在该档案的所有 AML 筛查中关闭监控。" }, "skipped_no_identity_data": { "type": "integer", "description": "已跳过：资料缺少进行筛查所需的姓名、出生日期和国家/地区（用户）或名称（企业）。" }, "skipped_blocked": { "type": "integer", "description": "已跳过：用户已被封禁。" }, "skipped_sandbox": { "type": "integer", "description": "已跳过：沙盒应用，不创建筛查。" }, "failed_provider": { "type": "integer", "description": "无法完成筛查；请稍后重试。" }, "failed_insufficient_balance": { "type": "integer", "description": "任务运行时余额耗尽。" } } }, "results": { "type": "array", "description": "每个已处理的档案对应一个条目，按处理顺序排列。在任务运行期间逐步增加；状态变为 COMPLETED 时完成。对通过 API 启动的任务进行记录；从 Business Console 启动的任务仅报告计数器。", "items": { "type": "object", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "个人资料的 Didit 内部 ID。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您为资料指定的自身标识符。" }, "outcome": { "type": "string", "enum": [ "enabled", "screened_and_enabled", "already_enabled", "disabled", "skipped_no_identity_data", "skipped_blocked", "skipped_sandbox", "failed_provider", "failed_insufficient_balance" ] } } } }, "error": { "type": "string", "nullable": true, "description": "状态为 FAILED 时的通用失败消息；详细原因保留在平台端。" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "401": { "description": "API 密钥缺失或无效。" }, "404": { "description": "此应用不存在该作业。" } } } }, "/v3/users/{vendor_data}/update-status/": { "patch": { "summary": "更新用户状态", "description": "仅切换用户的生命周期 `status`：`ACTIVE`、`FLAGGED` 或 `BLOCKED`（非会话状态）。`BLOCKED` 会将 `vendor_data` 添加到系统黑名单中；脱离 `BLOCKED` 状态则会移除该条目。每次变更都会记录为用户的 `STATUS_CHANGED` 活动，并将可选的 `reason` 作为其 `comment`。发送当前状态不会产生任何更改，也不会记录 `reason`。`user.status.updated` Webhook 不包含 `reason`。", "operationId": "update_user_status", "x-didit-sdk": { "resource": "users", "method": "update_status", "auth": "api_key", "server": true }, "tags": [ "Users" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "schema": { "type": "string" }, "description": "您对该用户的唯一标识符。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/EntityStatusUpdateRequest" }, { "type": "object", "properties": { "reason": { "type": "string", "nullable": true, "maxLength": 1000, "description": "状态变更的原因。仅在状态实际变更时，记录在用户活动的状态变更条目（`comments[].comment`，以及 Business Console 中的 **Activity**）上。Webhook 不包含此项。" } } } ] }, "examples": { "Activate": { "summary": "重新激活用户", "value": { "status": "ACTIVE" } }, "Flag": { "summary": "标记用户以待审核", "value": { "status": "FLAGGED" } }, "Block": { "summary": "拉黑该用户（添加到系统黑名单）", "value": { "status": "BLOCKED" } }, "Block with reason": { "summary": "拉黑该用户并记录原因", "value": { "status": "BLOCKED", "reason": "Chargeback fraud pattern confirmed" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/users/user-abc-123/update-status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"status\": \"BLOCKED\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.update_status(\n \"user-123\",\n status=\"ACTIVE\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.updateStatus(\"user-123\", {\n status: \"ACTIVE\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.UpdateStatus(ctx, \"user-123\", didit.UsersUpdateStatusParams{\n\tStatus: \"ACTIVE\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.EntityStatusUpdateRequest;\nimport me.didit.types.UsersUpdateStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().updateStatus(\"user-123\", UsersUpdateStatusParams.builder()\n .status(EntityStatusUpdateRequest.Status.of(\"ACTIVE\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->updateStatus('user-123', [\n 'status' => 'ACTIVE',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.update_status(\n \"user-123\",\n status: \"ACTIVE\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.UpdateStatusAsync(\"user-123\", new UsersUpdateStatusParams\n{\n Status = \"ACTIVE\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "用户状态已更新。返回完整用户记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDetailItem" }, "examples": { "Blocked": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Michael Doe", "date_of_birth": "1990-05-15", "effective_name": "John Michael Doe", "status": "BLOCKED", "metadata": { "tier": "premium", "source": "website" }, "portrait_image_url": "https:///...", "session_count": 3, "approved_count": 2, "declined_count": 0, "in_review_count": 1, "issuing_states": [ "USA" ], "approved_emails": [ "john@example.com" ], "approved_phones": [ "+14155551234" ], "features": { "ID_VERIFICATION": "Approved", "LIVENESS": "Approved", "FACE_MATCH": "Approved", "AML": "Approved" }, "features_list": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" }, { "feature": "AML", "status": "Approved" } ], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-01T08:00:00Z", "tags": [ { "uuid": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "tag": { "uuid": "e1f2a3b4-c5d6-4e7f-8a9b-0c1d2e3f4a5b", "name": "VIP", "color": "#2567FF", "description": null, "source": "custom", "created_at": "2025-05-01T09:00:00Z", "updated_at": "2025-05-01T09:00:00Z" }, "added_by_email": "analyst@acme.com", "added_by_name": "Jane Analyst", "created_at": "2025-06-02T11:00:00Z" } ], "comments": [ { "uuid": "c1111111-2222-4333-8444-555555555555", "comment_type": "STATUS_CHANGED", "comment": "Chargeback fraud pattern confirmed", "actor_email": null, "actor_name": null, "previous_status": "ACTIVE", "new_status": "BLOCKED", "previous_value": null, "new_value": null, "changed_fields": [], "metadata": null, "mentioned_emails": [], "created_at": "2025-06-15T10:30:00Z" } ], "created_at": "2025-06-01T08:00:00Z", "updated_at": "2025-06-15T10:30:00Z" } } } } } }, "400": { "description": "`status` 缺失或无效，或 `reason` 超过 1000 个字符。", "content": { "application/json": { "examples": { "Missing status": { "value": { "status": [ "This field is required." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Reason too long": { "value": { "reason": [ "Ensure this field has no more than 1000 characters." ] } } } } } }, "401": { "description": "未提供凭证。对 `/v3/users/*` 路径的请求如果不包含 `x-api-key` 请求头（或 `Authorization: Bearer` token），将在到达 API 之前被身份验证中间件拒绝。", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "该密钥无法更新此应用的用户。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "该应用下不存在带有提供的 `vendor_data` 的（未删除）用户。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/businesses/create/": { "post": { "summary": "创建企业", "description": "预先创建[企业](/entities/businesses)（*不*包含 KYB 会话）。所有字段均为可选，但您应始终发送 `vendor_data`，若缺少该字段，该记录将无法与会话或交易关联。提供时，`vendor_data` 在未删除的企业中必须唯一（精确匹配；冲突将返回 400）。非幂等。", "operationId": "create_business", "x-didit-sdk": { "resource": "businesses", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Businesses" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您对此企业的唯一标识符（自由格式字符串，非 UUID）。可选但强烈建议提供。提供时，在该应用中未删除的企业之间必须唯一；按发送的内容精确匹配。" }, "display_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "控制台中显示的易读显示名称（在界面显示时优先级高于 `legal_name`）。" }, "legal_name": { "type": "string", "nullable": true, "maxLength": 255, "description": "企业的官方法定名称。" }, "registration_number": { "type": "string", "nullable": true, "maxLength": 100, "description": "企业注册号或成立号。" }, "country_code": { "type": "string", "nullable": true, "maxLength": 10, "description": "注册国家/地区（ISO 3166-1 alpha-2，例如 `GB`、`US`）。" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "default": "ACTIVE", "description": "初始生命周期状态。默认为 `ACTIVE`。" }, "metadata": { "type": "object", "nullable": true, "description": "附加到企业的任意 JSON 对象。默认为 `{}`。" } } }, "examples": { "Basic": { "summary": "建议的最小值", "value": { "vendor_data": "company-456", "legal_name": "New Corp Ltd", "country_code": "US" } }, "Full": { "summary": "所有字段", "value": { "vendor_data": "company-789", "display_name": "New Corp", "legal_name": "New Corp International Ltd", "registration_number": "98765432", "country_code": "DE", "status": "ACTIVE", "metadata": { "industry": "fintech", "tier": "enterprise" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/businesses/create/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data\": \"company-456\", \"legal_name\": \"New Corp Ltd\", \"country_code\": \"US\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.businesses.create(\n vendor_data=\"company-456\",\n legal_name=\"New Corp Ltd\",\n country_code=\"US\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.businesses.create({\n vendor_data: \"company-456\",\n legal_name: \"New Corp Ltd\",\n country_code: \"US\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.Create(ctx, didit.BusinessesCreateParams{\n\tVendorData: didit.String(\"company-456\"),\n\tLegalName: didit.String(\"New Corp Ltd\"),\n\tCountryCode: didit.String(\"US\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BusinessesCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.businesses().create(BusinessesCreateParams.builder()\n .vendorData(\"company-456\")\n .legalName(\"New Corp Ltd\")\n .countryCode(\"US\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->create([\n 'vendor_data' => 'company-456',\n 'legal_name' => 'New Corp Ltd',\n 'country_code' => 'US',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.businesses.create(\n vendor_data: \"company-456\",\n legal_name: \"New Corp Ltd\",\n country_code: \"US\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.CreateAsync(new BusinessesCreateParams\n{\n VendorData = \"company-456\",\n LegalName = \"New Corp Ltd\",\n CountryCode = \"US\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "企业已创建。返回完整企业记录（数据结构与获取企业相同）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDetailItem" }, "examples": { "Created": { "value": { "didit_internal_id": "a1b2c3d4-e5f6-4890-abcd-ef1234567890", "vendor_data": "company-456", "display_name": null, "legal_name": "New Corp Ltd", "registration_number": null, "country_code": "US", "effective_name": "New Corp Ltd", "status": "ACTIVE", "session_count": 0, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "features": {}, "features_list": [], "last_session_at": null, "last_activity_at": "2026-03-15T10:30:00Z", "first_session_at": null, "tags": [], "created_at": "2026-03-15T10:30:00Z", "metadata": {}, "updated_at": "2026-03-15T10:30:00Z" } } } } } }, "400": { "description": "无效的请求体，通常是重复的 `vendor_data`、未知的 `status` 或格式错误的 `metadata`。", "content": { "application/json": { "examples": { "Duplicate": { "value": { "vendor_data": [ "A business with this vendor_data already exists." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Bad metadata": { "value": { "metadata": [ "Metadata must be a JSON object." ] } } } } } }, "403": { "description": "API 密钥缺失、无效或已撤销，或者该密钥无法为此应用创建企业。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/users/create/": { "post": { "summary": "创建用户", "description": "在验证会话之前或无需验证会话的情况下，通过 `vendor_data` 创建[用户](/entities/users)。`vendor_data` 在应用的用户中必须唯一（重复将返回 `400`）。非幂等。\n\n**联系方式：**`email` 和 `phone_number` 存储在 `metadata.contact` 中，`country` 存储在 `metadata.address` 中。当您发送 `first_name` 或 `last_name` 但未提供 `full_name` 时，Didit 会将它们拼接为 `full_name`。\n\n**验证链接：**设置 `send_verification_link: true` 时，Didit 还会根据 `workflow_id` 为该人员创建一个验证会话，并通过电子邮件将链接发送至 `email`。该会话运行与[创建会话](/zh/sessions-api/create-session)相同的检查，例如黑名单和您的额度余额。该人员和会话要么同时创建，要么完全不创建：如果有任何检查失败，则不会写入任何内容，也不会发送电子邮件。响应中的 `verification_link` 描述了该会话；当您未请求链接时，其值为 `null`。\n\n**API 密钥访问权限：**作用域 API 密钥需要 `users` 写入权限。在 `send_verification_link: true` 的情况下，它还需要 `sessions` 写入权限，否则调用将在写入任何内容之前返回 `403`。全权限密钥不受影响。参见 [API 密钥](/zh/console/api-keys)。", "operationId": "create_user", "x-didit-sdk": { "resource": "users", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Users" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vendor_data" ], "properties": { "vendor_data": { "type": "string", "description": "您对此用户的唯一标识符（自由格式字符串，非 UUID）。在该应用的用户之间必须唯一；按发送的内容精确匹配。" }, "full_name": { "type": "string", "nullable": true, "maxLength": 512, "description": "用户的法定姓名。" }, "display_name": { "type": "string", "nullable": true, "description": "控制台中显示的易读显示名称（在界面显示时优先级高于 `full_name`）。", "maxLength": 255 }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "`YYYY-MM-DD` 格式的出生日期。" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "default": "ACTIVE", "description": "初始生命周期状态。默认为 `ACTIVE`。" }, "metadata": { "type": "object", "nullable": true, "description": "附加到用户的任意 JSON 对象。默认为 `{}`。" }, "approved_emails": { "type": "array", "items": { "type": "string" }, "description": "该用户的预信任邮箱地址，例如 `[\"john@example.com\"]`。" }, "approved_phones": { "type": "array", "items": { "type": "string" }, "description": "该用户的预信任电话号码，例如 `[\"+14155551234\"]`。" }, "issuing_states": { "type": "array", "items": { "type": "string" }, "description": "预先记录的签发国家/地区（ISO 3166-1 alpha-3），例如 `[\"USA\"]`。" }, "first_name": { "type": "string", "maxLength": 255, "description": "名字。未发送 `full_name` 时，Didit 会使用空格将 `first_name` 和 `last_name` 拼接为 `full_name`。不作为单独字段返回。" }, "last_name": { "type": "string", "maxLength": 255, "description": "姓氏。未发送 `full_name` 时，将与 `first_name` 拼接为 `full_name`。不作为单独字段返回。" }, "email": { "type": "string", "format": "email", "description": "联系邮箱，存储在 `metadata.contact.email` 中（它会替换您在 `metadata.contact` 内发送的 `email`）。当 `send_verification_link` 为 `true` 时必填：验证链接将发送至此地址。如果 `metadata.contact` 不是 JSON 对象，则调用将针对此字段返回 `400`。" }, "phone_number": { "type": "string", "maxLength": 32, "description": "联系电话号码，存储在 `metadata.contact.phone_number` 中。如果 `metadata.contact` 不是 JSON 对象，该调用会因该字段返回 `400`。" }, "country": { "type": "string", "maxLength": 3, "description": "ISO 3166 代码格式的国家/地区，alpha-2 或 alpha-3（`ES` 或 `ESP`）。以大写形式存储在 `metadata.address.country` 中。如果 `metadata.address` 不是 JSON 对象，则该调用针对该字段返回 `400`。" }, "send_verification_link": { "type": "boolean", "default": false, "description": "为 `true` 时，Didit 会根据 `workflow_id` 为该人员创建验证会话，并通过电子邮件将链接发送至 `email`。需要提供 `email` 和 `workflow_id`。限定权限的 API 密钥还需要具备 `sessions` 写入权限。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "验证会话的工作流。当 `send_verification_link` 为 `true` 时必填。该工作流必须验证个人：企业验证（KYB）工作流将被拒绝。其他情况下忽略。" }, "language": { "type": "string", "maxLength": 10, "description": "验证邮件的语言，采用[支持的语言](/zh/integration/supported-languages)代码。省略时为英语。当 `send_verification_link` 不为 `true` 时忽略。" } } }, "examples": { "Basic": { "summary": "使用基本信息创建", "value": { "vendor_data": "user-abc-123", "full_name": "John Doe" } }, "Full": { "summary": "所有字段", "value": { "vendor_data": "user-abc-456", "full_name": "Jane Smith", "display_name": "Jane S.", "date_of_birth": "1990-05-15", "status": "ACTIVE", "metadata": { "tier": "premium", "source": "api" }, "approved_emails": [ "jane@example.com" ] } }, "Contact details": { "summary": "姓名、邮箱、电话和国家/地区", "value": { "vendor_data": "user-abc-789", "first_name": "Julia", "last_name": "Martin", "email": "julia.martin@example.com", "phone_number": "+34600000000", "country": "ES" } }, "With verification link": { "summary": "创建该人员并通过电子邮件向其发送验证链接", "value": { "vendor_data": "user-abc-789", "first_name": "Julia", "last_name": "Martin", "email": "julia.martin@example.com", "send_verification_link": true, "workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "language": "es" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/users/create/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vendor_data\": \"user-abc-123\", \"full_name\": \"John Doe\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.users.create(\n vendor_data=\"user-abc-123\",\n full_name=\"John Doe\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.users.create({\n vendor_data: \"user-abc-123\",\n full_name: \"John Doe\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Users.Create(ctx, didit.UsersCreateParams{\n\tVendorData: \"user-abc-123\",\n\tFullName: didit.String(\"John Doe\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.UsersCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.users().create(UsersCreateParams.builder()\n .vendorData(\"user-abc-123\")\n .fullName(\"John Doe\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->create([\n 'vendor_data' => 'user-abc-123',\n 'full_name' => 'John Doe',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.users.create(\n vendor_data: \"user-abc-123\",\n full_name: \"John Doe\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Users.CreateAsync(new UsersCreateParams\n{\n VendorData = \"user-abc-123\",\n FullName = \"John Doe\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "用户已创建。完整的用户记录（格式与获取用户相同），加上 `verification_link`：当 `send_verification_link` 为 `true` 时为 Didit 发送邮件的验证会话，否则为 `null`。", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UserDetailItem" }, { "type": "object", "required": [ "verification_link" ], "properties": { "verification_link": { "type": "object", "nullable": true, "description": "Didit 创建并通过电子邮件发送给该人员的验证会话。始终存在：当 `send_verification_link` 不为 `true` 时为 `null`。", "required": [ "session_id", "session_number", "status", "url", "workflow_id", "email" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "验证会话的 ID。" }, "session_number": { "type": "integer", "description": "您应用内该会话的序号。" }, "status": { "type": "string", "description": "会话的状态，刚创建的会话为 `Not Started`。" }, "url": { "type": "string", "format": "uri", "description": "Didit 通过电子邮件发送给该人员的验证链接。" }, "workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "会话运行的工作流。" }, "email": { "type": "string", "format": "email", "description": "链接发送的目标地址。" } } } } } ] }, "examples": { "Created": { "value": { "didit_internal_id": "f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418", "vendor_data": "user-abc-123", "display_name": null, "full_name": "John Doe", "date_of_birth": null, "effective_name": "John Doe", "status": "ACTIVE", "metadata": {}, "portrait_image_url": null, "session_count": 0, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "issuing_states": [], "approved_emails": [], "approved_phones": [], "features": {}, "features_list": [], "last_session_at": null, "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": null, "tags": [], "comments": [], "created_at": "2025-06-15T10:30:00Z", "updated_at": "2025-06-15T10:30:00Z", "verification_link": null } }, "Created with verification link": { "value": { "didit_internal_id": "9b2f6c1e-3d4a-4e5f-8a7b-1c2d3e4f5a6b", "vendor_data": "user-abc-789", "display_name": null, "full_name": "Julia Martin", "date_of_birth": null, "effective_name": "Julia Martin", "status": "ACTIVE", "metadata": { "contact": { "email": "julia.martin@example.com" } }, "portrait_image_url": null, "session_count": 1, "approved_count": 0, "declined_count": 0, "in_review_count": 0, "issuing_states": [], "approved_emails": [], "approved_phones": [], "features": {}, "features_list": [], "last_session_at": "2025-06-15T10:30:00Z", "last_activity_at": "2025-06-15T10:30:00Z", "first_session_at": "2025-06-15T10:30:00Z", "tags": [], "comments": [], "created_at": "2025-06-15T10:30:00Z", "updated_at": "2025-06-15T10:30:00Z", "verification_link": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa7", "session_number": 43762, "status": "Not Started", "url": "https://verify.didit.me/en/session/3FaJ9wLqX2Mz", "workflow_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "email": "julia.martin@example.com" } } } } } } }, "400": { "description": "无效的请求体，按字段索引：通常是重复的 `vendor_data`、缺少必填字段或格式错误的值。在设置了 `send_verification_link: true` 的情况下，还可能是缺少 `email` 或 `workflow_id`、未知或企业验证（KYB）工作流、不受支持的 `language`（字段键为 `contact_details.email_lang`）、被列入黑名单的 `vendor_data`，或者额度不足以启动会话。未写入任何内容。", "content": { "application/json": { "examples": { "Duplicate": { "value": { "vendor_data": [ "A user with this vendor_data already exists." ] } }, "Missing vendor_data": { "value": { "vendor_data": [ "This field is required." ] } }, "Bad metadata": { "value": { "metadata": [ "Metadata must be a JSON object." ] } }, "Bad status": { "value": { "status": [ "Invalid status. Valid options are: ACTIVE, FLAGGED, BLOCKED" ] } }, "Bad country": { "value": { "country": [ "Use an ISO 3166 country code, like ES or ESP." ] } }, "Contact not an object": { "value": { "email": [ "metadata.contact must be a JSON object to store this value." ] } }, "Address not an object": { "value": { "country": [ "metadata.address must be a JSON object to store this value." ] } }, "Link without email or workflow": { "value": { "email": [ "An email address is required to send a verification link." ], "workflow_id": [ "Pick the workflow to send a verification link for." ] } }, "Unknown workflow": { "value": { "workflow_id": [ "Invalid workflow_id." ] } }, "Business workflow": { "value": { "workflow_id": [ "This workflow verifies a business. Pick a workflow that verifies a person to send them a verification link." ] } }, "Blocklisted vendor_data": { "value": { "vendor_data": "This user or business has been blocked and cannot create new verification sessions." } }, "Insufficient credits": { "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "401": { "description": "未提供凭证。对 `/v3/users/*` 路径的请求如果不包含 `x-api-key` 请求头（或 `Authorization: Bearer` token），将在到达 API 之前被身份验证中间件拒绝。", "content": { "application/json": { "examples": { "Missing credentials": { "value": { "detail": "You must be authenticated with a valid access token to access this endpoint." } } } } } }, "403": { "description": "无效或已撤销的 API 密钥，或者该密钥无法为此应用创建用户。限定范围的 API 密钥需要 `users` 写入权限，且在 `send_verification_link` 为 `true` 时还需要 `sessions` 写入权限；未写入任何内容。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } }, "No sessions write": { "summary": "作用域密钥在没有 sessions 写入权限的情况下请求验证链接", "value": { "detail": "This API key has no write access to sessions." } } } } } }, "429": { "description": "超出速率限制；请退避并在 `Retry-After` 指定的间隔后重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/": { "post": { "summary": "上传用户人脸", "description": "将受信任的已导入人脸图像关联至现有的用户档案。在通过 `vendor_data` 创建或检索用户并读取其 `didit_internal_id` 后使用此功能。上传的人脸将存储在该用户档案中，并建立索引以用于重复项检测和人脸搜索。它不会被添加到人脸黑名单中。", "operationId": "upload_user_face", "x-didit-sdk": { "resource": "users", "method": "upload_face", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Users" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "拥有该应用的组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "拥有该用户资料的应用 UUID。" }, { "name": "didit_internal_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Didit 内部用户 UUID，由 `GET /v3/users/{vendor_data}/` 和 `POST /v3/users/create/` 作为 `didit_internal_id` 返回。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "format": "byte", "description": "原始 base64 编码的 JPG 或 PNG 人脸图像。请勿包含 `data:image/...;base64,` 前缀。解码后的最大尺寸：2 MB。" }, "comment": { "type": "string", "description": "针对所上传人脸的可选备注，操作员可见。", "default": "" } } }, "examples": { "Imported face": { "summary": "关联从之前提供商导入的人脸", "value": { "image": "/9j/4AAQSkZJRgABAQEA...", "comment": "Imported from previous KYC provider" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/vendor-users/by-id/f4e5e1f2-94a9-4f86-8c16-2b7d9b4db418/faces/upload/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"image\": \"/9j/4AAQSkZJRgABAQEA...\", \"comment\": \"Imported from previous KYC provider\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image=\"/9j/4AAQSkZJRgABAQEA...\",\n comment=\"Imported from previous KYC provider\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.uploadFace(\"11111111-2222-3333-4444-555555555555\", {\n image: \"/9j/4AAQSkZJRgABAQEA...\",\n comment: \"Imported from previous KYC provider\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.UsersUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQEA...\",\n\tComment: didit.String(\"Imported from previous KYC provider\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.UsersUploadFaceParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().uploadFace(\"11111111-2222-3333-4444-555555555555\", UsersUploadFaceParams.builder()\n .image(\"/9j/4AAQSkZJRgABAQEA...\")\n .comment(\"Imported from previous KYC provider\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->uploadFace('11111111-2222-3333-4444-555555555555', [\n 'image' => '/9j/4AAQSkZJRgABAQEA...',\n 'comment' => 'Imported from previous KYC provider',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image: \"/9j/4AAQSkZJRgABAQEA...\",\n comment: \"Imported from previous KYC provider\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.UploadFaceAsync(\"11111111-2222-3333-4444-555555555555\", new UsersUploadFaceParams\n{\n Image = \"/9j/4AAQSkZJRgABAQEA...\",\n Comment = \"Imported from previous KYC provider\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "人脸已上传并附加到用户个人资料中。", "content": { "application/json": { "schema": { "type": "object", "required": [ "uuid", "image_url", "comment", "uploaded_by", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "已上传用户人脸记录的 UUID。" }, "image_url": { "type": "string", "format": "uri", "nullable": true, "description": "已上传人脸图像的签名 URL。" }, "comment": { "type": "string", "nullable": true, "description": "上传人脸时提供的备注。" }, "uploaded_by": { "type": "string", "nullable": true, "description": "上传者的邮箱或操作者标识符（若可用）。" }, "created_at": { "type": "string", "format": "date-time", "description": "上传时间戳。" } } }, "examples": { "Uploaded": { "value": { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "image_url": "https://signed-url.example/face.jpg", "comment": "Imported from previous KYC provider", "uploaded_by": "api", "created_at": "2026-05-18T12:00:00Z" } } } } } }, "400": { "description": "无效的请求体或图像。常见原因：无效的 base64、无效的图像、未检测到人脸、图像超过 2 MB、缺少人脸特征向量，或用户已上传 5 张人脸。", "content": { "application/json": { "examples": { "No face": { "value": { "image": "No face detected in the image. Please upload a clear photo with a visible face." } }, "Too many faces": { "value": { "detail": "Maximum of 5 faces per user reached." } }, "Too large": { "value": { "image": "Image exceeds maximum size of 2 MB." } } } } } }, "401": { "description": "API 密钥缺失或无效。", "content": { "application/json": { "examples": { "Missing key": { "value": { "detail": "Authentication credentials were not provided." } } } } } }, "403": { "description": "凭证有效，但无法为此应用写入用户资料。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "该应用中不存在与该 `didit_internal_id` 对应的用户。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Not found." } } } } } }, "429": { "description": "超出速率限制；请退避并重试。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "Request was throttled. Expected available in 30 seconds." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/update-data/": { "patch": { "summary": "更新验证会话中从身份证件提取的 KYC 数据", "description": "在验证完成后，更正从用户的身份证件中提取（OCR / NFC）的身份字段（例如误读的姓名、日期、证件号码等）。典型的调用方是在您自有后台工作的合规分析师，或自动化对账任务。请求体中的每个字段都是可选的：仅写入您发送的键，其余所有内容均保持不变（`PATCH` 语义）。\n\n该会话必须属于您的应用，并且处于 `Approved`、`Declined`、`In Review` 或 `Kyc Expired` 状态。处于任何其他状态（例如仍处于 `In Progress`）的会话将返回 `404` 及 `\"No Session matches the given query.\"`，这与未知的或已删除的 `sessionId` 所返回的 `\"Not found.\"` 不同。该会话还必须包含身份证件验证（KYC）记录：其工作流从未运行过身份证件验证步骤的会话将返回 `404`（`\"The session does not have a KYC.\"`）。对于具有多个身份证件验证步骤的图谱工作流，可以通过 `node_id`（查询参数或请求体字段）指定特定步骤；若省略，则会对最新的 KYC 记录进行 PATCH 更新。\n\n每次调用时都会重新计算两个派生字段：`full_name`（基于 `first_name` + `last_name`）和 `issuing_state_name`（基于 `issuing_state`）。如果自由文本 `address` 发生更改，服务器还可能会重新对其进行地理编码并刷新 `parsed_address`（沙盒会话会跳过此项）。`extra_fields` 和 `parsed_address` 采用按键合并而非替换，有关传 `null` 表示删除的语义，请参阅各个字段的说明。\n\n提交至少一个有效字段会触发 `data.updated` [Webhook](/zh/integration/webhooks)（触发器为 `manual_review`），即使提交的值与已存储的值相同也是如此。当值确实发生更改时，一条记录了更改字段以及先前值和新值的 `KYC_DATA_UPDATED` 活动条目将附加到该会话的 `reviews` 中，可在[获取决策](#get-/v3/session/-sessionId-/decision/)以及控制台活动时间线中查看。会话的状态和决策**不会**被重新评估，请使用[更新状态](#patch-/v3/session/-sessionId-/update-status/)来更改结果。空的 JSON 请求体（`{}`）是允许的，将仅返回当前 KYC 数据且不会触发 Webhook。\n\n支持 API 密钥或控制台用户 token；无论使用哪种方式，凭据都需要具备 `write:sessions` 权限。身份验证和权限失败均会返回 `403`，该 API 从不响应 `401`。请注意，会话查找会在凭据检查之前运行，因此即使凭据缺失，未知的 `sessionId` 也会返回 `404`。该 endpoint 对每个 API 密钥设置了每分钟 10 次请求的专属速率限制（无效请求也计入）；每分钟 300 次请求的共享写入预算同样适用。", "operationId": "patch_v3_session_update_data", "x-didit-sdk": { "resource": "sessions", "method": "update_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "您正在更正其提取的证件数据的用户验证（KYC）会话的 UUID。企业（KYB）会话 ID 在此处无效 — 如需更新企业数据，请使用[更新 KYB 企业数据](#patch-/v3/session/-sessionId-/kyb/-companyUuid-/update-data/)。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "针对包含多个身份证件验证步骤的图谱工作流，指定要更新其 KYC 记录的工作流图谱节点（也可在请求体中通过 `node_id` 字段传入）。省略时，将更新该会话中最新的 KYC 记录。如果指定节点不存在 KYC，调用将返回 `404`（`\"The session does not have a KYC for node ''.\"`）。", "schema": { "type": "string", "example": "feature_ocr" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "所有字段均为可选，仅发送您想要更改的内容。", "properties": { "document_type": { "type": "string", "description": "证件类型代码。接受枚举中列出的短代码，以及在验证前由服务端规范化的六个完整形式别名：`Passport` → `P`、`Identity Card` → `ID`、`Driver's License` → `DL`、`Residence Permit` → `RP`、`Health Insurance Card` → `HIC`、`Tax Card` → `TC`。任何其他值（包括大写的 `PASSPORT`）均会返回 `400`。", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "nullable": true, "example": "P" }, "document_subtype": { "type": "string", "maxLength": 128, "nullable": true, "description": "证件注册表中的证件子类型，在注册表区分地区变体时包含地区前缀。" }, "document_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "身份证件上印制的证件号码。", "example": "PAB123456" }, "personal_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "证件上所载的个人/国民身份证号码（例如护照上的西班牙 DNI）。", "example": "99999999R" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "`YYYY-MM-DD` 格式的出生日期。任何其他格式均返回 `400`。", "example": "1980-01-01" }, "date_of_issue": { "type": "string", "format": "date", "nullable": true, "description": "证件签发日期，格式为 `YYYY-MM-DD`。" }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "证件的到期日期，格式为 `YYYY-MM-DD`。" }, "issuing_state": { "type": "string", "nullable": true, "description": "签发国家/地区，采用 ISO 3166-1 alpha-3 代码。不区分大小写（`esp` 会存储为 `ESP`）；[获取决策](#get-/v3/session/-sessionId-/decision/) 中显示的可读 `issuing_state_name` 会根据此值重新计算。无效代码将返回 `400`。", "example": "ESP" }, "first_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "名字。每次调用此 endpoint 时，存储的 `full_name` 都会重新计算为 `first_name + ' ' + last_name`。", "example": "Carmen" }, "last_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "姓氏。同时用于重新计算 `full_name`。", "example": "Espanola Espanola" }, "gender": { "type": "string", "enum": [ "M", "F", "U" ], "nullable": true, "description": "证件上印刷的性别：`M`（男）、`F`（女）或 `U`（未知）。任何其他值（包括 `X`）均返回 `400`。" }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "印在证件上的自由文本地址。当该值发生变化（仅限非沙盒会话）且结构化地址仍然缺失或不完整时，服务器会在响应前同步重新进行地理编码，200 响应体已反映更新后的 `parsed_address`。重新进行地理编码还要求 KYC 记录中存在 `issuing_state`。" }, "place_of_birth": { "type": "string", "maxLength": 255, "nullable": true, "description": "证件上印刷的出生地点。" }, "nationality": { "type": "string", "maxLength": 32, "nullable": true, "description": "证件上印刷的国籍。最多 32 个字符的自由文本，通常为 ISO 3166-1 alpha-3 代码（例如 `ESP`），但不会按该标准进行格式校验。" }, "marital_status": { "type": "string", "enum": [ "SINGLE", "MARRIED", "DIVORCED", "WIDOWED", "UNKNOWN" ], "description": "证件上注明的婚姻状况。任何其他值均返回 `400`。" }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "针对证件特定额外字段（例如 `blood_group`、`dl_categories`、`mrz_string`）的按键覆盖项。键会合并到现有的覆盖映射中：传入带有值的键进行设置，或传入 `null` / `\"\"` 从合并视图中移除该键。将整个字段传为 `null` 可清除之前应用的所有覆盖项。必须为 JSON 对象，否则返回 `400`。响应始终返回合并视图（应用了您的覆盖项的 OCR 提取值）。" }, "parsed_address": { "type": "object", "nullable": true, "description": "结构化地址。仅接受以下嵌套键：`address_type`、`city`、`region`、`street_1`、`street_2`、`postal_code`、`country`，任何其他键都会返回 `400`。各键的语义：传入值设置该键，`null` 删除该键。`formatted_address` 在服务端通过拼接 `street_1`、`street_2`、`city`、`region`、`postal_code` 和 `country` 重新计算并在响应中返回，您无法直接对其进行设置。", "properties": { "address_type": { "type": "string", "nullable": true, "description": "自由格式地址分类（例如 `home`）。" }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "州 / 省 / 自治区。" }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 国家/地区代码。小写输入将被规范化为大写；alpha-3 代码将被拒绝并返回 `400`。", "example": "ES" } } } } }, "examples": { "Correct name and DOB": { "summary": "修正 OCR 误读的姓名、出生日期和结构化地址", "value": { "first_name": "Carmen", "last_name": "Espanola Espanola", "date_of_birth": "1980-01-01", "issuing_state": "ESP", "marital_status": "MARRIED", "extra_fields": { "blood_group": "O+" }, "parsed_address": { "street_1": "Avda de Madrid 34", "city": "Madrid", "postal_code": "28013", "country": "ES" } } }, "Remove an extra field": { "summary": "删除一个额外字段键，保留其余字段", "value": { "extra_fields": { "blood_group": null } } }, "Long-form document type": { "summary": "完整形式的别名已规范化为短代码（此处为 P）", "value": { "document_type": "Passport" } } } } } }, "responses": { "200": { "description": "KYC 数据已更新。返回**当前完整的 KYC 记录**（包含每个可更新字段及其存储值，加上合并后的 `extra_fields` 和当前的 `parsed_address`），而不仅限于您提交的字段。当 payload 中至少包含一个有效字段时，将触发 `data.updated` Webhook。", "content": { "application/json": { "schema": { "type": "object", "properties": { "document_type": { "type": "string", "description": "证件类型代码。接受枚举中列出的短代码，以及在验证前由服务端规范化的六个完整形式别名：`Passport` → `P`、`Identity Card` → `ID`、`Driver's License` → `DL`、`Residence Permit` → `RP`、`Health Insurance Card` → `HIC`、`Tax Card` → `TC`。任何其他值（包括大写的 `PASSPORT`）均会返回 `400`。", "enum": [ "P", "DL", "ID", "RP", "SSC", "HIC", "WP", "TC", "VISA", "PSC", "BC", "OTHER" ], "nullable": true, "example": "P" }, "document_subtype": { "type": "string", "maxLength": 128, "nullable": true, "description": "证件注册表中的证件子类型，在注册表区分地区变体时包含地区前缀。" }, "document_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "身份证件上印制的证件号码。", "example": "PAB123456" }, "personal_number": { "type": "string", "maxLength": 255, "nullable": true, "description": "证件上所载的个人/国民身份证号码（例如护照上的西班牙 DNI）。", "example": "99999999R" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "`YYYY-MM-DD` 格式的出生日期。任何其他格式均返回 `400`。", "example": "1980-01-01" }, "date_of_issue": { "type": "string", "format": "date", "nullable": true, "description": "证件签发日期，格式为 `YYYY-MM-DD`。" }, "expiration_date": { "type": "string", "format": "date", "nullable": true, "description": "证件的到期日期，格式为 `YYYY-MM-DD`。" }, "issuing_state": { "type": "string", "nullable": true, "description": "签发国家/地区，采用 ISO 3166-1 alpha-3 代码。不区分大小写（`esp` 会存储为 `ESP`）；[获取决策](#get-/v3/session/-sessionId-/decision/) 中显示的可读 `issuing_state_name` 会根据此值重新计算。无效代码将返回 `400`。", "example": "ESP" }, "first_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "名字。每次调用此 endpoint 时，存储的 `full_name` 都会重新计算为 `first_name + ' ' + last_name`。", "example": "Carmen" }, "last_name": { "type": "string", "maxLength": 255, "nullable": true, "description": "姓氏。同时用于重新计算 `full_name`。", "example": "Espanola Espanola" }, "gender": { "type": "string", "enum": [ "M", "F", "U" ], "nullable": true, "description": "证件上印刷的性别：`M`（男）、`F`（女）或 `U`（未知）。任何其他值（包括 `X`）均返回 `400`。" }, "address": { "type": "string", "maxLength": 255, "nullable": true, "description": "印在证件上的自由文本地址。当该值发生变化（仅限非沙盒会话）且结构化地址仍然缺失或不完整时，服务器会在同一请求的后台重新进行地理编码，并可能用地理编码结果覆盖 `parsed_address`。" }, "place_of_birth": { "type": "string", "maxLength": 255, "nullable": true, "description": "证件上印刷的出生地点。" }, "nationality": { "type": "string", "maxLength": 32, "nullable": true, "description": "证件上印刷的国籍。最多 32 个字符的自由文本，通常为 ISO 3166-1 alpha-3 代码（例如 `ESP`），但不会按该标准进行格式校验。" }, "marital_status": { "type": "string", "enum": [ "SINGLE", "MARRIED", "DIVORCED", "WIDOWED", "UNKNOWN" ], "description": "证件上注明的婚姻状况。任何其他值均返回 `400`。" }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "证件附加字段的合并视图：经 OCR 提取的值以及应用的所有操作员覆写。通过 `null` 覆写移除的键不会出现在此映射中。" }, "parsed_address": { "type": "object", "nullable": true, "description": "当前结构化地址（已去除内部簿记键），如果不存在则为 `null`。包含重新计算的 `formatted_address` 以及七个可编辑键。", "properties": { "address_type": { "type": "string", "nullable": true, "description": "自由格式地址分类（例如 `home`）。" }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "州 / 省 / 自治区。" }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 国家/地区代码。小写输入将被规范化为大写；alpha-3 代码将被拒绝并返回 `400`。", "example": "ES" }, "formatted_address": { "type": "string", "nullable": true, "description": "结构化地址拼接而成的可读形式。每次编辑 `parsed_address` 后会在服务端重新计算。", "example": "Avda de Madrid 34, Madrid, 28013, ES" } } } } }, "examples": { "Updated KYC": { "summary": "纠正后的完整 KYC 记录", "value": { "document_type": "P", "document_subtype": null, "document_number": "PAB123456", "personal_number": "99999999R", "date_of_birth": "1980-01-01", "date_of_issue": "2021-02-09", "expiration_date": "2031-02-08", "issuing_state": "ESP", "first_name": "Carmen", "last_name": "Espanola Espanola", "gender": "F", "address": "AVDA DE MADRID 34, MADRID, MADRID 28013", "place_of_birth": "MADRID", "nationality": "ESP", "marital_status": "MARRIED", "extra_fields": { "mrz_string": "P\": [\"\"]}` 形式返回；嵌套的 `parsed_address` / `extra_fields` 键上的错误使用对象值：`{\"parsed_address\": {\"\": \"\"}}`。", "content": { "application/json": { "examples": { "Invalid gender": { "summary": "gender 必须为 M、F 或 U", "value": { "gender": [ "\"X\" is not a valid choice." ] } }, "Invalid document type": { "summary": "不是短代码或长格式别名", "value": { "document_type": [ "\"PASSPORT\" is not a valid choice." ] } }, "Invalid issuing state": { "summary": "issuing_state 不是 ISO 3166-1 alpha-3 代码", "value": { "issuing_state": [ "Invalid ISO 3166-1 alpha-3 country code for issuing_state." ] } }, "Invalid marital status": { "summary": "marital_status 不在枚举值中", "value": { "marital_status": [ "\"ENGAGED\" is not a valid choice." ] } }, "Bad date format": { "summary": "日期格式必须为 YYYY-MM-DD", "value": { "date_of_birth": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Unsupported parsed_address key": { "summary": "仅允许文档中记载的七个键", "value": { "parsed_address": { "zipcode": "Unsupported key. Allowed keys: address_type, city, region, street_1, street_2, postal_code, country" } } }, "Invalid parsed_address country": { "summary": "嵌套的 country 必须是 alpha-2 代码，不能是 alpha-3 代码", "value": { "parsed_address": { "country": "Invalid ISO 3166-1 alpha-2 country code." } } }, "extra_fields not an object": { "summary": "extra_fields 必须是 JSON 对象", "value": { "extra_fields": [ "This field must be a JSON object." ] } } } } } }, "403": { "description": "缺少凭据或权限不足。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "凭证缺少 write:sessions 权限", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未知会话、会话处于不可编辑状态，或没有可修补的 KYC 记录。每种情况都有不同的 `detail` 消息（参见示例）。未知会话查找在凭证检查之前运行。", "content": { "application/json": { "examples": { "Unknown session": { "summary": "您的应用中不存在具有此 ID 的会话（或已被删除）", "value": { "detail": "Not found." } }, "Wrong session state": { "summary": "会话存在，但状态不是 Approved / Declined / In Review / Kyc Expired", "value": { "detail": "No Session matches the given query." } }, "No KYC record": { "summary": "工作流从未运行过身份证件验证步骤", "value": { "detail": "The session does not have a KYC." } }, "No KYC for node": { "summary": "提供了 node_id，但不存在对应的 KYC", "value": { "detail": "The session does not have a KYC for node 'feature_missing'." } } } } } }, "429": { "description": "超出专用速率限制 — 每个 API 密钥每分钟允许 10 次 KYC 数据更新（被拒绝的请求也计入配额）。共享的 300 次/分钟写入配额也可能触发并显示其自身的提示消息。重试前请检查 `Retry-After` 和 `X-RateLimit-*` 响应头。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "KYC 更新配额已耗尽", "value": { "detail": "Session KYC data update rate limit exceeded. You can make up to 10 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-data/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"first_name\": \"Carmen\",\n \"last_name\": \"Espanola Espanola\",\n \"date_of_birth\": \"1980-01-01\",\n \"issuing_state\": \"ESP\",\n \"parsed_address\": {\n \"street_1\": \"Avda de Madrid 34\",\n \"city\": \"Madrid\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\"\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_data(\n \"11111111-2222-3333-4444-555555555555\",\n date_of_birth=\"1980-01-01\",\n issuing_state=\"ESP\",\n first_name=\"Carmen\",\n last_name=\"Espanola Espanola\",\n marital_status=\"MARRIED\",\n extra_fields={\"blood_group\": \"O+\"},\n parsed_address={\n \"city\": \"Madrid\",\n \"street_1\": \"Avda de Madrid 34\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateData(\"11111111-2222-3333-4444-555555555555\", {\n date_of_birth: \"1980-01-01\",\n issuing_state: \"ESP\",\n first_name: \"Carmen\",\n last_name: \"Espanola Espanola\",\n marital_status: \"MARRIED\",\n extra_fields: { blood_group: \"O+\" },\n parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateData(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateDataParams{\n\tDateOfBirth: didit.String(\"1980-01-01\"),\n\tIssuingState: didit.String(\"ESP\"),\n\tFirstName: didit.String(\"Carmen\"),\n\tLastName: didit.String(\"Espanola Espanola\"),\n\tMaritalStatus: didit.Some(didit.SessionsUpdateDataParamsMaritalStatus(\"MARRIED\")),\n\tExtraFields: didit.Some(map[string]any{\"blood_group\": \"O+\"}),\n\tParsedAddress: didit.Some(didit.SessionsUpdateDataParamsParsedAddress{\n\t\tCity: didit.String(\"Madrid\"),\n\t\tStreet1: didit.String(\"Avda de Madrid 34\"),\n\t\tPostalCode: didit.String(\"28013\"),\n\t\tCountry: didit.String(\"ES\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdateDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateData(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateDataParams.builder()\n .dateOfBirth(LocalDate.parse(\"1980-01-01\"))\n .issuingState(\"ESP\")\n .firstName(\"Carmen\")\n .lastName(\"Espanola Espanola\")\n .maritalStatus(SessionsUpdateDataParams.MaritalStatus.of(\"MARRIED\"))\n .extraFields(Map.of(\"blood_group\", \"O+\"))\n .parsedAddress(SessionsUpdateDataParams.ParsedAddress.builder()\n .city(\"Madrid\")\n .street1(\"Avda de Madrid 34\")\n .postalCode(\"28013\")\n .country(\"ES\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateData('11111111-2222-3333-4444-555555555555', [\n 'date_of_birth' => '1980-01-01',\n 'issuing_state' => 'ESP',\n 'first_name' => 'Carmen',\n 'last_name' => 'Espanola Espanola',\n 'marital_status' => 'MARRIED',\n 'extra_fields' => ['blood_group' => 'O+'],\n 'parsed_address' => [\n 'city' => 'Madrid',\n 'street_1' => 'Avda de Madrid 34',\n 'postal_code' => '28013',\n 'country' => 'ES',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_data(\n \"11111111-2222-3333-4444-555555555555\",\n date_of_birth: \"1980-01-01\",\n issuing_state: \"ESP\",\n first_name: \"Carmen\",\n last_name: \"Espanola Espanola\",\n marital_status: \"MARRIED\",\n extra_fields: { blood_group: \"O+\" },\n parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateDataAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateDataParams\n{\n DateOfBirth = \"1980-01-01\",\n IssuingState = \"ESP\",\n FirstName = \"Carmen\",\n LastName = \"Espanola Espanola\",\n MaritalStatus = new SessionsUpdateDataParamsMaritalStatus(\"MARRIED\"),\n ExtraFields = new Dictionary { [\"blood_group\"] = \"O+\" },\n ParsedAddress = new SessionsUpdateDataParamsParsedAddress\n {\n City = \"Madrid\",\n Street1 = \"Avda de Madrid 34\",\n PostalCode = \"28013\",\n Country = \"ES\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/features/{nodeId}/update-status/": { "patch": { "summary": "更新单独功能（步骤）状态", "description": "设置会话中单个验证功能（步骤）的状态。通过其工作流图谱的 `nodeId` 指定该功能。在步骤没有节点的非图谱工作流中，请使用 `default` 并同时传递 `feature_type` 以指明您所指的步骤。\n\n适用于用户验证（KYC）和企业验证（KYB）会话以及所有步骤类型：ID/OCR、活体检测、人脸比对、NFC、AML、地址证明、电话、邮箱、数据库核验、问卷，以及 KYB 公司登记/证件/关键人员核查。此 endpoint **不**适用于独立 API 会话（`session_type = API`）。\n\n`new_status` 必须为 `Approved`、`Declined` 或 `In Review` 之一，且必须与该功能的当前状态不同。\n\n**覆盖生效的时间。** 若未设置 `defer_until_flow_finishes`（或设为 `false`），覆盖将立即生效，与以往相同；当用户仍在流程中时，该操作记录为 `forced`。当用户仍在流程中（会话处于 `Not Started`、`In Progress` 或 `Resubmitted` 状态且尚未结束）并设置了 `defer_until_flow_finishes: true` 时，覆盖将存储为 `pending_until_flow_finishes`，并在流程结束且自行得出决策后生效。对于流程已经结束的会话，无论哪种情况都会立即生效。当用户在完成流程前重新执行该步骤、同一核查有了较新的覆盖将其替换、会话未完成流程便退出（已放弃、已过期或在流程中途得出决策），或者您使用 `POST /v3/session/{sessionId}/features/overrides/{overrideId}/cancel/` 取消它时，等待中的覆盖将被取消。使用 `GET /v3/session/{sessionId}/features/overrides/` 列出会话的覆盖记录。\n\n**对会话的影响。** 已经得出决策的会话将保留该决策：仅核查发生变更。当会话尚未得出决策且其工作流正等待此特定步骤时，应用覆盖将完成该步骤：工作流将继续进行，运行后续步骤，并且状态节点可以设置会话决策并触发 `status.updated`。\n\n**Webhook 与活动。** `data.updated` Webhook 会在覆盖生效时（立即生效或流程结束时）触发，在等待期间或被取消时绝不会触发。每次覆盖都会记录在会话的活动中，标记为 `FEATURE_OVERRIDE_PENDING`、`FEATURE_OVERRIDE_APPLIED` 或 `FEATURE_OVERRIDE_CANCELLED`，并附带操作者信息；该请求的记录项会包含您的 `comment`。\n\n使用您的 API 密钥（`x-api-key`）或带有 `write:sessions` 权限的用户授权请求头进行身份验证；限定作用域的 API 密钥需要对决策具有写入权限。", "operationId": "patch_v3_session_update_feature_status", "x-didit-sdk": { "resource": "sessions", "method": "update_feature_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID，服务会跨两种会话类型解析该 ID。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "in": "path", "name": "nodeId", "required": true, "description": "要更新的功能的工作流图谱节点 ID（例如 `feature_ocr_1`）。对于功能没有节点 ID 的非图谱（单步骤）工作流，请使用字面值 `default`。", "schema": { "type": "string", "example": "feature_ocr_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string", "description": "此功能的目标状态。必须与当前值不同。", "enum": [ "Approved", "Declined", "In Review" ], "example": "Approved" }, "comment": { "type": "string", "description": "可选的自由文本备注，记录在此功能变更的会话审核轨迹中。", "example": "Document manually verified by compliance." }, "feature_type": { "type": "string", "enum": [ "ID_VERIFICATION", "OCR", "OCR_BACK", "NFC", "LIVENESS", "FACE", "AGE_ESTIMATION", "AGE_VERIFICATION", "FACE_SEARCH", "FACE_MATCH", "IP_ANALYSIS", "AML", "PHONE", "PHONE_VERIFICATION", "EMAIL", "EMAIL_VERIFICATION", "POA", "PROOF_OF_ADDRESS", "DATABASE_VALIDATION", "DATA_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "BANK_VERIFICATION", "GEOLOCATION" ], "description": "要定位哪种类型的步骤。非图谱工作流中需要提供（`nodeId` = `default`），此时所有步骤不共享节点；其他情况下可选。未知值将返回 `400`。", "example": "LIVENESS" }, "defer_until_flow_finishes": { "type": "boolean", "default": false, "description": "当当事人仍在流程中时，将覆盖项存储为 `pending_until_flow_finishes` 并在流程结束时应用，而不是立即生效。若省略或设为 `false`，覆盖项将立即生效。对于流程已结束的会话，无论哪种情况均会立即生效。", "example": false } } }, "examples": { "Apply Now": { "summary": "立即通过证件验证步骤", "value": { "new_status": "Approved", "comment": "Document manually verified by compliance." } }, "Wait For The Flow": { "summary": "用户完成流程后通过活体检测步骤", "value": { "new_status": "Approved", "comment": "Liveness retried with a reviewer present.", "defer_until_flow_finishes": true } }, "Non-graph Workflow": { "summary": "针对无节点工作流（nodeId = default）的活体检测步骤", "value": { "new_status": "In Review", "feature_type": "LIVENESS" } } } } } }, "responses": { "200": { "description": "覆盖已记录。`new_status` 是已存储的核验状态：覆盖生效后为请求的状态，等待流程完成期间为未更改的状态。`override` 说明了实际发生的情况。", "content": { "application/json": { "schema": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "nullable": true, "description": "已更新步骤的工作流节点；对于没有节点的步骤（非图谱工作流中的 `default` 路径），则为 `null`。", "example": "feature_ocr_1" }, "feature_type": { "type": "string", "description": "已更新功能的模型名称（例如 `KYC`、`Face`、`FaceMatch`、`AML`、`POA`）。", "example": "KYC" }, "new_status": { "type": "string", "description": "该检查的已存储状态：覆盖生效后为所请求的状态，在覆盖等待流程完成期间为未更改的状态。", "example": "Approved" }, "override": { "$ref": "#/components/schemas/FeatureStatusOverride" } }, "required": [ "session_id", "node_id", "feature_type", "new_status", "override" ] }, "examples": { "Applied": { "summary": "覆盖操作已立即应用", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "node_id": "feature_ocr_1", "feature_type": "KYC", "new_status": "Approved", "override": { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "node_id": "feature_ocr_1", "feature_type": "", "feature_model": "KYC", "previous_status": "In Review", "new_status": "Approved", "state": "applied", "forced": false, "reason": "Document manually verified by compliance.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": "2026-10-13T09:15:00Z", "cancelled_at": null, "cancel_reason": null } } }, "Waiting For The Flow": { "summary": "该人员仍在流程中时的 defer_until_flow_finishes", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "node_id": "feature_liveness_1", "feature_type": "Face", "new_status": "Declined", "override": { "id": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3", "node_id": "feature_liveness_1", "feature_type": "", "feature_model": "Face", "previous_status": "Declined", "new_status": "Approved", "state": "pending_until_flow_finishes", "forced": false, "reason": "Liveness retried with a reviewer present.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": null, "cancelled_at": null, "cancel_reason": null } } } } } } }, "400": { "description": "验证错误。当 `new_status` 无效或未发生变化、`feature_type` 未知，或者会话为独立 API 会话时返回。", "content": { "application/json": { "examples": { "Same Status": { "summary": "new_status 与当前状态相同", "value": { "new_status": [ "The new status is the same as the current status." ] } }, "API Session": { "summary": "独立 API 会话上的功能状态无法更改", "value": [ "Cannot change feature status for API sessions." ] }, "Unknown feature_type": { "summary": "feature_type 不是已知的步骤类型", "value": { "feature_type": [ "Unknown feature_type 'SELFIE'." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "已过有效期的作用域 API 密钥", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少凭据或权限不足。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "API 密钥缺少 write:sessions", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "没有决策写入权限的作用域 API 密钥", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "未找到该会话，或者该会话没有具有给定 `nodeId` 的功能。", "content": { "application/json": { "examples": { "Session Not Found": { "summary": "未知的 session_id", "value": { "detail": "Session not found." } }, "Feature Not Found": { "summary": "此 node_id 没有对应功能", "value": { "detail": "No feature found with node_id 'feature_ocr_1' in this session." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/features/feature_ocr_1/update-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"new_status\": \"Approved\",\n \"comment\": \"Document manually verified by compliance.\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_feature_status(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_ocr_1\",\n new_status=\"Approved\",\n comment=\"Document manually verified by compliance.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateFeatureStatus(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_ocr_1\",\n {\n new_status: \"Approved\",\n comment: \"Document manually verified by compliance.\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateFeatureStatus(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_ocr_1\", didit.SessionsUpdateFeatureStatusParams{\n\tNewStatus: \"Approved\",\n\tComment: didit.String(\"Document manually verified by compliance.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateFeatureStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateFeatureStatus(\"11111111-2222-3333-4444-555555555555\", \"feature_ocr_1\", SessionsUpdateFeatureStatusParams.builder()\n .newStatus(SessionsUpdateFeatureStatusParams.NewStatus.of(\"Approved\"))\n .comment(\"Document manually verified by compliance.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateFeatureStatus('11111111-2222-3333-4444-555555555555', 'feature_ocr_1', [\n 'new_status' => 'Approved',\n 'comment' => 'Document manually verified by compliance.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_feature_status(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_ocr_1\",\n new_status: \"Approved\",\n comment: \"Document manually verified by compliance.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateFeatureStatusAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_ocr_1\", new SessionsUpdateFeatureStatusParams\n{\n NewStatus = \"Approved\",\n Comment = \"Document manually verified by compliance.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/update-aml-hit-status/": { "patch": { "summary": "更新 AML 命中审核状态", "description": "设置 AML 筛查返回的**单个 AML 命中项**（潜在的制裁 / PEP / 观察名单 / 负面新闻匹配）的审核状态，且不会更改整个会话决策。通过其 `hit_id`（AML 检查的 `hits` 数组中某个条目的 `id` — 请参阅会话决策）标识该命中项。仍然支持以较早格式返回的命中项 ID；响应始终按其当前 `id` 命名该命中项。\n\n`review_status` 为 `Unreviewed`、`Confirmed Match`、`False Positive` 或 `Inconclusive` 之一。审核员决策会在持续监控更新期间保留，因此当提供商重新筛查时，您标记为 `False Positive` 的命中项将保持该状态。\n\n成功的调用会触发 `data.updated` Webhook，并向会话的审核轨迹附加一条活动条目（包含操作者归因）。对于包含多个 AML 检查的图谱工作流，请传递 `node_id` 以定位特定检查。\n\n使用您的 API 密钥（`x-api-key`）或用户授权请求头进行身份验证 — 两者都必须包含 `write:sessions` 权限。", "operationId": "patch_v3_session_update_aml_hit_status", "x-didit-sdk": { "resource": "sessions", "method": "update_aml_hit_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID，服务会跨两种会话类型解析该 ID。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "in": "query", "name": "node_id", "required": false, "description": "工作流图谱节点 ID。仅在会话包含多个 AML 检查（每个节点一个）时需要；单 AML 会话请省略。", "schema": { "type": "string", "example": "feature_aml_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hit_id", "review_status" ], "properties": { "hit_id": { "type": "string", "description": "AML 检查中 `hits` 数组里的命中项 `id`（`hit_...`）。以旧格式返回的命中项 id 仍被接受。", "example": "hit_7c1e9a40b2d35f86e0a4c912" }, "review_status": { "type": "string", "description": "该命中项的新审核状态。", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ], "example": "False Positive" }, "node_id": { "type": "string", "description": "可选的图谱节点 ID。当会话包含多个 AML 检查时，请使用此项（在此处或作为查询参数）。", "example": "feature_aml_1" } } }, "example": { "hit_id": "hit_7c1e9a40b2d35f86e0a4c912", "review_status": "False Positive" } } } }, "responses": { "200": { "description": "命中项审核状态已更新。", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "hit_id", "review_status" ], "properties": { "message": { "type": "string", "description": "始终为 `Hit status updated successfully`。" }, "hit_id": { "type": "string", "description": "更新后命中项的 `id`，按会话决策返回的形式呈现；即使请求使用的是旧格式的 id 指定该命中项，也会正常返回。" }, "review_status": { "type": "string", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ], "description": "当前存储在命中项上的审核状态。" } } }, "example": { "message": "Hit status updated successfully", "hit_id": "hit_7c1e9a40b2d35f86e0a4c912", "review_status": "False Positive" } } } }, "400": { "description": "验证错误 — `hit_id` 为空，或 `review_status` 不是允许的值之一。", "content": { "application/json": { "example": { "review_status": [ "\"Maybe\" is not a valid choice." ] } } } }, "403": { "description": "缺少凭据或权限不足。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "API 密钥缺少 write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未找到会话、会话没有 AML 检查（可选针对给定的 `node_id`），或没有命中项匹配 `hit_id`。", "content": { "application/json": { "examples": { "No AML Check": { "summary": "会话没有 AML 检查", "value": { "detail": "The session does not have an AML check." } }, "Hit Not Found": { "summary": "未知的 hit_id", "value": { "detail": "Hit with ID 'hit_9d2e7f41c0a8b3e65d1f0c47' not found in the AML check." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-aml-hit-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"hit_id\": \"abc123\",\n \"review_status\": \"False Positive\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_id=\"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status=\"False Positive\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", {\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"False Positive\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateAMLHitStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateAMLHitStatusParams{\n\tHitID: \"hit_7c1e9a40b2d35f86e0a4c912\",\n\tReviewStatus: \"False Positive\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateAmlHitStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateAmlHitStatusParams.builder()\n .hitId(\"hit_7c1e9a40b2d35f86e0a4c912\")\n .reviewStatus(SessionsUpdateAmlHitStatusParams.ReviewStatus.of(\"False Positive\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateAmlHitStatus('11111111-2222-3333-4444-555555555555', [\n 'hit_id' => 'hit_7c1e9a40b2d35f86e0a4c912',\n 'review_status' => 'False Positive',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"False Positive\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateAmlHitStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateAmlHitStatusParams\n{\n HitId = \"hit_7c1e9a40b2d35f86e0a4c912\",\n ReviewStatus = \"False Positive\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/bulk-update-aml-hit-status/": { "patch": { "summary": "批量更新 AML 命中审核状态", "description": "在单次调用中更新**多个 AML 命中项**的审核状态。提供 `hit_updates`，即 `{ hit_id, review_status }` 键值对列表。`review_status` 为 `Unreviewed`、`Confirmed Match`、`False Positive` 或 `Inconclusive` 之一。\n\n更新遵循“要么全部成功，要么全部失败”的模式：如果在 AML 检查中未找到任何 `hit_id`，请求将返回 `404` 且不会更改任何命中项。成功的调用将触发单个 `data.updated` Webhook，并记录一条涵盖所有更改的活动条目。对于包含多个 AML 检查的图谱工作流，请传递 `node_id` 以针对特定的检查。\n\n使用您的 API 密钥（`x-api-key`）或用户授权请求头进行身份验证，两者都必须包含 `write:sessions` 权限。", "operationId": "patch_v3_session_bulk_update_aml_hit_status", "x-didit-sdk": { "resource": "sessions", "method": "bulk_update_aml_hit_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID，服务会跨两种会话类型解析该 ID。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "in": "query", "name": "node_id", "required": false, "description": "工作流图谱节点 ID。仅在会话包含多个 AML 检查（每个节点一个）时需要；单 AML 会话请省略。", "schema": { "type": "string", "example": "feature_aml_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "hit_updates" ], "properties": { "hit_updates": { "type": "array", "description": "命中更新的非空列表。", "items": { "type": "object", "required": [ "hit_id", "review_status" ], "properties": { "hit_id": { "type": "string", "example": "hit_7c1e9a40b2d35f86e0a4c912", "description": "AML 检查中 `hits` 数组里的命中项 `id`（`hit_...`）。以旧格式返回的命中项 id 仍被接受。" }, "review_status": { "type": "string", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ], "example": "Confirmed Match" } } } }, "node_id": { "type": "string", "description": "可选的图谱节点 ID。当会话包含多个 AML 检查时，请使用此项（在此处或作为查询参数）。", "example": "feature_aml_1" } } }, "example": { "hit_updates": [ { "hit_id": "hit_7c1e9a40b2d35f86e0a4c912", "review_status": "Confirmed Match" }, { "hit_id": "hit_3b8f20d6a91c4e75f0b2d6a8", "review_status": "False Positive" } ] } } } }, "responses": { "200": { "description": "所有命中项已更新。", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "updated_hits" ], "properties": { "message": { "type": "string", "description": "`Updated {n} hit(s) successfully`，其中 `n` 是 `hit_updates` 中的条目数。" }, "updated_hits": { "type": "array", "items": { "type": "string" }, "description": "`hit_updates` 中各条目所指定的命中项 `id`，按会话决策返回的格式及请求顺序排列，包括状态未发生变化的命中项。" } } }, "example": { "message": "Updated 2 hit(s) successfully", "updated_hits": [ "hit_7c1e9a40b2d35f86e0a4c912", "hit_3b8f20d6a91c4e75f0b2d6a8" ] } } } }, "400": { "description": "验证错误 — `hit_updates` 为空，或某一条目缺少 `hit_id` / `review_status`，亦或包含无效值。", "content": { "application/json": { "example": { "hit_updates": [ "hit_updates cannot be empty" ] } } } }, "403": { "description": "缺少凭据或权限不足。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "API 密钥缺少 write:sessions", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未找到会话、会话没有 AML 检查，或者一个或多个 `hit_id` 不存在（在此情况下不会更改任何命中项）。", "content": { "application/json": { "example": { "detail": "Hits not found: hit_9d2e7f41c0a8b3e65d1f0c47" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/bulk-update-aml-hit-status/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"hit_updates\": [\n { \"hit_id\": \"abc123\", \"review_status\": \"Confirmed Match\" },\n { \"hit_id\": \"def456\", \"review_status\": \"False Positive\" }\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.bulk_update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_updates=[{\n \"hit_id\": \"hit_7c1e9a40b2d35f86e0a4c912\",\n \"review_status\": \"Confirmed Match\",\n }, {\n \"hit_id\": \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n \"review_status\": \"False Positive\",\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.bulkUpdateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", {\n hit_updates: [{\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"Confirmed Match\",\n }, {\n hit_id: \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n review_status: \"False Positive\",\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.BulkUpdateAMLHitStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsBulkUpdateAMLHitStatusParams{\n\tHitUpdates: []didit.SessionsBulkUpdateAMLHitStatusParamsHitUpdates{{\n\t\tHitID: \"hit_7c1e9a40b2d35f86e0a4c912\",\n\t\tReviewStatus: \"Confirmed Match\",\n\t}, {\n\t\tHitID: \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n\t\tReviewStatus: \"False Positive\",\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsBulkUpdateAmlHitStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().bulkUpdateAmlHitStatus(\"11111111-2222-3333-4444-555555555555\", SessionsBulkUpdateAmlHitStatusParams.builder()\n .hitUpdates(List.of(\n SessionsBulkUpdateAmlHitStatusParams.HitUpdates.builder()\n .hitId(\"hit_7c1e9a40b2d35f86e0a4c912\")\n .reviewStatus(SessionsBulkUpdateAmlHitStatusParams.HitUpdates.ReviewStatus.of(\"Confirmed Match\"))\n .build(),\n SessionsBulkUpdateAmlHitStatusParams.HitUpdates.builder()\n .hitId(\"hit_3b8f20d6a91c4e75f0b2d6a8\")\n .reviewStatus(SessionsBulkUpdateAmlHitStatusParams.HitUpdates.ReviewStatus.of(\"False Positive\"))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->bulkUpdateAmlHitStatus('11111111-2222-3333-4444-555555555555', [\n 'hit_updates' => [[\n 'hit_id' => 'hit_7c1e9a40b2d35f86e0a4c912',\n 'review_status' => 'Confirmed Match',\n ], [\n 'hit_id' => 'hit_3b8f20d6a91c4e75f0b2d6a8',\n 'review_status' => 'False Positive',\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.bulk_update_aml_hit_status(\n \"11111111-2222-3333-4444-555555555555\",\n hit_updates: [{\n hit_id: \"hit_7c1e9a40b2d35f86e0a4c912\",\n review_status: \"Confirmed Match\",\n }, {\n hit_id: \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n review_status: \"False Positive\",\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.BulkUpdateAmlHitStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsBulkUpdateAmlHitStatusParams\n{\n HitUpdates = new SessionsBulkUpdateAmlHitStatusParamsHitUpdates[]\n {\n new()\n {\n HitId = \"hit_7c1e9a40b2d35f86e0a4c912\",\n ReviewStatus = \"Confirmed Match\",\n },\n new()\n {\n HitId = \"hit_3b8f20d6a91c4e75f0b2d6a8\",\n ReviewStatus = \"False Positive\",\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/update-poa-data/": { "patch": { "summary": "更新验证会话中从地址证明文件提取的地址证明数据", "description": "在验证完成后，更正从用户的地址证明文件（水电费账单、银行对账单或其他地址证明材料）中提取的字段：签发方、日期、印制的姓名、地址本身以及银行详细信息。请求体中的每个字段均为可选：仅写入您发送的键，其余内容保持不变（`PATCH` 语义）。\n\n会话必须属于您的应用，并且处于 `Approved`、`Declined`、`In Review` 或 `Kyc Expired` 状态。处于任何其他状态（例如仍处于 `In Progress`）的会话将返回 `404` 及 `\"No Session matches the given query.\"`，这与针对未知或已删除的 `sessionId` 所返回的 `\"Not found.\"` 有所不同。会话还必须包含 POA 记录：工作流从未运行过地址证明步骤的会话将返回 `404`（`\"The session does not have a POA.\"`）。对于包含多个 POA 步骤的图谱工作流，可通过 `node_id`（查询参数或请求体字段）指定特定步骤；若省略，则更新最新的 POA 记录。\n\n`extra_fields` 按键逐项合并：9 个已知键（`bank_iban`、`additional_names`……）将直接写入专用的 POA 列，任何其他键均作为自定义扩展项保留，`null` / `\"\"` 则会删除该键。`poa_parsed_address` 仅接受文档记录的 7 个键，并在每次修改后重新计算 `formatted_address` / `poa_formatted_address`。如果自由文本 `poa_address` 发生变更，服务器还可能对其重新进行地理编码并刷新结构化地址（沙盒会话跳过此操作）。\n\n与此 endpoint 的 KYC 变体不同，`data.updated` [Webhook](/zh/integration/webhooks)（触发器 `manual_review`）仅在至少一个存储的值**实际发生变更**时才会触发：重新发送完全相同的值将被静默视为无操作。当值发生变更时，记录了变更字段及其旧值和新值的 `POA_DATA_UPDATED` 活动条目会附加到会话的 `reviews` 中，在[获取决策](#get-/v3/session/-sessionId-/decision/)和控制台活动时间线中均可见。会话的状态和决策**不会**重新评估，请使用[更新状态](#patch-/v3/session/-sessionId-/update-status/)来修改结果。\n\n接受 API 密钥或控制台用户 token；无论哪种方式，凭证都需要 `write:sessions` 权限。认证和权限失败均返回 `403`，该 API 从不返回 `401`。请注意，会话查找在凭证检查之前执行，因此即使缺少凭证，未知的 `sessionId` 也会返回 `404`。该 endpoint 对每个 API 密钥设置了专用的速率限制，即每分钟 10 次请求（无效请求也计入）；共享的每分钟 300 次写入预算同样适用。\n\n空的 JSON 请求体 `{}` 为无操作：它会返回 `200` 并原样返回当前 POA 记录，而不会触发 Webhook（`has_changes` 保持为 false）。", "operationId": "patch_v3_session_update_poa_data", "x-didit-sdk": { "resource": "sessions", "method": "update_poa_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "您正在更正其附加地址证明记录的用户验证（KYC）会话的 UUID。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "针对包含多个地址证明步骤的图谱工作流，指定要更新其 POA 记录的工作流图谱节点（也可在请求体中通过 `node_id` 字段传入）。省略时，将更新该会话中最新的 POA 记录。如果指定节点不存在 POA，调用将返回 `404`（`\"The session does not have a POA for node ''.\"`）。", "schema": { "type": "string", "example": "feature_poa" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "所有字段均为可选，仅发送您想要更改的内容。", "properties": { "issuing_state": { "type": "string", "nullable": true, "description": "签发地址证明文件的国家/地区，ISO 3166-1 alpha-3。不区分大小写（规范化为大写）；无效代码返回 `400`。", "example": "ESP" }, "document_type": { "type": "string", "enum": [ "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" ], "description": "地址证明证件类别。值为大写，小写变体如 `utility_bill` 将返回 `400`。", "example": "UTILITY_BILL" }, "document_language": { "type": "string", "maxLength": 50, "nullable": true, "description": "证件的语言，通常为 ISO 639-1 代码（例如 `es`）。自定义文本，不作为语言代码进行校验。", "example": "es" }, "issuer": { "type": "string", "maxLength": 255, "nullable": true, "description": "签发该证件的机构/组织（公用事业公司、银行、政府机构）。", "example": "Energy Provider S.A." }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "`YYYY-MM-DD` 格式的地址证明证件签发日期。任何其他格式均返回 `400`。", "example": "2026-04-12" }, "poa_address": { "type": "string", "nullable": true, "description": "印在证件上的自由文本地址。当该值发生变化（仅限非沙盒会话）且结构化地址仍然缺失或不完整时，服务器会在同一请求的后台重新进行地理编码，并可能用地理编码结果覆盖 `poa_parsed_address` / `poa_formatted_address`。重新进行地理编码还要求 POA 记录中存在 `issuing_state`。", "example": "Avda de Madrid 34, 28013 Madrid" }, "name_on_document": { "type": "string", "maxLength": 255, "nullable": true, "description": "证件上打印的收件人姓名。", "example": "Carmen Espanola" }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "证件特定的附加信息，按键逐个合并。9 个键映射到专用的 POA 列：`bank_account_number`、`bank_iban`、`bank_sort_code`、`bank_routing_number`、`bank_swift_bic`、`bank_branch_name`、`bank_branch_address`、`document_phone_number` 以及 `additional_names`（必须是字符串列表或 `null`，否则返回 `400`）。任何其他键均存储为自定义额外字段。按键语义：有值则设置该键；`null` 或 `\"\"` 则将其删除。必须是 JSON 对象，否则返回 `400`。" }, "poa_parsed_address": { "type": "object", "nullable": true, "description": "结构化地址。仅接受以下嵌套键：`address_type`、`city`、`region`、`street_1`、`street_2`、`postal_code`、`country`，任何其他键都会返回 `400`。各键的语义：传入值设置该键，`null` 删除该键。`formatted_address`（以及顶层的 `poa_formatted_address`）在服务端通过拼接 `street_1`、`street_2`、`city`、`region`、`postal_code` 和 `country` 重新计算，您无法直接对其进行设置。", "properties": { "address_type": { "type": "string", "nullable": true, "description": "自由格式地址分类（例如 `home`）。" }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "州 / 省 / 自治区。" }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 国家/地区代码。小写输入将被规范化为大写；alpha-3 代码将被拒绝并返回 `400`。", "example": "ES" } } } } }, "examples": { "Correct issuer and address": { "summary": "修正证件分类、签发方和结构化地址", "value": { "issuing_state": "ESP", "document_type": "BANK_STATEMENT", "issuer": "Banco Example S.A.", "issue_date": "2026-05-02", "name_on_document": "Carmen Espanola", "poa_address": "Avda de Madrid 34, 28013 Madrid", "extra_fields": { "bank_iban": "ES9121000418450200051332", "additional_names": [ "Carmen E. Espanola" ] }, "poa_parsed_address": { "street_1": "Avda de Madrid 34", "city": "Madrid", "postal_code": "28013", "country": "ES" } } }, "Remove a banking detail": { "summary": "删除一个额外字段键，保留其余字段", "value": { "extra_fields": { "bank_iban": null } } } } } } }, "responses": { "200": { "description": "地址证明数据已更新。返回**完整的当前地址证明记录**（每个可更新字段及其存储值，加上完整的 `extra_fields` 映射、`poa_parsed_address` 和 `poa_formatted_address`），而不仅仅是您提交的字段。仅当至少有一个值实际发生更改时，才会触发 `data.updated` Webhook。", "content": { "application/json": { "schema": { "type": "object", "properties": { "issuing_state": { "type": "string", "nullable": true, "description": "签发地址证明文件的国家/地区，ISO 3166-1 alpha-3。不区分大小写（规范化为大写）；无效代码返回 `400`。", "example": "ESP" }, "document_type": { "type": "string", "enum": [ "UTILITY_BILL", "BANK_STATEMENT", "GOVERNMENT_ISSUED_DOCUMENT", "OTHER_POA_DOCUMENT", "UNKNOWN" ], "description": "地址证明证件类别。值为大写，小写变体如 `utility_bill` 将返回 `400`。", "example": "UTILITY_BILL" }, "document_language": { "type": "string", "maxLength": 50, "nullable": true, "description": "证件的语言，通常为 ISO 639-1 代码（例如 `es`）。自定义文本，不作为语言代码进行校验。", "example": "es" }, "issuer": { "type": "string", "maxLength": 255, "nullable": true, "description": "签发该证件的机构/组织（公用事业公司、银行、政府机构）。", "example": "Energy Provider S.A." }, "issue_date": { "type": "string", "format": "date", "nullable": true, "description": "`YYYY-MM-DD` 格式的地址证明证件签发日期。任何其他格式均返回 `400`。", "example": "2026-04-12" }, "poa_address": { "type": "string", "nullable": true, "description": "印在证件上的自由文本地址。当该值发生变化（仅限非沙盒会话）且结构化地址仍然缺失或不完整时，服务器会在同一请求的后台重新进行地理编码，并可能用地理编码结果覆盖 `poa_parsed_address` / `poa_formatted_address`。", "example": "Avda de Madrid 34, 28013 Madrid" }, "name_on_document": { "type": "string", "maxLength": 255, "nullable": true, "description": "证件上打印的收件人姓名。", "example": "Carmen Espanola" }, "extra_fields": { "type": "object", "additionalProperties": true, "nullable": true, "description": "响应中始终存在：九个已知键（未设置的键为 `null`，`additional_names` 默认为 `[]`）以及先前存储的任何自定义键。" }, "poa_parsed_address": { "type": "object", "nullable": true, "description": "当前结构化地址，如果不存在则为 `null`。包含重新计算的 `formatted_address` 以及七个可编辑键。按存储原样返回。在服务端地理编码后，除可编辑键外还可能包含簿记键（例如 `raw_results`）。", "properties": { "address_type": { "type": "string", "nullable": true, "description": "自由格式地址分类（例如 `home`）。" }, "city": { "type": "string", "nullable": true, "example": "Madrid" }, "region": { "type": "string", "nullable": true, "description": "州 / 省 / 自治区。" }, "street_1": { "type": "string", "nullable": true, "example": "Avda de Madrid 34" }, "street_2": { "type": "string", "nullable": true }, "postal_code": { "type": "string", "nullable": true, "example": "28013" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 国家/地区代码。小写输入将被规范化为大写；alpha-3 代码将被拒绝并返回 `400`。", "example": "ES" }, "formatted_address": { "type": "string", "nullable": true, "description": "结构化地址拼接而成的可读形式。每次编辑 `poa_parsed_address` 后会在服务端重新计算。", "example": "Avda de Madrid 34, Madrid, 28013, ES" } } }, "poa_formatted_address": { "type": "string", "nullable": true, "description": "重新计算的 `formatted_address` 的顶层副本，在结构化地址更改时保持同步。", "example": "Avda de Madrid 34, Madrid, 28013, ES" } } }, "examples": { "Updated POA": { "summary": "纠正后的完整 POA 记录", "value": { "issuing_state": "ESP", "document_type": "BANK_STATEMENT", "document_language": "es", "issuer": "Banco Example S.A.", "issue_date": "2026-05-02", "poa_address": "Avda de Madrid 34, 28013 Madrid", "name_on_document": "Carmen Espanola", "extra_fields": { "bank_account_number": null, "bank_iban": "ES9121000418450200051332", "bank_sort_code": null, "bank_routing_number": null, "bank_swift_bic": null, "bank_branch_name": null, "bank_branch_address": null, "document_phone_number": null, "additional_names": [ "Carmen E. Espanola" ] }, "poa_parsed_address": { "city": "Madrid", "street_1": "Avda de Madrid 34", "postal_code": "28013", "country": "ES", "formatted_address": "Avda de Madrid 34, Madrid, 28013, ES" }, "poa_formatted_address": "Avda de Madrid 34, Madrid, 28013, ES" } } } } } }, "400": { "description": "验证错误。字段错误以 `{\"\": [\"\"]}` 形式返回；嵌套的 `poa_parsed_address` / `extra_fields` 键上的错误使用对象值：`{\"extra_fields\": {\"\": \"\"}}`。", "content": { "application/json": { "examples": { "Invalid document type": { "summary": "枚举为大写，小写变体将被拒绝", "value": { "document_type": [ "\"utility_bill\" is not a valid choice." ] } }, "Invalid issuing state": { "summary": "issuing_state 不是 ISO 3166-1 alpha-3 代码", "value": { "issuing_state": [ "Invalid ISO 3166-1 alpha-3 country code for issuing_state." ] } }, "additional_names not a list": { "summary": "additional_names 接受字符串列表或 null", "value": { "extra_fields": { "additional_names": "Must be a list or null." } } }, "Unsupported poa_parsed_address key": { "summary": "仅允许文档中记载的七个键", "value": { "poa_parsed_address": { "zipcode": "Unsupported key. Allowed keys: address_type, city, region, street_1, street_2, postal_code, country" } } }, "Bad date format": { "summary": "日期格式必须为 YYYY-MM-DD", "value": { "issue_date": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } } } } } }, "403": { "description": "缺少凭据或权限不足。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "凭证缺少 write:sessions 权限", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未知会话、会话处于不可编辑状态，或没有可修补的 POA 记录。每种情况都有不同的 `detail` 消息（参见示例）。未知会话查找在凭证检查之前运行。", "content": { "application/json": { "examples": { "Unknown session": { "summary": "您的应用中不存在具有此 ID 的会话（或已被删除）", "value": { "detail": "Not found." } }, "Wrong session state": { "summary": "会话存在，但状态不是 Approved / Declined / In Review / Kyc Expired", "value": { "detail": "No Session matches the given query." } }, "No POA record": { "summary": "工作流从未运行过地址证明步骤", "value": { "detail": "The session does not have a POA." } }, "No POA for node": { "summary": "提供了 node_id，但不存在对应的 POA", "value": { "detail": "The session does not have a POA for node 'feature_missing'." } } } } } }, "429": { "description": "超出专用速率限制 — 每个 API 密钥每分钟允许 10 次 POA 数据更新（被拒绝的请求也计入配额）。共享的 300 次/分钟写入配额也可能触发并显示其自身的提示消息。重试前请检查 `Retry-After` 和 `X-RateLimit-*` 响应头。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "地址证明更新预算已耗尽", "value": { "detail": "Session POA data update rate limit exceeded. You can make up to 10 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-poa-data/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"issuing_state\": \"ESP\",\n \"document_type\": \"BANK_STATEMENT\",\n \"issuer\": \"Banco Example S.A.\",\n \"issue_date\": \"2026-05-02\",\n \"name_on_document\": \"Carmen Espanola\",\n \"poa_address\": \"Avda de Madrid 34, 28013 Madrid\",\n \"extra_fields\": {\n \"bank_iban\": \"ES9121000418450200051332\"\n },\n \"poa_parsed_address\": {\n \"city\": \"Madrid\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\"\n }\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_poa_data(\n \"11111111-2222-3333-4444-555555555555\",\n issuing_state=\"ESP\",\n document_type=\"BANK_STATEMENT\",\n issuer=\"Banco Example S.A.\",\n issue_date=\"2026-05-02\",\n poa_address=\"Avda de Madrid 34, 28013 Madrid\",\n name_on_document=\"Carmen Espanola\",\n extra_fields={\"bank_iban\": \"ES9121000418450200051332\", \"additional_names\": [\"Carmen E. Espanola\"]},\n poa_parsed_address={\n \"city\": \"Madrid\",\n \"street_1\": \"Avda de Madrid 34\",\n \"postal_code\": \"28013\",\n \"country\": \"ES\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updatePoaData(\"11111111-2222-3333-4444-555555555555\", {\n issuing_state: \"ESP\",\n document_type: \"BANK_STATEMENT\",\n issuer: \"Banco Example S.A.\",\n issue_date: \"2026-05-02\",\n poa_address: \"Avda de Madrid 34, 28013 Madrid\",\n name_on_document: \"Carmen Espanola\",\n extra_fields: { bank_iban: \"ES9121000418450200051332\", additional_names: [\"Carmen E. Espanola\"] },\n poa_parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdatePOAData(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdatePOADataParams{\n\tIssuingState: didit.String(\"ESP\"),\n\tDocumentType: didit.Some(didit.SessionsUpdatePOADataParamsDocumentType(\"BANK_STATEMENT\")),\n\tIssuer: didit.String(\"Banco Example S.A.\"),\n\tIssueDate: didit.String(\"2026-05-02\"),\n\tPOAAddress: didit.String(\"Avda de Madrid 34, 28013 Madrid\"),\n\tNameOnDocument: didit.String(\"Carmen Espanola\"),\n\tExtraFields: didit.Some(map[string]any{\"bank_iban\": \"ES9121000418450200051332\", \"additional_names\": []any{\"Carmen E. Espanola\"}}),\n\tPOAParsedAddress: didit.Some(didit.SessionsUpdatePOADataParamsPOAParsedAddress{\n\t\tCity: didit.String(\"Madrid\"),\n\t\tStreet1: didit.String(\"Avda de Madrid 34\"),\n\t\tPostalCode: didit.String(\"28013\"),\n\t\tCountry: didit.String(\"ES\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdatePoaDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updatePoaData(\"11111111-2222-3333-4444-555555555555\", SessionsUpdatePoaDataParams.builder()\n .issuingState(\"ESP\")\n .documentType(SessionsUpdatePoaDataParams.DocumentType.of(\"BANK_STATEMENT\"))\n .issuer(\"Banco Example S.A.\")\n .issueDate(LocalDate.parse(\"2026-05-02\"))\n .poaAddress(\"Avda de Madrid 34, 28013 Madrid\")\n .nameOnDocument(\"Carmen Espanola\")\n .extraFields(Map.of(\"bank_iban\", \"ES9121000418450200051332\", \"additional_names\", List.of(\"Carmen E. Espanola\")))\n .poaParsedAddress(SessionsUpdatePoaDataParams.PoaParsedAddress.builder()\n .city(\"Madrid\")\n .street1(\"Avda de Madrid 34\")\n .postalCode(\"28013\")\n .country(\"ES\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updatePoaData('11111111-2222-3333-4444-555555555555', [\n 'issuing_state' => 'ESP',\n 'document_type' => 'BANK_STATEMENT',\n 'issuer' => 'Banco Example S.A.',\n 'issue_date' => '2026-05-02',\n 'poa_address' => 'Avda de Madrid 34, 28013 Madrid',\n 'name_on_document' => 'Carmen Espanola',\n 'extra_fields' => ['bank_iban' => 'ES9121000418450200051332', 'additional_names' => ['Carmen E. Espanola']],\n 'poa_parsed_address' => [\n 'city' => 'Madrid',\n 'street_1' => 'Avda de Madrid 34',\n 'postal_code' => '28013',\n 'country' => 'ES',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_poa_data(\n \"11111111-2222-3333-4444-555555555555\",\n issuing_state: \"ESP\",\n document_type: \"BANK_STATEMENT\",\n issuer: \"Banco Example S.A.\",\n issue_date: \"2026-05-02\",\n poa_address: \"Avda de Madrid 34, 28013 Madrid\",\n name_on_document: \"Carmen Espanola\",\n extra_fields: { bank_iban: \"ES9121000418450200051332\", additional_names: [\"Carmen E. Espanola\"] },\n poa_parsed_address: {\n city: \"Madrid\",\n street_1: \"Avda de Madrid 34\",\n postal_code: \"28013\",\n country: \"ES\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdatePoaDataAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdatePoaDataParams\n{\n IssuingState = \"ESP\",\n DocumentType = new SessionsUpdatePoaDataParamsDocumentType(\"BANK_STATEMENT\"),\n Issuer = \"Banco Example S.A.\",\n IssueDate = \"2026-05-02\",\n PoaAddress = \"Avda de Madrid 34, 28013 Madrid\",\n NameOnDocument = \"Carmen Espanola\",\n ExtraFields = new Dictionary { [\"bank_iban\"] = \"ES9121000418450200051332\", [\"additional_names\"] = new object[] { \"Carmen E. Espanola\" } },\n PoaParsedAddress = new SessionsUpdatePoaDataParamsPoaParsedAddress\n {\n City = \"Madrid\",\n Street1 = \"Avda de Madrid 34\",\n PostalCode = \"28013\",\n Country = \"ES\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/{companyUuid}/update-data/": { "patch": { "summary": "更新企业验证（KYB）会话中从登记机构提取的公司数据", "description": "更正由 `companyUuid` 标识的企业验证（KYB）会话中从登记机构提取的企业数据（企业名称、注册号、地址、状态、联系方式）。典型的调用方包括修正登记信息读取错误的合规分析师，或同步更正后企业数据的后台系统。请求体中的每个字段均为可选（`PATCH` 语义）；空的 JSON 请求体（`{}`）为无操作，仅返回当前的企业记录。\n\n修改会同时写入两个位置：拥有规范企业列的字段（名称、注册号、国家/地区、成立日期、税号、类型、状态、资本字段（`registered_capital`、`registered_capital_amount`、`registered_capital_currency`）、备用名称、业务性质、网站、邮箱、电话、LEI、位置，以及 `legal_address` → `registered_address`）会更新该列，并且提交的**每个**键也会合并到 `registry_data` 快照中（日期为 ISO 字符串），以便“从登记机构提取”的视图体现此项更正。没有对应列的字段（`region`、`registration_date`、`dissolution_date`、`control_scheme`）仅写入 `registry_data`。`user_provided_data`（终端用户在托管流程中确认的内容）绝不会被修改，且每次非空 PATCH 都会打上 `last_console_edit_at` 时间戳。\n\n与 KYC/POA 更新 endpoint 不同，此处**没有会话状态限制**：在企业会话生命周期的任何阶段都可以编辑企业。企业必须属于路径中的会话（否则返回 `404` 及 `\"KYB company does not belong to the given session.\"`）且属于您的应用。每次非空 PATCH 都会在企业会话上触发 `data.updated` [Webhook](/zh/integration/webhooks)（触发器为 `console_registry_edit`），即使提交的值与已存储的值相同也是如此。会话的状态和决策**不会**被重新评估，也不会记录审核/审计条目。\n\n接受 API 密钥或控制台用户 token；无论哪种方式，凭证都需要具备 `write:businesses` 权限。身份验证和权限失败均返回 `403`，该 API 从不响应 `401`。请注意，会话查找在凭证检查之前执行，因此即使缺少凭证，未知的 `sessionId` 也会返回 `404`。适用每个 API 密钥每分钟 300 次请求的共享写入配额。\n\n对于用户验证会话，对应的 KYC 接口为 `PATCH /v3/session/{sessionId}/update-data/`；若要更改会话决策本身，请使用 `PATCH /v3/session/{sessionId}/update-status/`。", "operationId": "patch_v3_session_kyb_company_update_data", "x-didit-sdk": { "resource": "sessions", "method": "update_kyb_company_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "父企业验证（KYB）会话的 UUID。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "companyUuid", "in": "path", "required": true, "description": "要更新的企业记录的 UUID（企业会话决策上的 `registry_checks[].company.uuid`）。必须属于 `sessionId` 所引用的会话。", "schema": { "type": "string", "format": "uuid", "example": "88888888-9999-aaaa-bbbb-cccccccccccc" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "所有字段均为可选 — 仅发送您希望更改的内容。提供的字段会更新标准公司列（如果存在），并合并到 `registry_data` 快照中。", "properties": { "company_name": { "type": "string", "maxLength": 255, "description": "企业的法定名称。写入规范列及公司登记快照。", "example": "Docs Probe Corp" }, "registration_number": { "type": "string", "maxLength": 100, "description": "在公司登记处的官方注册号。", "example": "DPC-001" }, "country_code": { "type": "string", "maxLength": 2, "description": "注册国家/地区，ISO 3166-1 alpha-2。不区分大小写（`us` 存储为 `US`）。Alpha-3 代码因超过 2 个字符的限制而返回 `400`。", "example": "US" }, "region": { "type": "string", "maxLength": 10, "nullable": true, "description": "公司登记包含的行政区划/地区标签（例如美国各州）。仅存储在登记快照中，没有规范列。" }, "incorporation_date": { "type": "string", "format": "date", "description": "`YYYY-MM-DD` 格式的注册成立日期。与其他字段一样为可选参数 — `PATCH` 是部分更新。任何其他日期格式都会返回 `400`。", "example": "2015-04-12" }, "registration_date": { "type": "string", "format": "date", "nullable": true, "description": "公司登记中独立于成立日期的注册日期。仅存储在公司登记快照中。" }, "dissolution_date": { "type": "string", "format": "date", "nullable": true, "description": "已不再存续企业的注销日期。仅存储在公司登记快照中。" }, "tax_number": { "type": "string", "maxLength": 100, "description": "税号。" }, "legal_address": { "type": "string", "description": "法定/注册地址。在服务端作为规范字段 `registered_address` 的别名：响应将在 `registered_address` 下返回该值，而登记快照将保留您发送的 `legal_address` 键名。", "example": "1 Example Plaza, Wilmington, DE 19801" }, "company_type": { "type": "string", "maxLength": 100, "description": "法律实体类型（例如 `Limited Liability Company`、`PLC`、`GmbH`）。", "example": "Limited Liability Company" }, "registry_status": { "type": "string", "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off" ], "nullable": true, "description": "公司登记所报告的企业状态。小写，某些值包含空格（例如 `struck off`、`no longer authorised`）。任何其他值均返回 `400`。", "example": "active" }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "登记验证的结果。任何其他值均返回 `400`。", "example": "verified" }, "alternative_names": { "type": "string", "description": "商号、曾用法定名称、DBA 名称（自由文本）。" }, "nature_of_business": { "type": "string", "description": "公司业务活动的简短描述。", "example": "Software development" }, "registered_capital": { "type": "string", "maxLength": 100, "description": "易于阅读的注册资本（例如 `USD 50000`）。结构化数值请使用 `registered_capital_amount` + `registered_capital_currency`，自由格式文本请使用此字段。", "example": "USD 50000" }, "registered_capital_amount": { "type": "number", "format": "double", "nullable": true, "description": "注册资本数字金额（最多 20 位数字，2 位小数）。设置 `registered_capital_amount` 列并以小数字符串形式同步镜像到 `registry_data` 中；响应会将其作为小数字符串返回（例如 `\"1500000.50\"`）。" }, "registered_capital_currency": { "type": "string", "maxLength": 3, "nullable": true, "description": "`registered_capital_amount` 的 ISO 4217 货币代码。不区分大小写（`usd` 会存储为 `USD`）；非正好 3 个字母的值将返回 `400` 及 ISO 4217 错误消息。设置规范的 `registered_capital_currency` 列，并同步映射至 `registry_data`。", "example": "USD" }, "website": { "type": "string", "maxLength": 500, "description": "企业网站。接受裸域名并自动规范化添加 `https://` 前缀（`docsprobe.example.com` 存储为 `https://docsprobe.example.com`）；仍然未通过 URL 验证的值返回 `400`。", "example": "https://docsprobe.example.com" }, "email": { "type": "string", "format": "email", "description": "登记机关备案的联系邮箱。", "example": "legal@docsprobe.example.com" }, "phone": { "type": "string", "maxLength": 50, "description": "联系电话。必须匹配 `+`、数字、空格、破折号、点或括号，总共包含 7-15 位数字，否则返回 `400`。", "example": "+1 302 555 0143" }, "legal_entity_identifier": { "type": "string", "maxLength": 50, "description": "LEI（如果公司有 LEI）。" }, "location_of_registration": { "type": "string", "maxLength": 255, "description": "登记记录中的城市/行政区划。" }, "vat_number": { "type": "string", "maxLength": 64, "description": "欧盟增值税号。仅合并至 `registry_data` 快照，在此处编辑不会重新运行增值税号和税号核验，因此 `vat_validation_status` 及其他 `vat_*` 结果字段保持不变。" }, "control_scheme": { "type": "string", "description": "公司登记公开的控制/治理方案（如有）。仅存储在登记快照中。" } } }, "examples": { "Correct registry data": { "summary": "修正从公司登记中提取的字段", "value": { "company_name": "Docs Probe Corp", "registration_number": "DPC-001", "country_code": "US", "incorporation_date": "2015-04-12", "company_type": "Limited Liability Company", "legal_address": "1 Example Plaza, Wilmington, DE 19801", "registry_status": "active", "verification_status": "verified", "website": "docsprobe.example.com", "email": "legal@docsprobe.example.com", "phone": "+1 302 555 0143", "registered_capital": "USD 50000", "nature_of_business": "Software development" } }, "Single field": { "summary": "仅写入您发送的键", "value": { "registry_status": "dissolved" } }, "No-op": { "summary": "空请求体将返回当前记录，而不触发 Webhook", "value": {} } } } } }, "responses": { "200": { "description": "已更新的企业数据（若请求体为空则原样返回）。返回完整的 KYB 企业记录，格式与企业会话决策中的 `registry_checks[].company` 相同。请注意 `legal_address` 会作为 `registered_address` 返回。`registered_capital_amount`/`registered_capital_currency` 会填充到对应的标准字段中并同步映射到 `registry_data`。", "content": { "application/json": { "schema": { "type": "object", "description": "完整 KYB 公司记录，与企业会话决策中 `registry_checks[]` 内的 `company` 对象结构相同。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "企业记录标识符（`companyUuid` 路径参数）。" }, "node_id": { "type": "string", "nullable": true, "description": "当工作流基于图谱时，此公司记录所属的工作流图谱节点。" }, "status": { "type": "string", "description": "登记核验的功能生命周期状态（例如 `Not Finished`、`Approved`、`Declined`、`In Review`）。" }, "registry_status": { "type": "string", "nullable": true, "description": "公司登记所报告的企业状态（例如 `active`、`dissolved`、`struck off`）。" }, "data_resolved": { "type": "boolean", "description": "当企业数据完整时为 `true`：对于手动输入的企业始终为 `true`；对于源自登记的企业，在公司登记获取完成时为 `true`。" }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 注册成立国家/地区。" }, "region": { "type": "string", "nullable": true }, "company_type": { "type": "string", "nullable": true }, "incorporation_date": { "type": "string", "format": "date", "nullable": true }, "registered_address": { "type": "string", "nullable": true, "description": "标准注册地址 — 当您发送 `legal_address` 时更新。" }, "tax_number": { "type": "string", "nullable": true }, "risk_level": { "type": "string", "nullable": true }, "verification_status": { "type": "string", "nullable": true, "description": "`verified`、`failed` 或 `unknown`。" }, "is_from_registry": { "type": "boolean", "description": "当企业信息是通过公司登记搜索预填充而非手动输入时为 `true`。" }, "fetch_status": { "type": "string", "nullable": true, "description": "来源于公司登记的企业的登记信息获取生命周期（`pending` / `resolved`）；手动条目为 `null`。" }, "alternative_names": { "type": "string", "nullable": true, "description": "上报时的替代名称、商业名称、曾用名或原始语言公司名称（文本格式）。" }, "nature_of_business": { "type": "string", "nullable": true }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "规范列。以十进制字符串形式返回（例如 `\"2750000.00\"`）。" }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "规范列。由注册机构流程设置，或通过此 endpoint 进行控制台/API 编辑设置。" }, "website": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "legal_entity_identifier": { "type": "string", "nullable": true }, "location_of_registration": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true, "description": "欧盟增值税号（EU VAT number），在托管登记步骤中收集或随后编辑时提供。" }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "在登记提交时验证增值税号（若无，则为 `tax_number`）的结果。`valid` / `invalid`：由相应国家/地区的官方登记处判定（欧盟 VIES、挪威、瑞士、巴西、哥伦比亚、哥斯达黎加、厄瓜多尔、巴拉圭；波兰还由其国内增值税登记册判定）。`format_valid` / `invalid_format`：在无法查询登记处时，由该国家/地区的格式和校验位规则判定。`could_not_validate`：登记处不可用。`not_applicable`：无号码、无登记处或规则的国家/地区，或者沙盒会话。" }, "vat_validated_number": { "type": "string", "nullable": true, "description": "已核验的号码，格式以数据源所知为准（例如从法国 SIREN 或荷兰 RSIN 派生的增值税号）。若未运行核验，则为 `null`。" }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "判定 `vat_validation_status` 的来源：官方登记，或 `format_rules`。未运行任何检查时为 `null`。" }, "vat_validated_name": { "type": "string", "nullable": true, "description": "向验证该号码的数据源登记的名称（如果该数据源公开名称）。仅当状态为 `valid` 时设置。" }, "vat_validated_address": { "type": "string", "nullable": true, "description": "核验该号码的数据源中登记的地址（若该数据源披露）。仅在状态为 `valid` 时设置。" }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "检查的时间戳。未运行检查时为 `null`。" }, "financial_summary": { "type": "object", "nullable": true, "additionalProperties": true }, "officers": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "隶属于该公司的董事/高管，包括每名人员的 KYC 进度。" }, "beneficial_owners": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "关联至该公司的实际受益人，包括每个人的 KYC 进度。" }, "addresses": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "公司登记地址详情（若公司登记有返回）。" }, "industries": { "type": "array", "nullable": true, "items": { "type": "object", "additionalProperties": true }, "description": "公司登记行业分类（如可用）。" }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "公司登记备案日期（如可用）。年度申报表和大会使用 last_annual_return_date 与 last_agm_date；它们与财务账目不同。" }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "终端用户在托管登记确认步骤中输入的内容。此 endpoint 绝不会修改该内容。" }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "终端用户在托管流程中确认公司数据的时间。" }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在每次成功的非空 PATCH 上加盖时间戳，以便用户界面可以显示“由操作员编辑”的上下文。" }, "is_editable": { "type": "boolean", "description": "当终端用户仍可在托管流程中编辑源自公司登记的数据（源自登记且尚未确认）时为 `true`。" } } }, "examples": { "Updated company": { "summary": "纠正后的完整公司记录", "value": { "uuid": "6b9479f5-6769-46c8-baf1-df63bbbc5f8c", "node_id": null, "status": "Not Finished", "registry_status": "active", "data_resolved": true, "company_name": "Docs Probe Corp", "registration_number": "DPC-001", "country_code": "US", "region": null, "company_type": "Limited Liability Company", "incorporation_date": "2015-04-12", "registered_address": "1 Example Plaza, Wilmington, DE 19801", "tax_number": null, "risk_level": null, "verification_status": "verified", "is_from_registry": false, "fetch_status": null, "alternative_names": null, "nature_of_business": "Software development", "registered_capital": "USD 50000", "registered_capital_amount": null, "registered_capital_currency": "USD", "website": "https://docsprobe.example.com", "email": "legal@docsprobe.example.com", "phone": "+1 302 555 0143", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": null, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": { "company_name": "Docs Probe Corp", "registration_number": "DPC-001", "country_code": "US", "incorporation_date": "2015-04-12", "legal_address": "1 Example Plaza, Wilmington, DE 19801", "company_type": "Limited Liability Company", "registry_status": "active", "verification_status": "verified", "nature_of_business": "Software development", "registered_capital": "USD 50000", "registered_capital_currency": "USD", "website": "https://docsprobe.example.com", "email": "legal@docsprobe.example.com", "phone": "+1 302 555 0143" }, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": "2026-06-12T00:02:34.276061Z", "is_editable": false } } } } } }, "400": { "description": "验证错误。字段错误以 `{\"\": [\"\"]}` 形式返回。最大长度检查先于格式检查运行，因此 `country_code: \"USA\"` 会报告 2 个字符限制，而不是 ISO 消息。", "content": { "application/json": { "examples": { "Alpha-3 country code": { "summary": "country_code 必须是两位字母（alpha-2）代码：长度检查会优先触发", "value": { "country_code": [ "Ensure this field has no more than 2 characters." ] } }, "Non-alphabetic country code": { "summary": "2 个字符但不是字母", "value": { "country_code": [ "country_code must be a 2-letter ISO 3166-1 alpha-2 code." ] } }, "Invalid currency": { "summary": "3 个字符但不是 ISO 4217 代码", "value": { "registered_capital_currency": [ "Currency must be a 3-letter ISO 4217 code (e.g. USD, EUR, GBP)." ] } }, "Invalid phone": { "summary": "电话号码未通过格式/位数检查", "value": { "phone": [ "Invalid phone number format." ] } }, "Invalid registry status": { "summary": "registry_status 不在枚举值中", "value": { "registry_status": [ "\"liquidated\" is not a valid choice." ] } }, "Invalid email": { "summary": "邮箱地址格式错误", "value": { "email": [ "Enter a valid email address." ] } }, "Invalid website": { "summary": "即使在 https:// 规范化后，该值仍未通过 URL 验证", "value": { "website": [ "Enter a valid URL." ] } }, "Bad date format": { "summary": "日期格式必须为 YYYY-MM-DD", "value": { "incorporation_date": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } } } } } }, "403": { "description": "缺少凭据或权限不足。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "凭证缺少 write:businesses 权限", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未知会话、未知公司，或属于不同会话的公司。每种情况都有不同的 `detail` 消息（参见示例）。未知会话查找在凭证检查之前运行。", "content": { "application/json": { "examples": { "Unknown session": { "summary": "您的应用中不存在具有此 ID 的会话（或已被删除）", "value": { "detail": "Not found." } }, "Unknown company": { "summary": "您的应用中没有具有此 UUID 的公司", "value": { "detail": "No KYBCompany matches the given query." } }, "Company / session mismatch": { "summary": "companyUuid 存在但属于另一个会话", "value": { "detail": "KYB company does not belong to the given session." } } } } } }, "429": { "description": "超出共享写入速率限制（每个 API 密钥每分钟 300 次 POST/PATCH/DELETE 请求）。重试前请检查 `Retry-After` 和 `X-RateLimit-*` 响应头。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "写入预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH \\\n https://verification.didit.me/v3/session/33333333-4444-5555-6666-777777777777/kyb/88888888-9999-aaaa-bbbb-cccccccccccc/update-data/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"company_name\": \"Docs Probe Corp\",\n \"registration_number\": \"DPC-001\",\n \"country_code\": \"US\",\n \"incorporation_date\": \"2015-04-12\",\n \"company_type\": \"Limited Liability Company\",\n \"legal_address\": \"1 Example Plaza, Wilmington, DE 19801\",\n \"registry_status\": \"active\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_kyb_company_data(\n \"33333333-4444-5555-6666-777777777777\",\n \"88888888-9999-aaaa-bbbb-cccccccccccc\",\n company_name=\"Docs Probe Corp\",\n registration_number=\"DPC-001\",\n country_code=\"US\",\n incorporation_date=\"2015-04-12\",\n legal_address=\"1 Example Plaza, Wilmington, DE 19801\",\n company_type=\"Limited Liability Company\",\n registry_status=\"active\",\n verification_status=\"verified\",\n nature_of_business=\"Software development\",\n registered_capital=\"USD 50000\",\n website=\"docsprobe.example.com\",\n email=\"legal@docsprobe.example.com\",\n phone=\"+1 302 555 0143\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateKybCompanyData(\n \"33333333-4444-5555-6666-777777777777\",\n \"88888888-9999-aaaa-bbbb-cccccccccccc\",\n {\n company_name: \"Docs Probe Corp\",\n registration_number: \"DPC-001\",\n country_code: \"US\",\n incorporation_date: \"2015-04-12\",\n legal_address: \"1 Example Plaza, Wilmington, DE 19801\",\n company_type: \"Limited Liability Company\",\n registry_status: \"active\",\n verification_status: \"verified\",\n nature_of_business: \"Software development\",\n registered_capital: \"USD 50000\",\n website: \"docsprobe.example.com\",\n email: \"legal@docsprobe.example.com\",\n phone: \"+1 302 555 0143\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateKYBCompanyData(ctx, \"33333333-4444-5555-6666-777777777777\", \"88888888-9999-aaaa-bbbb-cccccccccccc\", didit.SessionsUpdateKYBCompanyDataParams{\n\tCompanyName: didit.String(\"Docs Probe Corp\"),\n\tRegistrationNumber: didit.String(\"DPC-001\"),\n\tCountryCode: didit.String(\"US\"),\n\tIncorporationDate: didit.String(\"2015-04-12\"),\n\tLegalAddress: didit.String(\"1 Example Plaza, Wilmington, DE 19801\"),\n\tCompanyType: didit.String(\"Limited Liability Company\"),\n\tRegistryStatus: didit.Some(didit.SessionsUpdateKYBCompanyDataParamsRegistryStatus(\"active\")),\n\tVerificationStatus: didit.Some(didit.SessionsUpdateKYBCompanyDataParamsVerificationStatus(\"verified\")),\n\tNatureOfBusiness: didit.String(\"Software development\"),\n\tRegisteredCapital: didit.String(\"USD 50000\"),\n\tWebsite: didit.String(\"docsprobe.example.com\"),\n\tEmail: didit.String(\"legal@docsprobe.example.com\"),\n\tPhone: didit.String(\"+1 302 555 0143\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdateKybCompanyDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateKybCompanyData(\"33333333-4444-5555-6666-777777777777\", \"88888888-9999-aaaa-bbbb-cccccccccccc\", SessionsUpdateKybCompanyDataParams.builder()\n .companyName(\"Docs Probe Corp\")\n .registrationNumber(\"DPC-001\")\n .countryCode(\"US\")\n .incorporationDate(LocalDate.parse(\"2015-04-12\"))\n .legalAddress(\"1 Example Plaza, Wilmington, DE 19801\")\n .companyType(\"Limited Liability Company\")\n .registryStatus(SessionsUpdateKybCompanyDataParams.RegistryStatus.of(\"active\"))\n .verificationStatus(SessionsUpdateKybCompanyDataParams.VerificationStatus.of(\"verified\"))\n .natureOfBusiness(\"Software development\")\n .registeredCapital(\"USD 50000\")\n .website(\"docsprobe.example.com\")\n .email(\"legal@docsprobe.example.com\")\n .phone(\"+1 302 555 0143\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateKybCompanyData('33333333-4444-5555-6666-777777777777', '88888888-9999-aaaa-bbbb-cccccccccccc', [\n 'company_name' => 'Docs Probe Corp',\n 'registration_number' => 'DPC-001',\n 'country_code' => 'US',\n 'incorporation_date' => '2015-04-12',\n 'legal_address' => '1 Example Plaza, Wilmington, DE 19801',\n 'company_type' => 'Limited Liability Company',\n 'registry_status' => 'active',\n 'verification_status' => 'verified',\n 'nature_of_business' => 'Software development',\n 'registered_capital' => 'USD 50000',\n 'website' => 'docsprobe.example.com',\n 'email' => 'legal@docsprobe.example.com',\n 'phone' => '+1 302 555 0143',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_kyb_company_data(\n \"33333333-4444-5555-6666-777777777777\",\n \"88888888-9999-aaaa-bbbb-cccccccccccc\",\n company_name: \"Docs Probe Corp\",\n registration_number: \"DPC-001\",\n country_code: \"US\",\n incorporation_date: \"2015-04-12\",\n legal_address: \"1 Example Plaza, Wilmington, DE 19801\",\n company_type: \"Limited Liability Company\",\n registry_status: \"active\",\n verification_status: \"verified\",\n nature_of_business: \"Software development\",\n registered_capital: \"USD 50000\",\n website: \"docsprobe.example.com\",\n email: \"legal@docsprobe.example.com\",\n phone: \"+1 302 555 0143\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateKybCompanyDataAsync(\"33333333-4444-5555-6666-777777777777\", \"88888888-9999-aaaa-bbbb-cccccccccccc\", new SessionsUpdateKybCompanyDataParams\n{\n CompanyName = \"Docs Probe Corp\",\n RegistrationNumber = \"DPC-001\",\n CountryCode = \"US\",\n IncorporationDate = \"2015-04-12\",\n LegalAddress = \"1 Example Plaza, Wilmington, DE 19801\",\n CompanyType = \"Limited Liability Company\",\n RegistryStatus = new SessionsUpdateKybCompanyDataParamsRegistryStatus(\"active\"),\n VerificationStatus = new SessionsUpdateKybCompanyDataParamsVerificationStatus(\"verified\"),\n NatureOfBusiness = \"Software development\",\n RegisteredCapital = \"USD 50000\",\n Website = \"docsprobe.example.com\",\n Email = \"legal@docsprobe.example.com\",\n Phone = \"+1 302 555 0143\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/parties/{partyUuid}/": { "patch": { "summary": "在企业验证（KYB）会话中跳过（或重新要求）关键人员关联方", "description": "豁免关键人员参与方的验证，或将其重新纳入范围。这是操作员针对永远无法完成自身检查的参与方的应急处理手段，最常见的情况是分配给 UBO 或董事的个人 KYC 会话已被删除，这会冻结该子会话的状态，并导致 KYB 停留在 `Awaiting User` 且无法继续推进。\n\n设置 `is_skipped: true` 会将该参与方从关键人员聚合中移除，并立即重新计算 `KYBKeyPeopleCheck` 及父会话状态，从而使企业会话得以结算，随后变为已通过或已拒绝。发送 `is_skipped: false` 会将该参与方重新纳入范围，检查将恢复为等待该参与方的状态。\n\n与托管关键人员页面中面向申请人的跳过不同，此 endpoint **不**受角色的 `allow_skip` 设置限制，该标志限制的是申请人的决定权，而不是分析师的覆盖操作权限。`requires_verification` 会特意保持不变，因此被覆盖的参与方将显示为 `requires_verification: true` **且** `is_skipped: true`，记录仍会保留规则最初的要求。\n\n该参与方必须属于路径中的会话（否则返回 `404` 及 `\"Party does not belong to the given session.\"`）并属于您的应用。实际更改了该标志的 PATCH 会在企业会话上触发 `data.updated` [Webhook](/zh/integration/webhooks)，触发器为 `console_key_people_skip`；将标志设置为其当前值的 PATCH 则为无操作，仅回显该参与方信息。\n\n接受 API 密钥或控制台用户 token；无论哪种方式，凭据都需要具备 `write:businesses` 权限。", "operationId": "patch_v3_session_kyb_party_update", "x-didit-sdk": { "resource": "sessions", "method": "update_kyb_party", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "父企业验证（KYB）会话的 UUID。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "partyUuid", "in": "path", "required": true, "description": "要更新的关键人员主体的 UUID（企业会话决策上的 `key_people_checks[].submitted.parties[].uuid`）。必须属于 `sessionId` 所引用的会话。", "schema": { "type": "string", "format": "uuid", "example": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_skipped" ], "properties": { "is_skipped": { "type": "boolean", "description": "`true` 免除该方的验证，以便关键人员核验可以在缺少该方的情况下完成；`false` 则将其重新纳入范围。", "example": true } } } } } }, "responses": { "200": { "description": "已更新的当事方（若标志已具有此值，则原样返回）。返回该当事方，数据结构与企业会话决策中 `key_people_checks[].submitted.parties[]` 的条目相同。", "content": { "application/json": { "schema": { "type": "object", "description": "关键人员当事方记录：结构与企业会话决策中 `key_people_checks[].submitted.parties[]` 的条目相同。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "当事方标识符。" }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "该主体是个人还是公司。" }, "name": { "type": "string", "description": "参与方的显示名称。" }, "is_skipped": { "type": "boolean", "description": "该主体是否免于验证。" }, "requires_verification": { "type": "boolean", "description": "角色和阈值规则所要求的内容。此 endpoint 不做修改。" }, "kyc_session_status": { "type": "string", "nullable": true, "description": "关联的个人 KYC 会话的状态，若会话已被删除，则冻结在删除时的状态。" }, "kyc_session_url": { "type": "string", "nullable": true, "description": "指向关联个人 KYC 会话的链接。若不存在或已被删除则为 `null`。" }, "kyc_session_deleted": { "type": "boolean", "description": "关联的个人 KYC 会话已被删除，因此永远无法完成结算。" }, "kyb_sub_session_deleted": { "type": "boolean", "description": "与 `kyc_session_deleted` 对应的企业主体事件。" } } } } } }, "400": { "description": "请求体验证错误。`is_skipped` 是此 endpoint 读取的唯一字段，且为必填项。字段错误将以 `{\"\": [\"\"]}` 的形式返回。请求体验证在当事方查找*之后*执行，因此向不存在的当事方发送格式错误的 `is_skipped` 会报告 `404`，而非 `400`。", "content": { "application/json": { "examples": { "Missing is_skipped": { "summary": "空请求体，或省略 `is_skipped` 的请求体", "value": { "is_skipped": [ "This field is required." ] } }, "Non-boolean is_skipped": { "summary": "值不是布尔值 — `\"maybe\"`、`2`、`[]`。布尔值以及 `\"true\"`/`\"false\"`、`1`/`0` 和 `\"yes\"`/`\"no\"` 均可接受", "value": { "is_skipped": [ "Must be a valid boolean." ] } }, "Null is_skipped": { "summary": "`is_skipped` 存在但为 `null`", "value": { "is_skipped": [ "This field may not be null." ] } } } } } }, "403": { "description": "缺少凭据或权限不足。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "凭证缺少 write:businesses 权限", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未知的当事方，或属于不同会话的当事方。每种情况都有不同的 `detail` 消息（参见示例）。凭证和权限检查在当事方查找之前运行，因此未经授权的调用会报告 `403` 而不是 `404`。没有单独的会话查找：未知的 `sessionId` 与您的当事方配对会报告不匹配消息。", "content": { "application/json": { "examples": { "Unknown party": { "summary": "您的应用中没有具有此 UUID 的主体", "value": { "detail": "Not found." } }, "Party / session mismatch": { "summary": "partyUuid 存在，但关联到另一个会话", "value": { "detail": "Party does not belong to the given session." } } } } } }, "429": { "description": "超出共享写入速率限制（每个 API 密钥每分钟 300 次 POST/PATCH/DELETE 请求）。重试前请检查 `Retry-After` 和 `X-RateLimit-*` 响应头。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Rate limited": { "summary": "写入预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n is_skipped=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateKybParty(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n {\n is_skipped: true,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateKYBParty(ctx, \"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\", didit.SessionsUpdateKYBPartyParams{\n\tIsSkipped: true,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateKybPartyParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateKybParty(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\", SessionsUpdateKybPartyParams.builder()\n .isSkipped(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateKybParty('33333333-4444-5555-6666-777777777777', '0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41', [\n 'is_skipped' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n is_skipped: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateKybPartyAsync(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\", new SessionsUpdateKybPartyParams\n{\n IsSkipped = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/travel-rule/settings/": { "get": { "summary": "获取 Travel Rule 设置", "description": "读取应用的 Travel Rule 设置和 VASP 档案。首次读取时会自动创建默认（已禁用）设置行和空白档案。", "operationId": "getTravelRuleSettings", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_settings", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/settings/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_settings()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveSettings();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveSettings(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveSettings();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveSettings();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_settings\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveSettingsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "当前 Travel Rule 设置和 VASP 资料。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleSettingsDetail" }, "examples": { "Disabled (default)": { "value": { "is_enabled": false, "jurisdiction": "EU", "name_matching_strictness": "DEFAULT", "confirmation_timeout_hours": 48, "timeout_outcome": "HOLD", "threshold_amount": "0.00", "inbound_auto_accept": true, "allow_self_declaration": true, "allow_screenshot_proof": true, "auto_wallet_verification": true, "vasp_attribution_enabled": true, "legal_name": "", "lei": "", "compliance_email": "", "is_discoverable": true, "counterparty_screening_enabled": false, "sunrise_policy": "", "sunrise_jurisdictions": [ "CO", "KH", "VN" ], "non_responsive_policy": "", "travel_address": "", "disabled_networks": [], "networks": { "gtr": { "rail": "GTR", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "trust": { "rail": "TRUST", "mode": "unavailable", "state": "unavailable", "reason": "own_membership_only", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "verifyvasp": { "rail": "VERIFYVASP", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "sygna": { "rail": "SYGNA", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 } }, "didit_network": { "listed": false, "missing": [ "travel_rule_off", "legal_name_missing", "compliance_email_missing" ], "compliance_email_confirmed": false } } } } } } } } }, "put": { "summary": "更新 Travel Rule 设置", "description": "更新或插入应用的 Travel Rule 设置和 VASP 资料。部分更新：仅发送您希望更改的字段。设置 `is_enabled: true` 需要非空的 `legal_name`（已存储或包含在同一请求中），否则返回 400。", "operationId": "updateTravelRuleSettings", "x-didit-sdk": { "resource": "travel_rule", "method": "update_settings", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleSettingsUpdate" }, "example": { "is_enabled": true, "legal_name": "Origin CASP SL", "jurisdiction": "EU", "name_matching_strictness": "DEFAULT", "confirmation_timeout_hours": 48, "timeout_outcome": "HOLD", "is_discoverable": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT https://verification.didit.me/v3/travel-rule/settings/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"is_enabled\": true, \"legal_name\": \"Origin CASP SL\", \"jurisdiction\": \"EU\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.update_settings(\n is_enabled=True,\n legal_name=\"Origin CASP SL\",\n jurisdiction=\"EU\",\n name_matching_strictness=\"DEFAULT\",\n confirmation_timeout_hours=48,\n timeout_outcome=\"HOLD\",\n is_discoverable=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.updateSettings({\n is_enabled: true,\n legal_name: \"Origin CASP SL\",\n jurisdiction: \"EU\",\n name_matching_strictness: \"DEFAULT\",\n confirmation_timeout_hours: 48,\n timeout_outcome: \"HOLD\",\n is_discoverable: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.UpdateSettings(ctx, didit.TravelRuleSettingsUpdate{\n\tIsEnabled: didit.Bool(true),\n\tLegalName: didit.String(\"Origin CASP SL\"),\n\tJurisdiction: didit.String(\"EU\"),\n\tNameMatchingStrictness: didit.Some(didit.TravelRuleSettingsUpdateNameMatchingStrictness(\"DEFAULT\")),\n\tConfirmationTimeoutHours: didit.Int(48),\n\tTimeoutOutcome: didit.Some(didit.TravelRuleSettingsUpdateTimeoutOutcome(\"HOLD\")),\n\tIsDiscoverable: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleSettingsUpdate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().updateSettings(TravelRuleSettingsUpdate.builder()\n .isEnabled(true)\n .legalName(\"Origin CASP SL\")\n .jurisdiction(\"EU\")\n .nameMatchingStrictness(TravelRuleSettingsUpdate.NameMatchingStrictness.of(\"DEFAULT\"))\n .confirmationTimeoutHours(48L)\n .timeoutOutcome(TravelRuleSettingsUpdate.TimeoutOutcome.of(\"HOLD\"))\n .isDiscoverable(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->updateSettings([\n 'is_enabled' => true,\n 'legal_name' => 'Origin CASP SL',\n 'jurisdiction' => 'EU',\n 'name_matching_strictness' => 'DEFAULT',\n 'confirmation_timeout_hours' => 48,\n 'timeout_outcome' => 'HOLD',\n 'is_discoverable' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.update_settings(\n is_enabled: true,\n legal_name: \"Origin CASP SL\",\n jurisdiction: \"EU\",\n name_matching_strictness: \"DEFAULT\",\n confirmation_timeout_hours: 48,\n timeout_outcome: \"HOLD\",\n is_discoverable: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.UpdateSettingsAsync(new TravelRuleSettingsUpdate\n{\n IsEnabled = true,\n LegalName = \"Origin CASP SL\",\n Jurisdiction = \"EU\",\n NameMatchingStrictness = new TravelRuleSettingsUpdateNameMatchingStrictness(\"DEFAULT\"),\n ConfirmationTimeoutHours = 48,\n TimeoutOutcome = new TravelRuleSettingsUpdateTimeoutOutcome(\"HOLD\"),\n IsDiscoverable = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新设置和个人资料，结构与 GET 相同。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleSettingsDetail" } } } }, "400": { "description": "验证错误，例如在没有 legal_name 的情况下启用、sunrise_policy 或 non_responsive_policy 不是 HOLD、REJECT、PROCEED 或为空、`matching_rules` 中存在未知字段，或者 `data_sharing_fields` 选择无法满足您所在管辖区制度的汇款人义务（错误以 `data_sharing_fields` 下的实体类型为键）。", "content": { "application/json": { "schema": { "type": "object" }, "example": { "legal_name": [ "legal_name is required to enable travel rule." ] } } } } } } }, "/v3/travel-rule/settings/compliance-email/confirmation/": { "post": { "summary": "发送合规确认邮件", "description": "向您 VASP 资料的 compliance_email 发送一次性确认链接。打开链接并点击确认按钮即可确认该地址，Didit 网络需要完成此步骤才会将您的资料列出。新的请求会替换之前的链接；当合规邮箱更改时，链接将失效。每个地址每分钟仅限一封邮件。", "operationId": "sendTravelRuleComplianceEmailConfirmation", "x-didit-sdk": { "resource": "travel_rule", "method": "send_compliance_email_confirmation", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/settings/compliance-email/confirmation/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.send_compliance_email_confirmation()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.sendComplianceEmailConfirmation();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.SendComplianceEmailConfirmation(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().sendComplianceEmailConfirmation();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->sendComplianceEmailConfirmation();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.send_compliance_email_confirmation\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.SendComplianceEmailConfirmationAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "202": { "description": "确认邮件已发送。", "content": { "application/json": { "schema": { "type": "object", "properties": { "sent_to": { "type": "string", "format": "email" } } }, "example": { "sent_to": "compliance@your-vasp.example" } } } }, "400": { "description": "未设置合规邮箱，或该邮箱已确认。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "No compliance email": { "value": { "compliance_email": [ "Set a compliance email before confirming it." ] } }, "Already confirmed": { "value": { "compliance_email": [ "This compliance email is already confirmed." ] } } } } } }, "429": { "description": "不到一分钟前已向该地址发送了确认信息。" }, "503": { "description": "无法发送电子邮件。未做任何更改；请稍后重试。" } } } }, "/v3/travel-rule/wallet-addresses/": { "get": { "summary": "列出钱包地址簿条目", "description": "您应用的 Travel Rule 钱包地址簿分页列表，最新优先。", "operationId": "listTravelRuleWalletAddresses", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/wallet-addresses/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.wallet_addresses.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.walletAddresses.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.WalletAddresses.ListAutoPaging(ctx, didit.TravelRuleWalletAddressesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().walletAddresses().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.wallet_addresses.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.WalletAddresses.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页钱包地址簿条目。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WalletAddressEntry" } } } } } } } } }, "post": { "summary": "注册地址", "description": "向您的 Travel Rule 钱包地址簿添加条目，以便入站的 INTERNAL 轨道转账可针对其进行解析。", "operationId": "createTravelRuleWalletAddress", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntryCreate" }, "example": { "address": "0xBeneficiaryWallet01", "chain": "ETH", "holder_name": "Ana Diaz", "holder_vendor_data": "user-042", "self_declared": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"address\": \"0xBeneficiaryWallet01\", \"chain\": \"ETH\", \"holder_name\": \"Ana Diaz\", \"self_declared\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_addresses.create(\n address=\"0xBeneficiaryWallet01\",\n chain=\"ETH\",\n holder_vendor_data=\"user-042\",\n holder_name=\"Ana Diaz\",\n self_declared=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletAddresses.create({\n address: \"0xBeneficiaryWallet01\",\n chain: \"ETH\",\n holder_vendor_data: \"user-042\",\n holder_name: \"Ana Diaz\",\n self_declared: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.WalletAddresses.Create(ctx, didit.WalletAddressEntryCreate{\n\tAddress: \"0xBeneficiaryWallet01\",\n\tChain: didit.String(\"ETH\"),\n\tHolderVendorData: didit.String(\"user-042\"),\n\tHolderName: didit.String(\"Ana Diaz\"),\n\tSelfDeclared: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WalletAddressEntryCreate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletAddresses().create(WalletAddressEntryCreate.builder()\n .address(\"0xBeneficiaryWallet01\")\n .chain(\"ETH\")\n .holderVendorData(\"user-042\")\n .holderName(\"Ana Diaz\")\n .selfDeclared(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->create([\n 'address' => '0xBeneficiaryWallet01',\n 'chain' => 'ETH',\n 'holder_vendor_data' => 'user-042',\n 'holder_name' => 'Ana Diaz',\n 'self_declared' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_addresses.create(\n address: \"0xBeneficiaryWallet01\",\n chain: \"ETH\",\n holder_vendor_data: \"user-042\",\n holder_name: \"Ana Diaz\",\n self_declared: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletAddresses.CreateAsync(new WalletAddressEntryCreate\n{\n Address = \"0xBeneficiaryWallet01\",\n Chain = \"ETH\",\n HolderVendorData = \"user-042\",\n HolderName = \"Ana Diaz\",\n SelfDeclared = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "已创建的条目。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntry" } } } }, "400": { "description": "此应用存在重复钱包（地址、链和 memo）、该链无法承载的 memo 或 X-address、缺少 `address`、无效的 `travel_address`、在 `allow_self_declaration` 未开启时设置了 `self_declared: true`，或在 `ownership_validation_mode` 为 `FULL` 时设置了 `self_declared: true`。", "content": { "application/json": { "schema": { "type": "object" }, "examples": { "Duplicate entry": { "value": { "address": [ "A wallet address entry with this address and chain already exists." ] } }, "Invalid travel address": { "value": { "travel_address": [ "Invalid travel address." ] } }, "Self-declaration disabled": { "value": { "self_declared": [ "Self-declared ownership is disabled for this application." ] } } } } } } } } }, "/v3/travel-rule/wallet-addresses/{entry_uuid}/": { "patch": { "summary": "更新地址持有者元数据", "description": "holder_name、holder_vendor_data、entity_type 和 travel_address 的部分更新。设置 travel_address 会将 TRP 路由地址附加到该条目；无效值将被拒绝并返回 400。响应中仅回显这四个字段。", "operationId": "updateTravelRuleWalletAddress", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "entry_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntryUpdate" }, "example": { "holder_name": "Ana Updated", "travel_address": "ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH https://verification.didit.me/v3/travel-rule/wallet-addresses/{entry_uuid}/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"holder_name\": \"Ana Updated\", \"travel_address\": \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_addresses.update(\n \"11111111-2222-3333-4444-555555555555\",\n holder_name=\"Ana Updated\",\n travel_address=\"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletAddresses.update(\"11111111-2222-3333-4444-555555555555\", {\n holder_name: \"Ana Updated\",\n travel_address: \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.WalletAddresses.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WalletAddressEntryUpdateParam{\n\tHolderName: didit.String(\"Ana Updated\"),\n\tTravelAddress: didit.String(\"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WalletAddressEntryUpdate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletAddresses().update(\"11111111-2222-3333-4444-555555555555\", WalletAddressEntryUpdate.builder()\n .holderName(\"Ana Updated\")\n .travelAddress(\"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->update('11111111-2222-3333-4444-555555555555', [\n 'holder_name' => 'Ana Updated',\n 'travel_address' => 'ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_addresses.update(\n \"11111111-2222-3333-4444-555555555555\",\n holder_name: \"Ana Updated\",\n travel_address: \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletAddresses.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new WalletAddressEntryUpdate\n{\n HolderName = \"Ana Updated\",\n TravelAddress = \"ta2ih1MicegQ3JqiKz9xT89KsSuwaDJYw8DgzmeSEp1h9tduJcNDZ5SgKLEHeyGMcS1s2HgbM6undFrMQknhM5aTXw3G9KBzi16hx\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新的字段。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressEntryUpdate" } } } }, "400": { "description": "`travel_address` 不是有效的 Travel Address。", "content": { "application/json": { "examples": { "Invalid travel address": { "value": { "travel_address": [ "Invalid travel address." ] } } } } } }, "404": { "description": "未知或已删除的条目。" } } }, "delete": { "summary": "删除钱包地址", "description": "删除该条目及其所有权证明和存储的截图。该条目将立即停止匹配新转账，且该地址将被释放以供重新注册。已经使用过该钱包的转账将保留其自身的记录，读取结果保持不变。删除操作不可逆。", "operationId": "deleteTravelRuleWalletAddress", "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "entry_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/travel-rule/wallet-addresses/{entry_uuid}/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.travel_rule.wallet_addresses.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.travelRule.walletAddresses.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.TravelRule.WalletAddresses.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.travelRule().walletAddresses().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.wallet_addresses.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.TravelRule.WalletAddresses.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "已删除。" }, "404": { "description": "未知或已删除的条目。" }, "503": { "description": "`wallet_address_deletion_incomplete`：某个存储的文件无法删除，因此删除操作在完成前中止。地址簿条目仍然存在；重试相同的请求以完成删除。", "content": { "application/json": { "example": { "detail": "A stored file could not be deleted, so the deletion stopped before it finished. Try again.", "code": "wallet_address_deletion_incomplete" } } } } } } }, "/v3/travel-rule/vasps/": { "get": { "summary": "搜索 VASP 目录", "description": "按名称排序的分页 VASP 目录搜索：共享目录条目（Didit 基于 ESMA 临时 MiCA 名录、公共 TRISA 目录、全球 LEI 名录及其自身整理构建）加上 Didit 网络成员。每行包含您的应用目前通往该 VASP 的路由。您自己应用的资料绝不会列出。各行还附带共享尽职调查评估以及您应用自身的决策、实体筛查和问卷。", "operationId": "listTravelRuleVasps", "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "名称或别名片段（不区分大小写）、精确的 LEI 或域名（example.com 或其上的 URL）。Didit 网络成员通过其法定名称、LEI 或合规邮箱的域名进行匹配。" }, { "name": "network", "in": "query", "schema": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA", "TRISA" ] }, "description": "仅包含网络成员目录当前列出的目录条目。" }, { "name": "jurisdiction", "in": "query", "schema": { "type": "string" }, "description": "ISO 3166 alpha-2 或 alpha-3 国家/地区代码。任何其他代码均返回 400。" }, { "name": "reachable", "in": "query", "schema": { "type": "boolean" }, "description": "true：仅返回您的应用拥有可用路由的 VASP（包括 Didit 网络成员）。false：仅返回当前无法送达的目录条目。" }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "directory", "didit" ] }, "description": "仅目录条目，或仅 Didit 网络成员。" }, { "name": "risk", "in": "query", "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "description": "仅包含 risk_level 为该区间的目录条目。未进行评分的 Didit 网络成员绝不会匹配。" }, { "name": "responsiveness", "in": "query", "schema": { "type": "string", "enum": [ "RESPONSIVE", "UNRESPONSIVE", "UNKNOWN" ] }, "description": "仅包含 responsiveness.status 为该值的目录条目。Didit 网络成员绝不会匹配。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/travel-rule/vasps/?search=counterparty&reachable=true' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.list_vasps():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.listVasps()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.ListVASPsAutoPaging(ctx, didit.TravelRuleListVASPsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().listVasps()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->listVasps() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.list_vasps.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.ListVaspsAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "按名称排序的分页 VASP 目录结果。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/VaspDirectoryEntry" } } } } } } }, "400": { "description": "过滤器无效：请求体列出了每个字段，例如未知的网络、国家/地区代码、风险区间或响应状态。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "jurisdiction": [ "Use an ISO 3166 alpha-2 or alpha-3 country code." ], "network": [ "\"SWIFT\" is not a valid choice." ] } } } } }, "x-didit-sdk": { "resource": "travel_rule", "method": "list_vasps", "auth": "api_key", "server": true } } }, "/v3/travel-rule/vasps/{vasp_id}/": { "get": { "summary": "获取 VASP 名录条目", "description": "根据搜索返回的 ID 查询到的一个名录条目或 Didit 网络成员，包含相同字段以及您的应用访问该条目的可用路由。", "operationId": "getTravelRuleVasp", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_vasp", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "GET /v3/travel-rule/vasps/ 中某一行记录的 id。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_vasp(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveVasp(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveVASP(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveVasp(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveVasp('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_vasp(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveVaspAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "条目。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VaspDirectoryEntry" } } } }, "404": { "description": "没有具有此 id 的条目或已列出的 Didit 网络成员。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry has this id." } } } } } } }, "/v3/travel-rule/vasps/{vasp_id}/decision/": { "get": { "summary": "获取您对 VASP 的决策", "description": "您的应用针对交易对手（目录条目或 Didit 网络成员）的决策：已通过、受限或已封禁。未单独设置决策的品牌实体将遵循该品牌的决策（在 inherited_from 中注明）。仅对您的应用私有。", "operationId": "getTravelRuleVaspDecision", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_vasp_decision", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "GET /v3/travel-rule/vasps/ 中某一行记录的 id：目录条目或 Didit 网络成员。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveVASPDecision(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveVaspDecision('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_vasp_decision(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveVaspDecisionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "适用的决策，或 null。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionResponse" }, "examples": { "Own decision": { "value": { "decision": { "decision": "APPROVED", "reason": "Licensed in DE, questionnaire reviewed", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": null } } }, "Inherited from the brand": { "value": { "decision": { "decision": "BLOCKED", "reason": "Group refused after review", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": { "id": "5e4d3c2b-1a0f-4e9d-8c7b-6a5f4e3d2c1b", "name": "Example Group" } } } }, "No decision": { "value": { "decision": null } } } } } }, "404": { "description": "目录中没有具有此 id 的条目或已列出的 Didit 网络成员。您自己的 VASP 资料绝不会是您的交易对手。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "put": { "summary": "设置您对 VASP 的决策", "description": "设置或更改您的应用对交易对手的决策：APPROVED、RESTRICTED 或 BLOCKED，并可附带可选原因。此操作绝不会更改共享目录条目，仅通过您的交易规则（counterparty_dd_status）生效。针对某个品牌的决策也会涵盖其名下所有尚未拥有独立决策的实体。", "operationId": "updateTravelRuleVaspDecision", "x-didit-sdk": { "resource": "travel_rule", "method": "update_vasp_decision", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "GET /v3/travel-rule/vasps/ 中某一行记录的 id：目录条目或 Didit 网络成员。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionRequest" }, "example": { "decision": "BLOCKED", "reason": "Unlicensed in its home jurisdiction" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"decision\": \"BLOCKED\", \"reason\": \"Unlicensed in its home jurisdiction\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.update_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n decision=\"BLOCKED\",\n reason=\"Unlicensed in its home jurisdiction\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.updateVaspDecision(\"11111111-2222-3333-4444-555555555555\", {\n decision: \"BLOCKED\",\n reason: \"Unlicensed in its home jurisdiction\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.UpdateVASPDecision(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleCounterpartyDecisionRequest{\n\tDecision: \"BLOCKED\",\n\tReason: didit.String(\"Unlicensed in its home jurisdiction\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyDecisionRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().updateVaspDecision(\"11111111-2222-3333-4444-555555555555\", TravelRuleCounterpartyDecisionRequest.builder()\n .decision(TravelRuleCounterpartyDecisionRequest.Decision.of(\"BLOCKED\"))\n .reason(\"Unlicensed in its home jurisdiction\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->updateVaspDecision('11111111-2222-3333-4444-555555555555', [\n 'decision' => 'BLOCKED',\n 'reason' => 'Unlicensed in its home jurisdiction',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.update_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n decision: \"BLOCKED\",\n reason: \"Unlicensed in its home jurisdiction\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.UpdateVaspDecisionAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleCounterpartyDecisionRequest\n{\n Decision = \"BLOCKED\",\n Reason = \"Unlicensed in its home jurisdiction\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "当前适用的决策。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionResponse" }, "example": { "decision": { "decision": "BLOCKED", "reason": "Unlicensed in its home jurisdiction", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": null } } } } }, "400": { "description": "决策缺失或不是 APPROVED、RESTRICTED 或 BLOCKED 之一，或者原因超过 255 个字符。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "decision": [ "\"MAYBE\" is not a valid choice." ] } } } }, "404": { "description": "目录中没有具有此 id 的条目或已列出的 Didit 网络成员。您自己的 VASP 资料绝不会是您的交易对手。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "delete": { "summary": "清除您对某一 VASP 的决策", "description": "清除您的应用自身对交易对手的决策。响应将显示随后生效的决策：null，或者对于某一品牌的实体，则显示该品牌的决策（该实体将重新沿用该决策）。", "operationId": "clearTravelRuleVaspDecision", "x-didit-sdk": { "resource": "travel_rule", "method": "clear_vasp_decision", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "GET /v3/travel-rule/vasps/ 中某一行记录的 id：目录条目或 Didit 网络成员。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.clear_vasp_decision(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.clearVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.ClearVASPDecision(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().clearVaspDecision(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->clearVaspDecision('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.clear_vasp_decision(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.ClearVaspDecisionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已清除的决策；响应体显示当前适用的决策。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyDecisionResponse" }, "example": { "decision": null } } } }, "404": { "description": "没有具有此 id 的交易对手，或者您的应用对其没有独立的决策（仅继承自其品牌的决策无法在此清除：请清除该品牌的决策）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Unknown id": { "value": { "detail": "No directory entry or Didit network member has this id." } }, "No decision of its own": { "value": { "detail": "This application has no decision of its own on this counterparty." } } } } } } } } }, "/v3/travel-rule/vasps/{vasp_id}/screening/": { "get": { "summary": "获取 VASP 实体筛查结果", "description": "您的应用是否启用了交易对手筛查、单次筛查对您组织的费用、结果的有效保留时长，以及您对该交易对手最近一次的制裁和负面新闻筛查记录。读取此信息免费。", "operationId": "getTravelRuleVaspScreening", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_vasp_screening", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "GET /v3/travel-rule/vasps/ 中某一行记录的 id：目录条目或 Didit 网络成员。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/screening/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.retrieve_vasp_screening(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.retrieveVaspScreening(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RetrieveVASPScreening(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().retrieveVaspScreening(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->retrieveVaspScreening('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.retrieve_vasp_screening(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RetrieveVaspScreeningAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "您的筛查设置、其价格以及您最新的筛查。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningStatus" }, "example": { "enabled": true, "price": "0.20", "fresh_days": 30, "screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "Approved", "total_hits": 0, "score": null, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": false } } } } }, "403": { "description": "您组织的合同未配置交易对手筛查的费率。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No contract rate is configured for this usage type." } } } }, "404": { "description": "目录中没有具有此 id 的条目或已列出的 Didit 网络成员。您自己的 VASP 资料绝不会是您的交易对手。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "post": { "summary": "筛查 VASP", "description": "针对制裁和负面新闻为您的应用筛查交易对手实体。选择启用：您的 Travel Rule 设置中必须开启 counterparty_screening_enabled。每次新的筛查按您组织的企业 AML 筛查价格计费；除非发送 refresh: true，否则将返回 30 天内的筛查结果（200，不计费）。每个应用同时只能运行一个交易对手筛查。结果对您的应用保密。沙盒应用从不进行筛查。", "operationId": "screenTravelRuleVasp", "x-didit-sdk": { "resource": "travel_rule", "method": "screen_vasp", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "GET /v3/travel-rule/vasps/ 中某一行记录的 id：目录条目或 Didit 网络成员。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningRequest" }, "example": { "refresh": false } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/screening/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"refresh\": false}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.screen_vasp(\n \"11111111-2222-3333-4444-555555555555\",\n refresh=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.screenVasp(\"11111111-2222-3333-4444-555555555555\", {\n refresh: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.ScreenVASP(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleCounterpartyScreeningRequest{\n\tRefresh: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyScreeningRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().screenVasp(\"11111111-2222-3333-4444-555555555555\", TravelRuleCounterpartyScreeningRequest.builder()\n .refresh(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->screenVasp('11111111-2222-3333-4444-555555555555', [\n 'refresh' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.screen_vasp(\n \"11111111-2222-3333-4444-555555555555\",\n refresh: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.ScreenVaspAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleCounterpartyScreeningRequest\n{\n Refresh = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已存在新的筛查并已返回。未产生费用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningResult" }, "example": { "outcome": "reused", "screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "Approved", "total_hits": 0, "score": null, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": false } } } } }, "201": { "description": "已运行新的筛查并已计费。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreeningResult" }, "example": { "outcome": "screened", "screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "In Review", "total_hits": 2, "score": 85.0, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": true } } } } }, "400": { "description": "请求体无效，或者交易对手没有可供筛查的名称。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "detail": [ "This counterparty has no name to screen." ] } } } }, "403": { "description": "您组织的余额无法支付筛查费用（代码 insufficient_credits；未运行任何模块且未计费），或者您的合同中未配置相应费率。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } }, "example": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me", "code": "insufficient_credits" } } } }, "404": { "description": "目录中没有具有此 id 的条目或已列出的 Didit 网络成员。您自己的 VASP 资料绝不会是您的交易对手。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } }, "409": { "description": "未运行任何操作且未产生计费：您的应用已关闭交易对手筛查、该应用为沙盒应用，或该交易对手的筛查已在运行中。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Screening off": { "value": { "detail": "Counterparty screening is turned off. Enable it in the Travel Rule settings first." } }, "Sandbox application": { "value": { "detail": "Counterparty screening does not run for sandbox applications." } }, "Already running": { "value": { "detail": "A screening of this counterparty is already running. Try again in a moment." } } } } } }, "502": { "description": "无法完成筛查。未收取费用；请稍后重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "The screening provider did not answer. Try again in a moment." } } } } } } }, "/v3/travel-rule/vasps/{vasp_id}/questionnaires/": { "get": { "summary": "列出与 VASP 之间的尽职调查问卷", "description": "您的应用发送给交易对手的每份尽职调查问卷，最新的排在最前，包含其状态以及填写后的答案。对您的应用私有。", "operationId": "listTravelRuleVaspQuestionnaires", "x-didit-sdk": { "resource": "travel_rule", "method": "list_vasp_questionnaires", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "GET /v3/travel-rule/vasps/ 中某一行记录的 id：目录条目或 Didit 网络成员。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/questionnaires/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.list_vasp_questionnaires(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.listVaspQuestionnaires(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.ListVASPQuestionnaires(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().listVaspQuestionnaires(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->listVaspQuestionnaires('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.list_vasp_questionnaires(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.ListVaspQuestionnairesAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "您与该交易对手的问卷。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaireList" }, "example": { "questionnaires": [ { "id": "3f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f", "status": "SENT", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-10-14T10:00:00Z", "expires_at": "2026-11-13T10:00:00Z", "answered_at": null, "valid_until": null, "current": false, "answers": {} }, { "id": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "status": "ANSWERED", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-09-02T08:00:00Z", "expires_at": "2026-10-02T08:00:00Z", "answered_at": "2026-09-04T15:20:00Z", "valid_until": "2027-09-04T15:20:00Z", "current": true, "answers": { "legal_name": "Example Counterparty VASP, incorporated in the example jurisdiction.", "licensing": "Crypto-asset service provider authorised under MiCA by its national regulator, licence active.", "jurisdictions": "EU and EEA. We do not serve the United States.", "aml_program": "Written AML/CFT policy, annual independent review, last completed in March 2026.", "compliance_officer": "Head of Compliance, reachable at compliance@counterparty.example.", "sanctions_screening": "Customers at onboarding and daily; counterparties on every transfer.", "transaction_monitoring": "Rule-based monitoring with analyst review; suspicious activity reports filed with the FIU.", "travel_rule": "TRP and email; we answer requests within one business day.", "custody": "Segregated customer wallets held with a qualified custodian, insured.", "ownership": "No shareholder holds 25 percent or more; parent company Example Holding Group.", "record_keeping": "Five-year record-keeping for Travel Rule and transaction data, as our regulator requires.", "data_protection": "Encrypted at rest and in transit, stored in the EU." } } ] } } } }, "404": { "description": "目录中没有具有此 id 的条目或已列出的 Didit 网络成员。您自己的 VASP 资料绝不会是您的交易对手。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } } } }, "post": { "summary": "向 VASP 发送尽职调查问卷", "description": "向交易对手备案的合规邮箱发送 Didit 的标准尽职调查问卷，并附带一次性作答链接。交易对手有 30 天时间回答所有问题；回答的有效期保持 365 天。重新发送将替换您此前发送给同一交易对手且尚未作答的问卷，先前的链接将失效。每个地址每分钟限发一封邮件。", "operationId": "sendTravelRuleVaspQuestionnaire", "x-didit-sdk": { "resource": "travel_rule", "method": "send_vasp_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "vasp_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "GET /v3/travel-rule/vasps/ 中某一行记录的 id：目录条目或 Didit 网络成员。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaireRequest" }, "example": { "sent_to": "travelrule@counterparty.example" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/vasps/{vasp_id}/questionnaires/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"sent_to\": \"travelrule@counterparty.example\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.send_vasp_questionnaire(\n \"11111111-2222-3333-4444-555555555555\",\n sent_to=\"travelrule@counterparty.example\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.sendVaspQuestionnaire(\"11111111-2222-3333-4444-555555555555\", {\n sent_to: \"travelrule@counterparty.example\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.SendVASPQuestionnaire(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleCounterpartyQuestionnaireRequest{\n\tSentTo: didit.String(\"travelrule@counterparty.example\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyQuestionnaireRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().sendVaspQuestionnaire(\"11111111-2222-3333-4444-555555555555\", TravelRuleCounterpartyQuestionnaireRequest.builder()\n .sentTo(\"travelrule@counterparty.example\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->sendVaspQuestionnaire('11111111-2222-3333-4444-555555555555', [\n 'sent_to' => 'travelrule@counterparty.example',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.send_vasp_questionnaire(\n \"11111111-2222-3333-4444-555555555555\",\n sent_to: \"travelrule@counterparty.example\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.SendVaspQuestionnaireAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleCounterpartyQuestionnaireRequest\n{\n SentTo = \"travelrule@counterparty.example\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "202": { "description": "问卷已通过电子邮件发送。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaire" }, "example": { "id": "3f9e8d7c-6b5a-4c3d-9e2f-1a0b9c8d7e6f", "status": "SENT", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-10-14T10:00:00Z", "expires_at": "2026-11-13T10:00:00Z", "answered_at": null, "valid_until": null, "current": false, "answers": {} } } } }, "400": { "description": "sent_to 不是有效的邮箱地址，或者不是该交易对手备案的合规地址，或者该交易对手没有备案的合规地址。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Not on record": { "value": { "sent_to": [ "Send the questionnaire to a compliance address on record for this counterparty." ] } }, "No address": { "value": { "sent_to": [ "No compliance address is on record for this counterparty. Add a contact for it first." ] } } } } } }, "404": { "description": "目录中没有具有此 id 的条目或已列出的 Didit 网络成员。您自己的 VASP 资料绝不会是您的交易对手。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No directory entry or Didit network member has this id." } } } }, "429": { "description": "问卷在不到一分钟前已发送至该地址。" }, "503": { "description": "无法发送电子邮件且未创建问卷。请稍后重试。" } } } }, "/v3/transactions/{transaction_id}/travel-rule/": { "patch": { "summary": "完成、取消、重新发送或更新 Travel Rule 转账的汇款人钱包", "description": "提供 `payment_txn_id` 以报告链上哈希并将出站 COMPLETED 转账变为 FINISHED（其 INTERNAL 轨道的对应转账也会变为 FINISHED）；提供 `{\"action\": \"cancel\"}` 以取消非终态转账；或提供 `{\"action\": \"resend\"}` 以对卡在 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 或 NOT_ENOUGH_COUNTERPARTY_DATA 的出站转账重新路由（请先完善交易对手数据，例如向目标钱包条目添加 travel_address）。resend 仅适用于出站转账。`{\"action\": \"update_compliance_email\", \"compliance_email\": \"desk@example.com\"}` 用于替换处于这三种状态之一的出站转账的合规邮箱，这是针对 `reason: email_undeliverable` 的修复方案：状态不会改变，下一次 `resend` 会向该地址发送请求。重新发送会进入队列，而不是在请求内同步执行：响应显示转账恢复为 AWAITING_COUNTERPARTY 状态，并带有 `resend queued` 时间线记录以及处于排队状态的 `delivery`，其投递去向会通过 `travel_rule.status.updated` Webhook 送达。当转账通过 GTR、VerifyVASP 或 Sygna Bridge 进行时，网络会在响应之后获悉链上哈希或取消操作，并支持重试；`delivery` 显示该消息的当前状态。`{\"action\": \"update_originator_wallet\", \"wallet_address\": \"...\"}` 记录出站转账中资金实际流出的钱包，例如 UTXO 提现广播时使用的地址，而非您声明的主钱包。此操作仅修改记录：不会向交易对手再次发送任何内容，状态保持不变。汇款人变更为 `chain_details.originator` 且 `source: updated`，该变更会连同先前与新的钱包一起添加到 `timeline` 中，且转账的 INTERNAL 轨道对应记录也会以相同方式更新。`{\"action\": \"beneficiary_vasp\", \"beneficiary_vasp\": \"\"}` 用于在自动发现失败时，针对处于 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 或 NOT_ENOUGH_COUNTERPARTY_DATA 状态的出站转账自行指定交易对手：转账将路由至该 VASP 并重新发送。", "operationId": "patchTravelRuleTransfer", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "update_transfer", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "拥有该转账的 Didit 稳定交易 UUID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTransferPatchRequest" }, "examples": { "Finish": { "value": { "payment_txn_id": "0xchainhash" } }, "Cancel": { "value": { "action": "cancel" } }, "Resend": { "value": { "action": "resend" } }, "Update compliance email": { "value": { "action": "update_compliance_email", "compliance_email": "desk@example.com" } }, "Update originator wallet": { "value": { "action": "update_originator_wallet", "wallet_address": "bc1qOriginatorInputAddress01" } }, "Name the counterparty": { "value": { "action": "beneficiary_vasp", "beneficiary_vasp": "9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"payment_txn_id\": \"0xchainhash\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.update_transfer(\n \"11111111-2222-3333-4444-555555555555\",\n payment_txn_id=\"0xchainhash\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.updateTransfer(\"11111111-2222-3333-4444-555555555555\", {\n payment_txn_id: \"0xchainhash\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.UpdateTransfer(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleTransferPatchRequest{\n\tPaymentTxnID: didit.String(\"0xchainhash\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleTransferPatchRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().updateTransfer(\"11111111-2222-3333-4444-555555555555\", TravelRuleTransferPatchRequest.builder()\n .paymentTxnId(\"0xchainhash\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->updateTransfer('11111111-2222-3333-4444-555555555555', [\n 'payment_txn_id' => '0xchainhash',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.update_transfer(\n \"11111111-2222-3333-4444-555555555555\",\n payment_txn_id: \"0xchainhash\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.UpdateTransferAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleTransferPatchRequest\n{\n PaymentTxnId = \"0xchainhash\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新的转账。在执行 `update_compliance_email` 后，其状态保持不变，并保留 `reason: email_undeliverable`，直到下一次 `resend`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } } }, "400": { "description": "既未提供 payment_txn_id 也未提供支持的操作，在 `update_compliance_email` 时缺少 `compliance_email` 或其不是有效的邮箱地址，或者对于 `update_originator_wallet`，未提供 wallet_address、钱包或 memo 无法由该转账所在链承载、钱包不是该转账的 UTXO 输入之一，或 `beneficiary_vasp` 缺失或不是有效的名录 VASP id。", "content": { "application/json": { "examples": { "No action": { "value": { "detail": [ "Provide payment_txn_id, action=cancel, action=resend, action=beneficiary_vasp, action=update_originator_wallet or action=update_compliance_email." ] } }, "Invalid compliance email": { "value": { "compliance_email": [ "Enter a valid email address." ] } } } } } }, "404": { "description": "未知的交易、该交易没有 Travel Rule 转账，或者（操作 `beneficiary_vasp`）名录条目中不存在该 ID。" }, "409": { "description": "转账未处于允许此操作的状态（例如完成操作未处于 COMPLETED/出账状态，取消操作已处于终态，或重新发送操作未处于可重新发送状态的出账转账）。对于入账转账以及处于 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 和 NOT_ENOUGH_COUNTERPARTY_DATA 之外的出账转账，`update_compliance_email` 响应 `409`。对于入账、已取消或已过期的转账，`update_originator_wallet` 响应 `409`。除非转账为出账且处于 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 或 NOT_ENOUGH_COUNTERPARTY_DATA 状态，否则 `beneficiary_vasp` 响应 `409`。", "content": { "application/json": { "examples": { "Cancel from a terminal status": { "value": { "detail": "Transfer is already in a terminal state." } }, "Resend not allowed": { "value": { "detail": "Transfer cannot be resent from its current state." } }, "Finish not allowed": { "value": { "detail": "Transfer must be an outbound transfer in COMPLETED status to finish." } }, "Compliance email cannot change": { "value": { "detail": "The compliance email of this transfer cannot change from its current state." } } } } } } } } }, "/v3/transactions/{transaction_id}/travel-rule/ownership/": { "post": { "summary": "确认或拒绝钱包所有权", "description": "解决处于等待钱包所有权状态的转账：当转账处于 UNCONFIRMED_OWNERSHIP，或入站转账处于 ON_HOLD 时，在您自己一侧的转账中调用此接口。确认会将匹配的钱包地址簿条目标记为所有权已核验（对于没有条目的入站 ON_HOLD 转账，Didit 会从 beneficiary_data.wallet_address 创建一个条目），并在转账双方执行收款人姓名匹配；拒绝则会拒绝双方。充值已结算的入站转账在匹配成功后将变更为 FINISHED。当交易对手钱包被声明为自托管（counterparty.payment_method.method_type: unhosted_wallet）时，确认操作会记录客户已核验谁控制该钱包，并将双向转账完成（COMPLETED），或者对于链上哈希已知的入站充值变更为 FINISHED。核验的钱包为交易对手的钱包：出站提币的目的地，或入站充值的来源（汇款人钱包）。如果它尚未在您的钱包地址簿中，Didit 会在交易对手姓名下将其添加为所有权已核验；如果地址簿已将其记录在其他持有人姓名下，转账将变更为 COUNTERPARTY_MISMATCHED_DATA。对于处于 UNCONFIRMED_OWNERSHIP、ON_HOLD 或 COUNTERPARTY_MISMATCHED_DATA 的入站 TRP 转账，Didit 会将您的决策发送给发起方 VASP：批准将返回支付地址（wallet_address，或匹配条目的地址）并将转账变更为 COMPLETED，而拒绝则会拒绝该转账。同一调用还可对 GTR 或 Sygna Bridge 交易对手发送且等待您审核的入站转账作出决策（`UNCONFIRMED_OWNERSHIP`、`ON_HOLD` 或 `COUNTERPARTY_MISMATCHED_DATA`）：`confirmed: true` 表示批准（如果转账未指明地址，请传入 `wallet_address`），`confirmed: false` 表示拒绝，且系统在响应后回复网络并进行重试。VerifyVASP 在请求时即获取答案，因此需要您审核的 VerifyVASP 转账会立即被拒绝，无法稍后进行决策。", "operationId": "confirmTravelRuleOwnership", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "confirm_ownership", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "您的应用针对此转账所持有的 Didit 稳定交易 UUID：在 INTERNAL 通道转账中为收款人侧交易，或在交易对手钱包被声明为自托管钱包时您创建的交易（出账或入账）。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleOwnershipConfirmRequest" }, "example": { "confirmed": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/ownership/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"confirmed\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.confirm_ownership(\n \"11111111-2222-3333-4444-555555555555\",\n confirmed=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.confirmOwnership(\"11111111-2222-3333-4444-555555555555\", {\n confirmed: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.ConfirmOwnership(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleOwnershipConfirmRequest{\n\tConfirmed: true,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleOwnershipConfirmRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().confirmOwnership(\"11111111-2222-3333-4444-555555555555\", TravelRuleOwnershipConfirmRequest.builder()\n .confirmed(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->confirmOwnership('11111111-2222-3333-4444-555555555555', [\n 'confirmed' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.confirm_ownership(\n \"11111111-2222-3333-4444-555555555555\",\n confirmed: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.ConfirmOwnershipAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleOwnershipConfirmRequest\n{\n Confirmed = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新的转账。对于入向转账，交易对手的 originator_data/beneficiary_data 会保持脱敏状态（`data_masked: true`），直到所有权得到确认，然后由 `data_unmasked` 记录数据解除屏蔽的时间、原因和操作人员。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } } }, "409": { "description": "转账未在等待所有权确认、钱包地址簿中没有与其交易对手钱包匹配的条目、来自另一 Didit 客户的 INTERNAL 转账在确认前需要控制权证明（签名消息或测试存款），或者网络转账已在其网络上得到应答（VerifyVASP 转账，或者您或 Didit 已作出决策的 GTR 或 Sygna Bridge 转账）。", "content": { "application/json": { "examples": { "Not awaiting confirmation": { "value": { "detail": "Transfer is not awaiting ownership confirmation." } }, "No matching address book entry": { "value": { "detail": "wallet address entry no longer available" } } } } } }, "400": { "description": "验证错误：缺少 confirmed、入站 TRP 批准缺少 wallet_address 且无备用地址，或者在已声明的自托管钱包转账中设置了 `confirmed: true` 但未指明交易对手钱包且未发送 `wallet_address`。", "content": { "application/json": { "examples": { "No payment address": { "value": { "wallet_address": [ "wallet_address is required to approve." ] } } } } } }, "404": { "description": "未知的交易，或者该交易没有 Travel Rule 转账。" }, "502": { "description": "仅限入站 TRP 转账：Didit 无法将您的决策投递给汇款方 VASP，因此转账状态不会改变。", "content": { "application/json": { "examples": { "Callback not delivered": { "value": { "detail": "Counterparty inquiry-resolution callback could not be delivered." } } } } } } } } }, "/v3/transactions/{transaction_id}/travel-rule/messages/": { "get": { "summary": "列出 Travel Rule 消息", "description": "与交易对手 VASP 就此笔转账交换的消息和证件请求。", "operationId": "listTravelRuleMessages", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "list_messages", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "拥有该转账的 Didit 稳定交易 UUID。", "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/messages/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.list_messages(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.listMessages(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.ListMessages(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().listMessages(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->listMessages('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.travel_rule.list_messages(\"11111111-2222-3333-4444-555555555555\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.ListMessagesAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "消息列表，按时间从旧到新排序。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleMessage" } } } } }, "404": { "description": "未知的交易或 token，或者该交易没有 Travel Rule 转账。" } } }, "post": { "summary": "发送 Travel Rule 消息或证件请求", "description": "向交易对手 VASP 发送消息或证件请求。适用于 INTERNAL 转账（另一位 Didit 客户会在其配对端看到）和 EMAIL 转账（通过电子邮件通知交易对手，交易对手在提取门户中回复）。通过 TRP、GTR、TRUST、VerifyVASP 或 Sygna 进行的转账不携带任何消息，因为这些协议不支持消息。限制：每次转账最多 100 条消息，正文最多 5000 个字符，最多 10 份请求的证件，最多 5 个文件（每个 10 MB）。", "operationId": "createTravelRuleMessage", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "create_message", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "拥有该转账的 Didit 稳定交易 UUID。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" }, "example": { "kind": "DOCUMENT_REQUEST", "body": "Please confirm the date of birth of the beneficiary.", "requested_documents": [ "Proof of address" ] } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/transactions/{transaction_id}/travel-rule/messages/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"kind\": \"DOCUMENT_REQUEST\", \"body\": \"Please confirm the date of birth of the beneficiary.\", \"requested_documents\": [\"Proof of address\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.create_message(\n \"11111111-2222-3333-4444-555555555555\",\n kind=\"DOCUMENT_REQUEST\",\n body=\"Please confirm the date of birth of the beneficiary.\",\n requested_documents=[\"Proof of address\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.createMessage(\"11111111-2222-3333-4444-555555555555\", {\n kind: \"DOCUMENT_REQUEST\",\n body: \"Please confirm the date of birth of the beneficiary.\",\n requested_documents: [\"Proof of address\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.CreateMessage(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleMessageCreateRequest{\n\tKind: didit.Some(didit.TravelRuleMessageCreateRequestKind(\"DOCUMENT_REQUEST\")),\n\tBody: didit.String(\"Please confirm the date of birth of the beneficiary.\"),\n\tRequestedDocuments: didit.Some([]string{\"Proof of address\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TravelRuleMessageCreateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().createMessage(\"11111111-2222-3333-4444-555555555555\", TravelRuleMessageCreateRequest.builder()\n .kind(TravelRuleMessageCreateRequest.Kind.of(\"DOCUMENT_REQUEST\"))\n .body(\"Please confirm the date of birth of the beneficiary.\")\n .requestedDocuments(List.of(\"Proof of address\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->createMessage('11111111-2222-3333-4444-555555555555', [\n 'kind' => 'DOCUMENT_REQUEST',\n 'body' => 'Please confirm the date of birth of the beneficiary.',\n 'requested_documents' => ['Proof of address'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.create_message(\n \"11111111-2222-3333-4444-555555555555\",\n kind: \"DOCUMENT_REQUEST\",\n body: \"Please confirm the date of birth of the beneficiary.\",\n requested_documents: [\"Proof of address\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.CreateMessageAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleMessageCreateRequest\n{\n Kind = new TravelRuleMessageCreateRequestKind(\"DOCUMENT_REQUEST\"),\n Body = \"Please confirm the date of birth of the beneficiary.\",\n RequestedDocuments = new string[] { \"Proof of address\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "存储的消息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessage" } } } }, "400": { "description": "无效的请求体、不被接受的文件类型或大小、该笔转账上的消息已超过 100 条，或者 `reply_to` 不是该笔转账的消息。", "content": { "application/json": { "schema": { "type": "object" }, "example": { "requested_documents": [ "Name at least one document the counterparty should send." ] } } } }, "404": { "description": "未知的交易或 token，或者该交易没有 Travel Rule 转账。" }, "409": { "description": "没有任何消息可以送达交易对手。`detail` 说明了原因：转账通过网络通道（TRP、GTR、TRUST、VerifyVASP 或 Sygna）进行；尚无交易对手；INTERNAL 转账的数据与钱包持有人不匹配导致未向接收方发送任何内容；或者 EMAIL 转账的提取链接已过期或转账已关闭。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/travel-rule/pickup/{token}/": { "get": { "summary": "获取邮件通道提取信息", "description": "公开，无需身份验证。允许非 Didit 交易对手 VASP 通过邮件收到的提取链接预览待处理的交换。token 本身即作为身份验证。", "operationId": "getTravelRulePickup", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_pickup", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact", "in": "query", "required": false, "schema": { "type": "string" }, "description": "链接的 `?contact=` 值，即链接发送到的联系人。原样回显为 `contact`；未经核验。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/pickup/{token}/" } ], "responses": { "200": { "description": "自提预览。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRulePickupInfo" }, "example": { "reference": "33333333-4444-5555-6666-777777777777", "requested_at": "2026-07-05T10:00:00Z", "originator_vasp_name": "Origin CASP SL", "originator_vasp_lei": "529900EXAMPLEORIG001", "recipient_vasp_name": "Example Counterparty VASP", "language": "es", "amount": "0.250000000000000000", "currency": "ETH", "fiat_amount": "", "fiat_currency": "", "chain": "ETH", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "status": "AWAITING_COUNTERPARTY", "ivms_version": "ivms101.2023", "deadline_at": "2026-07-07T10:00:00Z", "reminders_sent": 0, "contact": "", "decline_reasons": [ "data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other" ], "join_invitation": { "eligible": false, "url": "" }, "originator_data": { "name": "Jane Doe", "wallet_address": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" }, "beneficiary_data": { "name": "Ana Diaz", "wallet_address": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb" }, "ivms_request": { "originator": { "originatorPersons": [ { "naturalPerson": { "name": { "nameIdentifier": [ { "primaryIdentifier": "Doe", "secondaryIdentifier": "Jane", "nameIdentifierType": "LEGL" } ] } } } ], "accountNumber": [ "0x77ccff0cc624a53cd8b8d8703ced826710211ec7" ] }, "beneficiary": { "beneficiaryPersons": [ { "naturalPerson": { "name": { "nameIdentifier": [ { "primaryIdentifier": "Diaz", "secondaryIdentifier": "Ana", "nameIdentifierType": "LEGL" } ] } } } ], "accountNumber": [ "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb" ] } }, "data_masked": false } } } }, "404": { "description": "未知的 token。" }, "410": { "description": "窗口已关闭：交易对手已回复、转账已脱离 AWAITING_COUNTERPARTY 状态，或已超过截止时间。" } } } }, "/v3/travel-rule/pickup/{token}/respond/": { "post": { "summary": "响应邮件通道的提取请求", "description": "公开且无需认证。通过邮件发送的提取链接接受或拒绝此次信息交换。接受时，将根据汇款人的 name_matching_strictness 策略对 beneficiary_name 进行比对核验。", "operationId": "respondTravelRulePickup", "x-didit-sdk": { "resource": "travel_rule", "method": "respond_pickup", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "contact", "in": "query", "required": false, "schema": { "type": "string" }, "description": "链接的 `?contact=` 值。在请求体未发送 `contact` 时使用。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRulePickupRespondRequest" }, "example": { "decision": "accept", "beneficiary_name": "Carlos Ruiz" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/respond/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"decision\": \"accept\", \"beneficiary_name\": \"Carlos Ruiz\"}'" } ], "responses": { "200": { "description": "最终的数据交换状态：接受后为 COMPLETED 或 COUNTERPARTY_MISMATCHED_DATA；拒绝后为 COUNTERPARTY_VASP_GENERAL_DECLINE，同时会原样返回 `decline_reason`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "decline_reason": { "type": "string", "description": "在拒绝后提供。" } } }, "examples": { "accepted": { "value": { "status": "COMPLETED" } }, "declined": { "value": { "status": "COUNTERPARTY_VASP_GENERAL_DECLINE", "decline_reason": "not_our_customer" } } } } } }, "400": { "description": "字段无效：例如缺少 `decision` 或其值不是 `accept` 或 `decline`、在 `decline_reason: other` 的拒绝操作中缺少 `decline_detail`、`ivms_response` 不是 IVMS 101 对象或长度超过 16384 个字符，或者请求体中的 `contact` 不是 UUID（`{\"contact\": [\"Must be a valid UUID.\"]}`）。", "content": { "application/json": { "example": { "decline_detail": [ "Say what the reason is when you choose another reason." ] } } } }, "404": { "description": "未知的 token。" }, "410": { "description": "窗口已关闭：交易对手已回复、转账已脱离 AWAITING_COUNTERPARTY 状态，或已超过截止时间。" } } } }, "/v3/travel-rule/pickup/{token}/messages/": { "get": { "summary": "列出自提消息", "description": "公开，无需身份验证。交易对手 VASP 读取的 EMAIL-rail 传输消息：客户发送的内容为 `INBOUND`，并带有客户 VASP 名称的签名。token 即作为身份验证。", "operationId": "listTravelRulePickupMessages", "x-didit-sdk": { "resource": "travel_rule", "method": "list_pickup_messages", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/pickup/{token}/messages/" } ], "responses": { "200": { "description": "来自交易对手方的消息，按时间从旧到新排序。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleMessage" } } } } }, "404": { "description": "未知的 token。" }, "410": { "description": "提取链接已过期或转账已关闭。" } } }, "post": { "summary": "在提取门户中回复", "description": "公开，无需身份验证。交易对手 VASP 通过 EMAIL-rail 传输进行回写。body 与交易的消息相同；附件必须为 PDF、PNG、JPEG 或 WebP 格式。token 即作为身份验证。", "operationId": "createTravelRulePickupMessage", "x-didit-sdk": { "resource": "travel_rule", "method": "create_pickup_message", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" }, "example": { "kind": "MESSAGE", "body": "Attached is the proof of address of the wallet holder." } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/TravelRuleMessageCreateRequest" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/messages/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"kind\": \"MESSAGE\", \"body\": \"Attached is the proof of address of the wallet holder.\"}'" } ], "responses": { "201": { "description": "存储的消息。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleMessage" } } } }, "400": { "description": "无效的请求体、不被接受的文件类型或大小、该笔转账上的消息已超过 100 条，或者 `reply_to` 不是该笔转账的消息。", "content": { "application/json": { "schema": { "type": "object" }, "example": { "requested_documents": [ "Name at least one document the counterparty should send." ] } } } }, "404": { "description": "未知的 token。" }, "410": { "description": "提取链接已过期或转账已关闭。" } } } }, "/v3/travel-rule/inbound/": { "post": { "summary": "登记充值后（sunrise）入站转账", "description": "为在任何交易发生前已在链上结算的加密货币充值登记 Travel Rule 数据。创建入站 travelRule 交易（或复用未认领的充值），并根据您的钱包地址簿解析该笔转账。对于新创建的交易，Didit 会先发送 transaction.created Webhook，随后发送 travel_rule.status.updated Webhook。", "operationId": "registerTravelRuleInbound", "x-didit-sdk": { "resource": "travel_rule", "method": "register_inbound", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleInboundRequest" }, "example": { "chain": "ETH", "txid": "0xdeposit-hash", "wallet_address": "0xYourDepositWallet", "amount": "500.00", "currency": "USDC", "originator_data": { "name": "Origin CASP SL" }, "beneficiary_data": { "name": "Ana Diaz" }, "originating_vasp": { "name": "Origin CASP SL", "lei": "", "travel_address": "ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/inbound/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"chain\":\"ETH\",\"txid\":\"0xdeposit-hash\",\"wallet_address\":\"0xYourDepositWallet\",\"amount\":\"500.00\",\"currency\":\"USDC\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.register_inbound(\n chain=\"ETH\",\n txid=\"0xdeposit-hash\",\n wallet_address=\"0xYourDepositWallet\",\n amount=\"500.00\",\n currency=\"USDC\",\n originator_data={\"name\": \"Origin CASP SL\"},\n beneficiary_data={\"name\": \"Ana Diaz\"},\n originating_vasp={\n \"name\": \"Origin CASP SL\",\n \"lei\": \"\",\n \"travel_address\": \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.registerInbound({\n chain: \"ETH\",\n txid: \"0xdeposit-hash\",\n wallet_address: \"0xYourDepositWallet\",\n amount: \"500.00\",\n currency: \"USDC\",\n originator_data: { name: \"Origin CASP SL\" },\n beneficiary_data: { name: \"Ana Diaz\" },\n originating_vasp: {\n name: \"Origin CASP SL\",\n lei: \"\",\n travel_address: \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.RegisterInbound(ctx, didit.TravelRuleInboundRequest{\n\tChain: \"ETH\",\n\tTxid: \"0xdeposit-hash\",\n\tWalletAddress: \"0xYourDepositWallet\",\n\tAmount: \"500.00\",\n\tCurrency: \"USDC\",\n\tOriginatorData: didit.Some(map[string]any{\"name\": \"Origin CASP SL\"}),\n\tBeneficiaryData: didit.Some(map[string]any{\"name\": \"Ana Diaz\"}),\n\tOriginatingVASP: didit.Some(didit.TravelRuleInboundRequestOriginatingVASP{\n\t\tName: didit.String(\"Origin CASP SL\"),\n\t\tLei: didit.String(\"\"),\n\t\tTravelAddress: didit.String(\"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.TravelRuleInboundRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().registerInbound(TravelRuleInboundRequest.builder()\n .chain(\"ETH\")\n .txid(\"0xdeposit-hash\")\n .walletAddress(\"0xYourDepositWallet\")\n .amount(\"500.00\")\n .currency(\"USDC\")\n .originatorData(Map.of(\"name\", \"Origin CASP SL\"))\n .beneficiaryData(Map.of(\"name\", \"Ana Diaz\"))\n .originatingVasp(TravelRuleInboundRequest.OriginatingVasp.builder()\n .name(\"Origin CASP SL\")\n .lei(\"\")\n .travelAddress(\"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->registerInbound([\n 'chain' => 'ETH',\n 'txid' => '0xdeposit-hash',\n 'wallet_address' => '0xYourDepositWallet',\n 'amount' => '500.00',\n 'currency' => 'USDC',\n 'originator_data' => ['name' => 'Origin CASP SL'],\n 'beneficiary_data' => ['name' => 'Ana Diaz'],\n 'originating_vasp' => [\n 'name' => 'Origin CASP SL',\n 'lei' => '',\n 'travel_address' => 'ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.register_inbound(\n chain: \"ETH\",\n txid: \"0xdeposit-hash\",\n wallet_address: \"0xYourDepositWallet\",\n amount: \"500.00\",\n currency: \"USDC\",\n originator_data: { name: \"Origin CASP SL\" },\n beneficiary_data: { name: \"Ana Diaz\" },\n originating_vasp: {\n name: \"Origin CASP SL\",\n lei: \"\",\n travel_address: \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.RegisterInboundAsync(new TravelRuleInboundRequest\n{\n Chain = \"ETH\",\n Txid = \"0xdeposit-hash\",\n WalletAddress = \"0xYourDepositWallet\",\n Amount = \"500.00\",\n Currency = \"USDC\",\n OriginatorData = new Dictionary { [\"name\"] = \"Origin CASP SL\" },\n BeneficiaryData = new Dictionary { [\"name\"] = \"Ana Diaz\" },\n OriginatingVasp = new TravelRuleInboundRequestOriginatingVasp\n {\n Name = \"Origin CASP SL\",\n Lei = \"\",\n TravelAddress = \"ta9JbXbsBSuS5ozArJRFVgvBHMVnDGUnrPPChSZYQsuZTn3kPrJXUQ7RSLUEJ5KjyPvr8C9sAxmPtZfGsQVKCi4n8ShxP9BkbDdbtjtA9aumNybAZ1BxC\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "针对该 txid 和 wallet_address 的转账已注册；原样返回现有记录（created 为 false）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleInboundResponse" } } } }, "201": { "description": "已登记新的 Travel Rule 转账，基于新的入向交易或现有的未认领充值（created 为 true）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleInboundResponse" } } } }, "400": { "description": "缺少必填字段（`chain`、`txid`、`wallet_address`、`amount`、`currency`），`originating_vasp.lei` 不是有效的 LEI，`originating_vasp.travel_address` 不是有效的 Travel Address，包含该链无法承载的 memo、X-address 或 `utxo`，或者 `originator_data` / `beneficiary_data` 不是对象。", "content": { "application/json": { "examples": { "Missing field": { "value": { "txid": [ "This field is required." ] } }, "Invalid LEI": { "value": { "originating_vasp": { "lei": [ "Invalid LEI: expected 20 alphanumeric characters (ISO 17442)." ] } } } } } } } } } }, "/v3/travel-rule/test-vasp/inbound/": { "post": { "summary": "从 Didit 测试 VASP 触发入账转账（沙盒）", "description": "仅限沙盒应用。Didit Test VASP 会向您的应用发送一笔入站 Travel Rule 转账，以便您在上线生产环境之前端到端演练交易所的接收端。该转账由网络实际入站转账针对您的钱包地址簿运行的相同逻辑进行入账和决策，因此收件箱、决策和钱包所有权流程的表现与生产环境中一致。任何数据都不会离开 Didit。生产环境应用将收到 400。再次发送相同的 `reference` 可获取首次调用入账的转账，而不是创建第二笔转账。", "operationId": "triggerTravelRuleTestVaspInbound", "x-didit-sdk": { "resource": "transactions.travel_rule", "method": "trigger_test_vasp_inbound", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTestVaspInboundRequest" }, "example": { "beneficiary_wallet_address": "0xYourSandboxWallet", "scenario": "accept", "amount": "1", "reference": "demo-001" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/test-vasp/inbound/ \\\n -H 'x-api-key: YOUR_SANDBOX_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"beneficiary_wallet_address\":\"0xYourSandboxWallet\",\"scenario\":\"accept\",\"reference\":\"demo-001\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.travel_rule.trigger_test_vasp_inbound(\n beneficiary_wallet_address=\"0xYourSandboxWallet\",\n scenario=\"accept\",\n amount=\"1\",\n reference=\"demo-001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.travelRule.triggerTestVaspInbound({\n beneficiary_wallet_address: \"0xYourSandboxWallet\",\n scenario: \"accept\",\n amount: \"1\",\n reference: \"demo-001\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.TravelRule.TriggerTestVASPInbound(ctx, didit.TravelRuleTestVASPInboundRequest{\n\tBeneficiaryWalletAddress: \"0xYourSandboxWallet\",\n\tScenario: didit.Some(didit.TravelRuleTestVASPInboundRequestScenario(\"accept\")),\n\tAmount: didit.String(\"1\"),\n\tReference: didit.String(\"demo-001\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleTestVaspInboundRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().travelRule().triggerTestVaspInbound(TravelRuleTestVaspInboundRequest.builder()\n .beneficiaryWalletAddress(\"0xYourSandboxWallet\")\n .scenario(TravelRuleTestVaspInboundRequest.Scenario.of(\"accept\"))\n .amount(\"1\")\n .reference(\"demo-001\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->travelRule->triggerTestVaspInbound([\n 'beneficiary_wallet_address' => '0xYourSandboxWallet',\n 'scenario' => 'accept',\n 'amount' => '1',\n 'reference' => 'demo-001',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.travel_rule.trigger_test_vasp_inbound(\n beneficiary_wallet_address: \"0xYourSandboxWallet\",\n scenario: \"accept\",\n amount: \"1\",\n reference: \"demo-001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.TravelRule.TriggerTestVaspInboundAsync(new TravelRuleTestVaspInboundRequest\n{\n BeneficiaryWalletAddress = \"0xYourSandboxWallet\",\n Scenario = new TravelRuleTestVaspInboundRequestScenario(\"accept\"),\n Amount = \"1\",\n Reference = \"demo-001\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "入账转账已记录并作出决策。使用相同的 `reference` 重复请求将返回相同的响应体。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleTestVaspInboundResponse" } } } }, "400": { "description": "无效的请求体、未知或不受支持的 `scenario`，或者该应用为生产环境应用。", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "无法登记该转账，例如因为该应用未启用 Travel Rule。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } } } }, "/v3/travel-rule/widget-session/": { "post": { "summary": "生成钱包所有权小部件会话", "description": "生成托管的钱包所有权小组件 URL/token。引导客户访问返回的 URL 以证明其对钱包的控制权（消息签名、中本聪测试、屏幕截图或自主声明）。此版本中的小组件仅限网页端：请在系统浏览器或自定义标签页中打开该 URL，切勿在移动 SDK 的 webview 内打开。", "operationId": "createTravelRuleWidgetSession", "x-didit-sdk": { "resource": "travel_rule", "method": "create_widget_session", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetSessionCreate" }, "example": { "wallet_address": "0xd3b62acb76fb27a7f8961ec40fa11746b113aca9", "chain": "ETH", "holder_name": "Jane Doe", "vendor_data": "user-042", "transaction_id": "99999999-aaaa-bbbb-cccc-dddddddddddd", "expires_in_minutes": 60 } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget-session/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"wallet_address\":\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\"chain\":\"ETH\",\"holder_name\":\"Jane Doe\",\"transaction_id\":\"99999999-aaaa-bbbb-cccc-dddddddddddd\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.create_widget_session(\n wallet_address=\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n chain=\"ETH\",\n holder_name=\"Jane Doe\",\n vendor_data=\"user-042\",\n transaction_id=\"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n expires_in_minutes=60,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.createWidgetSession({\n wallet_address: \"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n chain: \"ETH\",\n holder_name: \"Jane Doe\",\n vendor_data: \"user-042\",\n transaction_id: \"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n expires_in_minutes: 60,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.CreateWidgetSession(ctx, didit.TravelRuleWidgetSessionCreate{\n\tWalletAddress: didit.String(\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\"),\n\tChain: didit.String(\"ETH\"),\n\tHolderName: didit.String(\"Jane Doe\"),\n\tVendorData: didit.String(\"user-042\"),\n\tTransactionID: didit.String(\"99999999-aaaa-bbbb-cccc-dddddddddddd\"),\n\tExpiresInMinutes: didit.Int(60),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWidgetSessionCreate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().createWidgetSession(TravelRuleWidgetSessionCreate.builder()\n .walletAddress(\"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\")\n .chain(\"ETH\")\n .holderName(\"Jane Doe\")\n .vendorData(\"user-042\")\n .transactionId(\"99999999-aaaa-bbbb-cccc-dddddddddddd\")\n .expiresInMinutes(60L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->createWidgetSession([\n 'wallet_address' => '0xd3b62acb76fb27a7f8961ec40fa11746b113aca9',\n 'chain' => 'ETH',\n 'holder_name' => 'Jane Doe',\n 'vendor_data' => 'user-042',\n 'transaction_id' => '99999999-aaaa-bbbb-cccc-dddddddddddd',\n 'expires_in_minutes' => 60,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.create_widget_session(\n wallet_address: \"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n chain: \"ETH\",\n holder_name: \"Jane Doe\",\n vendor_data: \"user-042\",\n transaction_id: \"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n expires_in_minutes: 60\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.CreateWidgetSessionAsync(new TravelRuleWidgetSessionCreate\n{\n WalletAddress = \"0xd3b62acb76fb27a7f8961ec40fa11746b113aca9\",\n Chain = \"ETH\",\n HolderName = \"Jane Doe\",\n VendorData = \"user-042\",\n TransactionId = \"99999999-aaaa-bbbb-cccc-dddddddddddd\",\n ExpiresInMinutes = 60,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "已签发的小部件会话。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetSessionResponse" } } } }, "400": { "description": "无效的请求体：`callback_url` 不是绝对 http(s) URL、`expires_in_minutes` 不在 5 到 10080 之间、`transaction_id` 不是 UUID，或某个字段超出了限制长度。", "content": { "application/json": { "examples": { "Invalid callback_url": { "value": { "callback_url": [ "callback_url must be an absolute http(s) URL." ] } } } } } }, "404": { "description": "`transaction_id` 未在此应用中指定 Travel Rule 转账。" } } } }, "/v3/travel-rule/widget/{token}/": { "get": { "summary": "获取钱包所有权小组件上下文", "description": "基于小部件会话 token 的公开读取 endpoint，无需 API 密钥。返回小部件上下文以及每项证明的状态，以便您通过轮询来检测完成情况；证明通过验证后，completed_at 将变为非空值。当在链上检测到充值但尚未确认时，SATOSHI_TEST 证明可能处于 PENDING 状态：后台任务会自动重新检查，并在充值确认后将其完成，因此在等待期间无需客户端执行任何操作。每项证明都包含其方法所需的字段：SATOSHI_TEST 包含 deposit_address、expected_amount 及其自身的 expires_at；MESSAGE_SIGNING 包含 challenge。当会话关联至转账时，建议优先使用 travel_rule.status.updated Webhook 而非轮询。", "operationId": "getTravelRuleWidgetContext", "x-didit-sdk": { "resource": "travel_rule", "method": "retrieve_widget_context", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "生成 widget 会话时返回的不透明会话 token。", "schema": { "type": "string" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/widget/{token}/" } ], "responses": { "200": { "description": "小组件上下文和证明状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetContext" } } } }, "404": { "description": "未知的 token。" }, "410": { "description": "会话已过期且未完成。" } } } }, "/v3/travel-rule/widget/{token}/vasps/": { "get": { "summary": "从钱包组件搜索 VASP", "description": "基于小部件会话 token 的公开读取 endpoint，无需 API 密钥：终端用户小部件的 VASP 选择器。提供与小部件所属应用的 GET /v3/travel-rule/vasps/ 相同的搜索和过滤器，仅返回各 VASP 的身份信息及其是否可达。", "operationId": "listTravelRuleWidgetVasps", "x-didit-sdk": { "resource": "travel_rule", "method": "list_widget_vasps", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "生成 widget 会话时返回的不透明会话 token。", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string", "maxLength": 255 }, "description": "名称或别名片段（不区分大小写）、精确的 LEI 或域名（example.com 或其上的 URL）。Didit 网络成员通过其法定名称、LEI 或合规邮箱的域名进行匹配。" }, { "name": "network", "in": "query", "schema": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA", "TRISA" ] }, "description": "仅包含网络成员目录当前列出的目录条目。" }, { "name": "jurisdiction", "in": "query", "schema": { "type": "string" }, "description": "ISO 3166 alpha-2 或 alpha-3 国家/地区代码。任何其他代码均返回 400。" }, { "name": "reachable", "in": "query", "schema": { "type": "boolean" }, "description": "true：仅返回您的应用拥有可用路由的 VASP（包括 Didit 网络成员）。false：仅返回当前无法送达的目录条目。" }, { "name": "kind", "in": "query", "schema": { "type": "string", "enum": [ "directory", "didit" ] }, "description": "仅目录条目，或仅 Didit 网络成员。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl 'https://verification.didit.me/v3/travel-rule/widget/{token}/vasps/?search=counterparty'" } ], "responses": { "200": { "description": "按名称排序的分页结果。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/VaspDirectoryWidgetEntry" } } } } } } }, "400": { "description": "过滤器无效：请求体列出了每个字段，例如未知的网络或国家/地区代码。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "jurisdiction": [ "Use an ISO 3166 alpha-2 or alpha-3 country code." ], "network": [ "\"SWIFT\" is not a valid choice." ] } } } }, "404": { "description": "未知的 token。" }, "410": { "description": "会话已过期。" } } }, "post": { "summary": "在钱包组件中选择交易对手 VASP", "description": "基于小部件会话 token 的公开写入 endpoint，无需 API 密钥：终端用户选择了自动发现机制无法确定的目标 VASP。仅当出向转账处于 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 或 NOT_ENOUGH_COUNTERPARTY_DATA 状态时，才接受此操作。该转账将路由至该 VASP 并重新发送；自动发现机制绝不会覆盖该选择。", "operationId": "selectTravelRuleWidgetVasp", "x-didit-sdk": { "resource": "travel_rule", "method": "select_widget_vasp", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "生成 widget 会话时返回的不透明会话 token。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "vasp" ], "properties": { "vasp": { "type": "string", "format": "uuid", "description": "来自 `GET /v3/travel-rule/widget/{token}/vasps/` 的 VASP `id`。" } } }, "example": { "vasp": "9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget/{token}/vasps/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"vasp\": \"9f1c2b34-5d6e-4f70-8a91-b2c3d4e5f607\"}'" } ], "responses": { "200": { "description": "已记录该选择，正在重新发送转账。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "transfer_status": { "type": "string", "description": "选取后的转账状态。" }, "counterparty_vasp": { "type": "string", "description": "终端用户选择的 VASP 名称。" } } }, "example": { "detail": "Counterparty VASP selected; the transfer is being resent.", "transfer_status": "AWAITING_COUNTERPARTY", "counterparty_vasp": "Northwind Exchange" } } } }, "400": { "description": "缺少 `vasp`，或者实时目录中没有该 ID 的有效条目。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "example": { "vasp": [ "No directory entry has this id." ] } } } }, "404": { "description": "未知的 token。" }, "409": { "description": "小组件会话未关联到 Travel Rule 转账，或者该转账不是处于允许指定交易对手状态的出向转账。" }, "410": { "description": "会话已过期。" } } } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/": { "patch": { "summary": "切换用户的持续 AML 监控", "description": "在用户级别启用或停用持续 AML 监控。每个用户仅保留一次受监控的 AML 筛查；没有任何 AML 筛查的用户（例如导入的用户）将先创建并进行一次筛查，按常规 AML 筛查计费。设置 estimate_only 可在不写入的情况下预览数量和成本。20 个或更少的批次将以内联方式解析（200，COMPLETED）；更大的批次将返回 202 并异步运行。", "operationId": "toggle_vendor_users_ongoing_monitoring", "x-didit-sdk": { "resource": "users", "method": "set_ongoing_monitoring", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Users" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleRequest" }, "example": { "is_enabled": true, "didit_internal_id_list": [ "5b9a0000-0000-4000-8000-00000000f00d" ] } } } }, "responses": { "200": { "description": "预估（当 estimate_only 时）或小批量内联处理的已完成任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleResult" } } } }, "202": { "description": "较大的批次将异步处理；使用返回的 job_id 轮询 job endpoint。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "403": { "description": "缺少 write:sessions 权限，或余额不足以启用（预估金额包含在错误响应体中）。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.set_ongoing_monitoring(\n is_enabled=True,\n didit_internal_id_list=[\"5b9a0000-0000-4000-8000-00000000f00d\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.setOngoingMonitoring({\n is_enabled: true,\n didit_internal_id_list: [\"5b9a0000-0000-4000-8000-00000000f00d\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.SetOngoingMonitoring(ctx, didit.OngoingMonitoringToggleRequest{\n\tIsEnabled: true,\n\tDiditInternalIDList: didit.Some([]string{\"5b9a0000-0000-4000-8000-00000000f00d\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.OngoingMonitoringToggleRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().setOngoingMonitoring(OngoingMonitoringToggleRequest.builder()\n .isEnabled(true)\n .diditInternalIdList(List.of(\"5b9a0000-0000-4000-8000-00000000f00d\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->setOngoingMonitoring([\n 'is_enabled' => true,\n 'didit_internal_id_list' => ['5b9a0000-0000-4000-8000-00000000f00d'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.set_ongoing_monitoring(\n is_enabled: true,\n didit_internal_id_list: [\"5b9a0000-0000-4000-8000-00000000f00d\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.SetOngoingMonitoringAsync(new OngoingMonitoringToggleRequest\n{\n IsEnabled = true,\n DiditInternalIdList = new string[] { \"5b9a0000-0000-4000-8000-00000000f00d\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-users/toggle-ongoing-monitoring/{job_id}/": { "get": { "summary": "获取 AML 持续监控任务", "description": "监控切换任务的进度及各结果计数器。当状态为 PENDING 或 PROCESSING 时，每隔几秒轮询一次。", "operationId": "get_vendor_users_ongoing_monitoring_job", "x-didit-sdk": { "resource": "users", "method": "retrieve_ongoing_monitoring_job", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Users" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "切换 endpoint 返回的监控任务 UUID。" } ], "responses": { "200": { "description": "作业。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "404": { "description": "此应用的未知任务。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.retrieve_ongoing_monitoring_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.RetrieveOngoingMonitoringJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->retrieveOngoingMonitoringJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.retrieve_ongoing_monitoring_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.RetrieveOngoingMonitoringJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/": { "patch": { "summary": "切换企业的持续 AML 监控", "description": "企业级别的等效用户切换：每个企业一个受监控的 AML 筛查，缺少任何 AML 筛查的企业优先进行筛查（企业实体）。相同的 estimate_only、内联快速路径和异步作业约定。", "operationId": "toggle_vendor_businesses_ongoing_monitoring", "x-didit-sdk": { "resource": "businesses", "method": "set_ongoing_monitoring", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleRequest" }, "example": { "is_enabled": true, "didit_internal_id_list": [ "b0000000-0000-4000-8000-0000000000b1" ] } } } }, "responses": { "200": { "description": "预估（当 estimate_only 时）或小批量内联处理的已完成任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleResult" } } } }, "202": { "description": "较大的批次将异步处理；使用返回的 job_id 轮询 job endpoint。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "403": { "description": "缺少 write:sessions 权限，或余额不足以启用（预估金额包含在错误响应体中）。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.set_ongoing_monitoring(\n is_enabled=True,\n didit_internal_id_list=[\"b0000000-0000-4000-8000-0000000000b1\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.setOngoingMonitoring({\n is_enabled: true,\n didit_internal_id_list: [\"b0000000-0000-4000-8000-0000000000b1\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.SetOngoingMonitoring(ctx, didit.OngoingMonitoringToggleRequest{\n\tIsEnabled: true,\n\tDiditInternalIDList: didit.Some([]string{\"b0000000-0000-4000-8000-0000000000b1\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.OngoingMonitoringToggleRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().setOngoingMonitoring(OngoingMonitoringToggleRequest.builder()\n .isEnabled(true)\n .diditInternalIdList(List.of(\"b0000000-0000-4000-8000-0000000000b1\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->setOngoingMonitoring([\n 'is_enabled' => true,\n 'didit_internal_id_list' => ['b0000000-0000-4000-8000-0000000000b1'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.set_ongoing_monitoring(\n is_enabled: true,\n didit_internal_id_list: [\"b0000000-0000-4000-8000-0000000000b1\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.SetOngoingMonitoringAsync(new OngoingMonitoringToggleRequest\n{\n IsEnabled = true,\n DiditInternalIdList = new string[] { \"b0000000-0000-4000-8000-0000000000b1\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/vendor-businesses/toggle-ongoing-monitoring/{job_id}/": { "get": { "summary": "获取 AML 持续监控任务", "description": "监控切换任务的进度及各结果计数器。当状态为 PENDING 或 PROCESSING 时，每隔几秒轮询一次。", "operationId": "get_vendor_businesses_ongoing_monitoring_job", "x-didit-sdk": { "resource": "businesses", "method": "retrieve_ongoing_monitoring_job", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "切换 endpoint 返回的监控任务 UUID。" } ], "responses": { "200": { "description": "作业。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "404": { "description": "此应用的未知任务。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.retrieve_ongoing_monitoring_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.RetrieveOngoingMonitoringJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().retrieveOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->retrieveOngoingMonitoringJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.retrieve_ongoing_monitoring_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.RetrieveOngoingMonitoringJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/": { "patch": { "summary": "切换企业会话的持续 AML 监控", "description": "用于 KYB 验证的会话级开关，通过会话编号寻址。没有 AML 筛查的会话将自动创建一项 AML 筛查并附加到会话本身。具有与用户级 endpoint 相同的 estimate_only、内联快速通道和异步作业约定。取代了跳过未进行 AML 筛查的会话的旧版同步行为。", "operationId": "toggle_business_sessions_ongoing_monitoring", "x-didit-sdk": { "resource": "businesses", "method": "set_session_ongoing_monitoring", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_enabled" ], "properties": { "is_enabled": { "type": "boolean", "description": "为 true 表示启用监控，为 false 表示停用监控。" }, "estimate_only": { "type": "boolean", "default": false, "description": "为 true 时，返回费用估算且不执行任何写入。" }, "update_all": { "type": "boolean", "default": false, "description": "应用于该应用的所有实体（存在 filter_* 参数时受其限定）。" }, "filter_search": { "type": "string" }, "filter_status": { "type": "array", "items": { "type": "string" } }, "filter_country": { "type": "string" }, "filter_date_from": { "type": "string", "format": "date" }, "filter_date_to": { "type": "string", "format": "date" }, "session_numbers": { "type": "array", "items": { "type": "string" }, "description": "要切换的企业会话编号。除非 update_all（或旧版 toggle_all 别名）为 true，否则必填。" }, "toggle_all": { "type": "boolean", "default": false, "description": "update_all 的旧版别名。" }, "filter_workflow_id": { "type": "string" } } }, "example": { "is_enabled": true, "session_numbers": [ "1001", "1002" ] } } } }, "responses": { "200": { "description": "预估（当 estimate_only 时）或小批量内联处理的已完成任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringToggleResult" } } } }, "202": { "description": "较大的批次将异步处理；使用返回的 job_id 轮询 job endpoint。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "403": { "description": "缺少 write:sessions 权限，或余额不足以启用（预估金额包含在错误响应体中）。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.set_session_ongoing_monitoring(\n is_enabled=True,\n session_numbers=[\"1001\", \"1002\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.setSessionOngoingMonitoring({\n is_enabled: true,\n session_numbers: [\"1001\", \"1002\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.SetSessionOngoingMonitoring(ctx, didit.BusinessesSetSessionOngoingMonitoringParams{\n\tIsEnabled: true,\n\tSessionNumbers: didit.Some([]string{\"1001\", \"1002\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BusinessesSetSessionOngoingMonitoringParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().setSessionOngoingMonitoring(BusinessesSetSessionOngoingMonitoringParams.builder()\n .isEnabled(true)\n .sessionNumbers(List.of(\"1001\", \"1002\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->setSessionOngoingMonitoring([\n 'is_enabled' => true,\n 'session_numbers' => ['1001', '1002'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.set_session_ongoing_monitoring(\n is_enabled: true,\n session_numbers: [\"1001\", \"1002\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.SetSessionOngoingMonitoringAsync(new BusinessesSetSessionOngoingMonitoringParams\n{\n IsEnabled = true,\n SessionNumbers = new string[] { \"1001\", \"1002\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/toggle-ongoing-monitoring/{job_id}/": { "get": { "summary": "获取 AML 持续监控任务", "description": "监控切换任务的进度及各结果计数器。当状态为 PENDING 或 PROCESSING 时，每隔几秒轮询一次。", "operationId": "get_business_sessions_ongoing_monitoring_job", "x-didit-sdk": { "resource": "businesses", "method": "retrieve_session_ongoing_monitoring_job", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "切换 endpoint 返回的监控任务 UUID。" } ], "responses": { "200": { "description": "作业。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OngoingMonitoringJob" } } } }, "404": { "description": "此应用的未知任务。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.retrieve_session_ongoing_monitoring_job(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.retrieveSessionOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.RetrieveSessionOngoingMonitoringJob(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().retrieveSessionOngoingMonitoringJob(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->retrieveSessionOngoingMonitoringJob('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.retrieve_session_ongoing_monitoring_job(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.RetrieveSessionOngoingMonitoringJobAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/": { "get": { "summary": "列出案件", "description": "列出应用下的案件，最新的优先。支持过滤、搜索和排序；详见查询参数。使用 `limit`/`offset` 分页。", "operationId": "list_cases", "x-didit-sdk": { "resource": "cases", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "页面大小。默认为 50。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "第一条记录的从零开始的偏移量。" }, { "name": "status__in", "in": "query", "schema": { "type": "string" }, "description": "要包含的状态列表（以逗号分隔），例如 OPEN,AWAITING_USER。" }, { "name": "priority", "in": "query", "schema": { "type": "string" }, "description": "要包含的优先级列表（以逗号分隔）。" }, { "name": "source__in", "in": "query", "schema": { "type": "string" }, "description": "要包含的来源列表（以逗号分隔）。" }, { "name": "blueprint", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "过滤此蓝图下的案件。" }, { "name": "assigned_to", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "过滤分配给该用户的案件。" }, { "name": "unassigned", "in": "query", "schema": { "type": "boolean" }, "description": "未分配的案件为 true，已分配的案件为 false。" }, { "name": "tag", "in": "query", "schema": { "type": "string" }, "description": "过滤带有此完全相同标签的案件。" }, { "name": "search", "in": "query", "schema": { "type": "string" }, "description": "匹配 title、case_number、tag、主体姓名/UUID/外部 ID、关联的会话 UUID 或关联的交易 UUID。" }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "创建时间下限（含）。" }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "创建时间上限（含）。" }, { "name": "due_before", "in": "query", "schema": { "type": "string", "format": "date-time" }, "description": "due_at 上限。" }, { "name": "overdue", "in": "query", "schema": { "type": "boolean" }, "description": "为 true 则仅返回逾期的 open/awaiting-user 案件。" }, { "name": "ordering", "in": "query", "schema": { "type": "string", "enum": [ "created_at", "-created_at", "due_at", "-due_at" ], "default": "-created_at" }, "description": "排序顺序。due_at 将 null 排在最后。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/?status__in=OPEN,AWAITING_USER&ordering=-due_at' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.ListAutoPaging(ctx, didit.CasesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页案件列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "匹配的行数。100 以内为准确数值，超过 100 时出于性能考虑封顶显示为 100。请根据 `next` 为 null 来判断是否为最后一页。" }, "next": { "type": "string", "nullable": true, "description": "下一页的绝对 URL，或者 null。" }, "previous": { "type": "string", "nullable": true, "description": "上一页的绝对 URL，或者 null。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseListItem" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建案件", "description": "创建锚定到恰好一个主体（用户或企业）的案件，可以直接指定主体，也可以通过关联的会话/交易链接推导主体。对于通过 API 创建的案件，来源始终为 `MANUAL`。", "operationId": "create_case", "x-didit-sdk": { "resource": "cases", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title" ], "properties": { "title": { "type": "string", "maxLength": 255 }, "blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "CaseBlueprint UUID。省略则表示无蓝图。" }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "default": "MEDIUM" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "type": "object", "description": "除非提供了 links，否则为必填项；案件的唯一主体。", "properties": { "type": { "type": "string", "enum": [ "user", "business" ] }, "uuid": { "type": "string", "format": "uuid" } } }, "links": { "type": "array", "description": "创建时要附加的会话/企业会话/交易，例如 [{\"entity_type\": \"transaction\", \"entity_uuid\": \"...\"}]。当省略主体时，主体将派生自第一个关联的所有者。", "items": { "type": "object" } }, "assigned_to": { "type": "string", "format": "uuid", "nullable": true, "description": "要立即分配的用户 UUID。" }, "review_duplicates": { "type": "boolean", "default": false, "description": "在创建案件前重新检查现有的调查。若为 true，存在现有案件的主体必须提供非空的 separate_incident_reason。控制台始终启用此保护。省略该参数将保留现有的 API 行为。" }, "separate_incident_reason": { "type": "string", "maxLength": 1000 }, "source_context": { "$ref": "#/components/schemas/CaseDuplicateCaseFraudSourceContextRequest" } } }, "example": { "title": "Manual - Jane Doe", "blueprint": "b1de0000-0000-4000-8000-000000000002", "priority": "HIGH", "subject": { "type": "user", "uuid": "5b9a0000-0000-4000-8000-00000000f00d" }, "tags": [ "review" ] } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Manual - Jane Doe\", \"blueprint\": \"b1de0000-0000-4000-8000-000000000002\", \"priority\": \"HIGH\", \"subject\": {\"type\": \"user\", \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\"}, \"tags\": [\"review\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.create(\n title=\"Manual - Jane Doe\",\n blueprint=\"b1de0000-0000-4000-8000-000000000002\",\n priority=\"HIGH\",\n tags=[\"review\"],\n subject={\n \"type\": \"user\",\n \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.create({\n title: \"Manual - Jane Doe\",\n blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n priority: \"HIGH\",\n tags: [\"review\"],\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Create(ctx, didit.CasesCreateParams{\n\tTitle: \"Manual - Jane Doe\",\n\tBlueprint: didit.String(\"b1de0000-0000-4000-8000-000000000002\"),\n\tPriority: didit.Some(didit.CasesCreateParamsPriority(\"HIGH\")),\n\tTags: didit.Some([]string{\"review\"}),\n\tSubject: didit.Some(didit.CasesCreateParamsSubject{\n\t\tType: didit.Some(didit.CasesCreateParamsSubjectType(\"user\")),\n\t\tUUID: didit.String(\"5b9a0000-0000-4000-8000-00000000f00d\"),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().create(CasesCreateParams.builder()\n .title(\"Manual - Jane Doe\")\n .blueprint(\"b1de0000-0000-4000-8000-000000000002\")\n .priority(CasesCreateParams.Priority.of(\"HIGH\"))\n .tags(List.of(\"review\"))\n .subject(CasesCreateParams.Subject.builder()\n .type(CasesCreateParams.Subject.Type.of(\"user\"))\n .uuid(\"5b9a0000-0000-4000-8000-00000000f00d\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->create([\n 'title' => 'Manual - Jane Doe',\n 'blueprint' => 'b1de0000-0000-4000-8000-000000000002',\n 'priority' => 'HIGH',\n 'tags' => ['review'],\n 'subject' => [\n 'type' => 'user',\n 'uuid' => '5b9a0000-0000-4000-8000-00000000f00d',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.create(\n title: \"Manual - Jane Doe\",\n blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n priority: \"HIGH\",\n tags: [\"review\"],\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.CreateAsync(new CasesCreateParams\n{\n Title = \"Manual - Jane Doe\",\n Blueprint = \"b1de0000-0000-4000-8000-000000000002\",\n Priority = new CasesCreateParamsPriority(\"HIGH\"),\n Tags = new string[] { \"review\" },\n Subject = new CasesCreateParamsSubject\n {\n Type = new CasesCreateParamsSubjectType(\"user\"),\n Uuid = \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "案件已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "400": { "description": "既未提供 subject 也未提供 links，或未找到 subject/blueprint/assignee。", "content": { "application/json": { "schema": { "type": "object" } } } }, "409": { "description": "重复审核已启用，且找到了没有独立事件原因的现有案件。未创建任何案件。" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/": { "get": { "summary": "获取案件", "description": "获取案件及其主体、蓝图、备注、事件、链接和清单。", "operationId": "get_case", "x-didit-sdk": { "resource": "cases", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.retrieve(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.retrieve(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Retrieve(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().retrieve(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->retrieve('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.retrieve(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RetrieveAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "案件详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "404": { "description": "在此应用中未找到案件（或嵌套资源）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新案件", "description": "更新案件的标题、优先级、截止日期、标签或所属审核团队。仅发送您想要更改的字段；省略的字段将保留其原值。`tags` 会替换整个标签列表。`team` 接受此应用中某个活跃审核团队的 uuid（可通过 `GET .../cases/teams/` 列出），或为 null 以清除团队。需要完全访问权限的 API 密钥，或者控制台成员具备 `write:cases` 权限：受限访问权限的密钥将收到 403。视情况记录 PRIORITY_CHANGED、DUE_DATE_CHANGED、TAG_ADDED、TAG_REMOVED 和 TEAM_CHANGED 事件；标题更改会被保存但不会生成时间线事件。返回更新后的案件。", "operationId": "update_case", "x-didit-sdk": { "resource": "cases", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255, "description": "新案件标题。" }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "due_at": { "type": "string", "format": "date-time", "nullable": true, "description": "新截止日期。发送 null 可清除该值。" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "完整的标签列表。它将替换当前的标签。" }, "team": { "type": "string", "format": "uuid", "nullable": true, "description": "负责该案件的审核团队的 UUID。必须是此应用下的活跃团队。发送 null 可清除团队。" } } }, "examples": { "Change priority and deadline": { "value": { "priority": "HIGH", "due_at": "2026-11-01T00:00:00Z" } }, "Move the case to a team": { "value": { "team": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, "Clear the team": { "value": { "team": null } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"priority\": \"HIGH\", \"due_at\": \"2026-08-01T00:00:00Z\"}'" }, { "lang": "curl", "label": "curl (change team)", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"team\": \"3fa85f64-5717-4562-b3fc-2c963f66afa6\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.update(\n \"c1a5e000-0000-4000-8000-000000000001\",\n priority=\"HIGH\",\n due_at=\"2026-11-01T00:00:00Z\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.update(\"c1a5e000-0000-4000-8000-000000000001\", {\n priority: \"HIGH\",\n due_at: \"2026-11-01T00:00:00Z\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Update(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesUpdateParams{\n\tPriority: didit.Some(didit.CasesUpdateParamsPriority(\"HIGH\")),\n\tDueAt: didit.Time(time.Date(2026, 11, 1, 0, 0, 0, 0, time.UTC)),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport me.didit.Didit;\nimport me.didit.types.CasesUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().update(\"c1a5e000-0000-4000-8000-000000000001\", CasesUpdateParams.builder()\n .priority(CasesUpdateParams.Priority.of(\"HIGH\"))\n .dueAt(OffsetDateTime.parse(\"2026-11-01T00:00:00Z\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->update('c1a5e000-0000-4000-8000-000000000001', [\n 'priority' => 'HIGH',\n 'due_at' => '2026-11-01T00:00:00Z',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.update(\n \"c1a5e000-0000-4000-8000-000000000001\",\n priority: \"HIGH\",\n due_at: \"2026-11-01T00:00:00Z\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.UpdateAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesUpdateParams\n{\n Priority = new CasesUpdateParamsPriority(\"HIGH\"),\n DueAt = DateTimeOffset.Parse(\"2026-11-01T00:00:00Z\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新案件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "400": { "description": "字段验证失败。响应体以字段名为键。如果 `team` 不是此应用的活动审核团队，则会被拒绝。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Team not active in this application": { "value": { "team": [ "Choose an active team of this application." ] } }, "Invalid priority": { "value": { "priority": [ "\"URGENT\" is not a valid choice." ] } } } } } }, "403": { "description": "API 密钥属于另一个应用，或者是一个访问权限受限的密钥：Cases endpoint 需要具有完全访问权限的密钥。控制台成员 token 需要 `write:cases` 权限。", "content": { "application/json": { "examples": { "Restricted API Key": { "summary": "受限访问权限的 API 密钥", "value": { "detail": "This API key has no access to this endpoint." } }, "Missing Privilege": { "summary": "不具备 write:cases 权限的 Console 成员，或其他应用的密钥", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "在此应用中未找到案件。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No Case matches the given query." } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "删除案件", "description": "永久删除一个案件。其草稿监管报告也会随之一同删除。关联的验证、人员、企业和交易不会被删除。不存在恢复删除的 endpoint。\n\n如果案件包含已定稿的监管报告，整个请求将被拒绝并返回 `409`，且不会删除任何内容。响应体使用 `code: in_filed_report`，并通过 `uuid`、`report_number`、`report_type` 和 `case_uuid` 列出每份报告。请先删除这些报告，然后重试请求。", "operationId": "delete_case", "x-didit-sdk": { "resource": "cases", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.delete(\"c1a5e000-0000-4000-8000-000000000001\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Delete(ctx, \"c1a5e000-0000-4000-8000-000000000001\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().delete(\"c1a5e000-0000-4000-8000-000000000001\");" }, { "lang": "php", "label": "PHP", "source": "cases->delete('c1a5e000-0000-4000-8000-000000000001');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.delete(\"c1a5e000-0000-4000-8000-000000000001\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.DeleteAsync(\"c1a5e000-0000-4000-8000-000000000001\");" } ], "responses": { "204": { "description": "案件已删除。" }, "403": { "description": "该密钥无法删除案件。它需要具有 `write:cases` 权限的全权访问密钥。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "404": { "description": "该案件在此应用中不存在或已被删除。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "409": { "description": "该案件已有定稿的监管报告。未删除任何内容。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/assign/": { "post": { "summary": "分配或取消分配案件", "description": "将案件分配给用户，或发送 assignee_user_id: null 取消分配。若被分配者尚不存在，assignee_email/assignee_name 将自动预配 User 记录。", "operationId": "assign_case", "x-didit-sdk": { "resource": "cases", "method": "assign", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "assignee_user_id" ], "properties": { "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "设为 null 以取消分配。" }, "assignee_email": { "type": "string", "format": "email", "nullable": true }, "assignee_name": { "type": "string", "nullable": true } } }, "example": { "assignee_user_id": "9a000000-0000-4000-8000-0000000000aa" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/assign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"assignee_user_id\": \"9a000000-0000-4000-8000-0000000000aa\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.assign(\n \"c1a5e000-0000-4000-8000-000000000001\",\n assignee_user_id=\"9a000000-0000-4000-8000-0000000000aa\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.assign(\"c1a5e000-0000-4000-8000-000000000001\", {\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Assign(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesAssignParams{\n\tAssigneeUserID: didit.String(\"9a000000-0000-4000-8000-0000000000aa\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesAssignParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().assign(\"c1a5e000-0000-4000-8000-000000000001\", CasesAssignParams.builder()\n .assigneeUserId(\"9a000000-0000-4000-8000-0000000000aa\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->assign('c1a5e000-0000-4000-8000-000000000001', [\n 'assignee_user_id' => '9a000000-0000-4000-8000-0000000000aa',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.assign(\n \"c1a5e000-0000-4000-8000-000000000001\",\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.AssignAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesAssignParams\n{\n AssigneeUserId = \"9a000000-0000-4000-8000-0000000000aa\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "案件已分配/未分配。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/resolve/": { "post": { "summary": "解决案件", "description": "使用以下五种处置结果之一解决该案件：FALSE_POSITIVE（未发现隐患）、VALID_THREAT（隐患已确认）、INCONCLUSIVE、REQUIREMENTS_NOT_MET 或 REQUIREMENTS_SATISFIED。如果蓝图的清单不是可选的且仍有未完成项，或者蓝图要求提供处置备注但未提供，则会被拦截并返回 400。当案件的蓝图包含双人复核步骤（four_eyes_checker_blueprint）时，处置结果会被暂存（case.pending_resolution），且案件会移至复核蓝图而不是立即解决；必须由另一位工作人员调用 approve 或 reject-approval。请以控制台成员身份提交双人复核处置：由 API 密钥提交的处置没有记录经办人，因此 approve 和 reject-approval 对任何调用方都会返回 403。在双人复核蓝图上，您可以使用 `checker` 指定必须批准的成员：届时只有该成员可以批准或拒绝该处置，且响应中的 `checker` 会显示该成员。如果不指定 `checker`，处置将在复核蓝图的队列中等待。为没有复核步骤的蓝图发送 `checker` 将返回 400。", "operationId": "resolve_case", "x-didit-sdk": { "resource": "cases", "method": "resolve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "resolution" ], "properties": { "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ] }, "note": { "type": "string", "nullable": true, "description": "当蓝图设置了 require_resolution_note 时必填。" }, "checker": { "type": "string", "format": "uuid", "nullable": true, "description": "仅限双人复核蓝图。必须批准此决议的成员用户 uuid（与案件上的 `assigned_to.uuid` 或审核团队中的 `members[].user_id` 相同）。该成员必须对此应用具有案件访问权限，且不能是提交该决议的工作人员。省略该字段或发送 null 可将决议交由复核员队列处理。" } } }, "examples": { "Resolve": { "value": { "resolution": "FALSE_POSITIVE", "note": "Confirmed legitimate activity after reviewing documents." } }, "Four-eyes blueprint with a named checker": { "value": { "resolution": "VALID_THREAT", "note": "Document tampering confirmed.", "checker": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/resolve/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"resolution\": \"FALSE_POSITIVE\", \"note\": \"Confirmed legitimate activity after reviewing documents.\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.resolve(\n \"c1a5e000-0000-4000-8000-000000000001\",\n resolution=\"FALSE_POSITIVE\",\n note=\"Confirmed legitimate activity after reviewing documents.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.resolve(\"c1a5e000-0000-4000-8000-000000000001\", {\n resolution: \"FALSE_POSITIVE\",\n note: \"Confirmed legitimate activity after reviewing documents.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Resolve(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesResolveParams{\n\tResolution: \"FALSE_POSITIVE\",\n\tNote: didit.String(\"Confirmed legitimate activity after reviewing documents.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesResolveParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().resolve(\"c1a5e000-0000-4000-8000-000000000001\", CasesResolveParams.builder()\n .resolution(CasesResolveParams.Resolution.of(\"FALSE_POSITIVE\"))\n .note(\"Confirmed legitimate activity after reviewing documents.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->resolve('c1a5e000-0000-4000-8000-000000000001', [\n 'resolution' => 'FALSE_POSITIVE',\n 'note' => 'Confirmed legitimate activity after reviewing documents.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.resolve(\n \"c1a5e000-0000-4000-8000-000000000001\",\n resolution: \"FALSE_POSITIVE\",\n note: \"Confirmed legitimate activity after reviewing documents.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ResolveAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesResolveParams\n{\n Resolution = \"FALSE_POSITIVE\",\n Note = \"Confirmed legitimate activity after reviewing documents.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已解决，或已暂存以待双人复核。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "400": { "description": "该处置被拒绝。非字段错误以字符串列表形式返回：清单未完成、缺少必填备注，或者 `checker` 无法核验或不是对此应用具有案件访问权限的活跃审核员。`checker` 错误以该字段为键返回：指定成员是提交处置的工作人员，或者案件蓝图没有复核步骤。", "content": { "application/json": { "schema": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } } ] }, "examples": { "Incomplete checklist": { "value": [ "Case has incomplete checklist items: Verify source of funds" ] }, "Resolution note required": { "value": [ "A resolution note is required to resolve this case." ] }, "Reviewer access could not be verified": { "value": [ "Reviewer access could not be verified. Try again." ] }, "Checker is not an active reviewer": { "value": [ "Choose an active reviewer with case access to this application." ] }, "Checker is the submitting officer": { "value": { "checker": [ "The officer who submitted the resolution cannot be its checker." ] } }, "Policy has no checker step": { "value": { "checker": [ "This review policy has no checker step, so the case resolves directly." ] } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/reopen/": { "post": { "summary": "重新打开案件", "description": "将处于 awaiting-user 或 resolved 状态的案件移回 open，同时清除 resolution、resolution_notes、resolved_at 和 resolved_by_email。", "operationId": "reopen_case", "x-didit-sdk": { "resource": "cases", "method": "reopen", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/reopen/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.reopen(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.reopen(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Reopen(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().reopen(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->reopen('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.reopen(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ReopenAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "重新打开案件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/request-info/": { "post": { "summary": "请求信息（等待用户）", "description": "在向已验证用户收集更多信息时，将 open 状态的案件移至 awaiting_user。如果某个解决方案当前正等待双人审核（4-eyes）批准，则失败并返回 400。", "operationId": "request_case_info", "x-didit-sdk": { "resource": "cases", "method": "request_info", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/request-info/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.request_info(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requestInfo(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RequestInfo(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requestInfo(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requestInfo('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.request_info(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RequestInfoAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "请求信息（等待用户）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/escalate/": { "post": { "summary": "升级案件", "description": "将案件移动到其 blueprint 配置的 escalation_blueprint。要求当前 blueprint 已启用 escalation_enabled 并设置了 escalation_blueprint，否则返回 400。", "operationId": "escalate_case", "x-didit-sdk": { "resource": "cases", "method": "escalate", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/escalate/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.escalate(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.escalate(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Escalate(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().escalate(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->escalate('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.escalate(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.EscalateAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "升级案件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/transfer/": { "post": { "summary": "移交案件", "description": "将案件移动到同一应用下的另一个处于活动状态的 blueprint。要求当前 blueprint 已启用 transfer_enabled，否则返回 400。", "operationId": "transfer_case", "x-didit-sdk": { "resource": "cases", "method": "transfer", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "target_blueprint" ], "properties": { "target_blueprint": { "type": "string", "format": "uuid" } } }, "example": { "target_blueprint": "b1de0000-0000-4000-8000-000000000002" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/transfer/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"target_blueprint\": \"b1de0000-0000-4000-8000-000000000002\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.transfer(\n \"c1a5e000-0000-4000-8000-000000000001\",\n target_blueprint=\"b1de0000-0000-4000-8000-000000000002\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.transfer(\"c1a5e000-0000-4000-8000-000000000001\", {\n target_blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Transfer(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesTransferParams{\n\tTargetBlueprint: \"b1de0000-0000-4000-8000-000000000002\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesTransferParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().transfer(\"c1a5e000-0000-4000-8000-000000000001\", CasesTransferParams.builder()\n .targetBlueprint(\"b1de0000-0000-4000-8000-000000000002\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->transfer('c1a5e000-0000-4000-8000-000000000001', [\n 'target_blueprint' => 'b1de0000-0000-4000-8000-000000000002',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.transfer(\n \"c1a5e000-0000-4000-8000-000000000001\",\n target_blueprint: \"b1de0000-0000-4000-8000-000000000002\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.TransferAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesTransferParams\n{\n TargetBlueprint = \"b1de0000-0000-4000-8000-000000000002\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "案件已转移。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/approve/": { "post": { "summary": "批准暂存的解决方案（双人复核）", "description": "在双人复核（four-eyes）蓝图上应用通过 resolve 暂存的处置方案。调用方必须是与提交该方案的人员不同的工作人员，否则返回 403。当处置方案指定了复核人（案件的 `checker`）时，只有该成员可以批准：任何其他调用方（包括 API 密钥）都会收到 403。", "operationId": "approve_case_resolution", "x-didit-sdk": { "resource": "cases", "method": "approve_resolution", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/approve/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.approve_resolution(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.approveResolution(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ApproveResolution(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().approveResolution(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->approveResolution('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.approve_resolution(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ApproveResolutionAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "决议已应用。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "409": { "description": "案件没有待审批的决议。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "403": { "description": "调用方无法批准此决议：决议由其提交、案件没有记录的发起者，或者决议指定了不同的审核者。指定审核者时，API 密钥始终会收到此 403 错误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Caller submitted the resolution": { "value": { "detail": "The officer who submitted the resolution cannot approve it." } }, "No recorded maker": { "value": { "detail": "Case has no recorded maker for this pending resolution; approve is not permitted." } }, "Caller is not the named checker": { "value": { "detail": "Only the named checker can approve this resolution." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/reject-approval/": { "post": { "summary": "拒绝暂存的决议（双人复核）", "description": "拒绝由 resolve 暂存的决议并将案件退回至创建该决议的人员所用的蓝图。调用方必须是与提交该决议不同的合规官，否则返回 403。当决议指定了复核员（案件的 `checker`）时，只有该成员可以拒绝它：包括 API 密钥在内的任何其他调用方都将收到 403。", "operationId": "reject_case_resolution", "x-didit-sdk": { "resource": "cases", "method": "reject_resolution", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "notes": { "type": "string", "nullable": true } } }, "example": { "notes": "Needs a clearer rationale before this can be approved." } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/reject-approval/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"notes\": \"Needs a clearer rationale before this can be approved.\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.reject_resolution(\n \"c1a5e000-0000-4000-8000-000000000001\",\n notes=\"Needs a clearer rationale before this can be approved.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.rejectResolution(\"c1a5e000-0000-4000-8000-000000000001\", {\n notes: \"Needs a clearer rationale before this can be approved.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RejectResolution(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesRejectResolutionParams{\n\tNotes: didit.String(\"Needs a clearer rationale before this can be approved.\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesRejectResolutionParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().rejectResolution(\"c1a5e000-0000-4000-8000-000000000001\", CasesRejectResolutionParams.builder()\n .notes(\"Needs a clearer rationale before this can be approved.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->rejectResolution('c1a5e000-0000-4000-8000-000000000001', [\n 'notes' => 'Needs a clearer rationale before this can be approved.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.reject_resolution(\n \"c1a5e000-0000-4000-8000-000000000001\",\n notes: \"Needs a clearer rationale before this can be approved.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RejectResolutionAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesRejectResolutionParams\n{\n Notes = \"Needs a clearer rationale before this can be approved.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "决议已拒绝，案件已退回至 maker 蓝图。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDetail" } } } }, "409": { "description": "案件没有待审批的决议。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "403": { "description": "调用方无法拒绝此决议：决议由其提交、案件没有记录的发起者，或者决议指定了不同的审核者。指定审核者时，API 密钥始终会收到此 403 错误。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Caller submitted the resolution": { "value": { "detail": "The officer who submitted the resolution cannot reject it." } }, "No recorded maker": { "value": { "detail": "Case has no recorded maker for this pending resolution; reject is not permitted." } }, "Caller is not the named checker": { "value": { "detail": "Only the named checker can reject this resolution." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/entity-actions/": { "post": { "operationId": "apply_case_entity_action", "x-didit-sdk": { "resource": "cases", "method": "apply_entity_action", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionRequest" }, "example": { "client_reference": "e1a00000-0000-4000-8000-000000000001", "action": "add_tags", "tags": [ "source-of-funds-reviewed" ] } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseEntityActionResult" } } }, "description": "" }, "409": { "description": "该引用属于不同的操作 payload。" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "对案件主体应用一项明确的操作。提供唯一的 client_reference 以获取操作回执并使重试具备幂等性。使用不同的 payload 重复使用该引用会返回 409。提供引用后，即使 HTTP 状态为 200，也应检查 receipt.status：FAILED 表示未应用任何操作。重复执行失败的请求不会再次执行它，除非 retry 为 true。省略 client_reference 将保留旧版响应。", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.apply_entity_action(\n \"11111111-2222-3333-4444-555555555555\",\n client_reference=\"e1a00000-0000-4000-8000-000000000001\",\n action=\"add_tags\",\n tags=[\"source-of-funds-reviewed\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.applyEntityAction(\"11111111-2222-3333-4444-555555555555\", {\n client_reference: \"e1a00000-0000-4000-8000-000000000001\",\n action: \"add_tags\",\n tags: [\"source-of-funds-reviewed\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ApplyEntityAction(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseActionCaseEntityActionRequest{\n\tClientReference: didit.String(\"e1a00000-0000-4000-8000-000000000001\"),\n\tAction: didit.CaseActionActionEnum(\"add_tags\"),\n\tTags: didit.Some([]string{\"source-of-funds-reviewed\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseActionActionEnum;\nimport me.didit.types.CaseActionCaseEntityActionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().applyEntityAction(\"11111111-2222-3333-4444-555555555555\", CaseActionCaseEntityActionRequest.builder()\n .clientReference(\"e1a00000-0000-4000-8000-000000000001\")\n .action(CaseActionActionEnum.of(\"add_tags\"))\n .tags(List.of(\"source-of-funds-reviewed\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->applyEntityAction('11111111-2222-3333-4444-555555555555', [\n 'client_reference' => 'e1a00000-0000-4000-8000-000000000001',\n 'action' => 'add_tags',\n 'tags' => ['source-of-funds-reviewed'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.apply_entity_action(\n \"11111111-2222-3333-4444-555555555555\",\n client_reference: \"e1a00000-0000-4000-8000-000000000001\",\n action: \"add_tags\",\n tags: [\"source-of-funds-reviewed\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ApplyEntityActionAsync(\"11111111-2222-3333-4444-555555555555\", new CaseActionCaseEntityActionRequest\n{\n ClientReference = \"e1a00000-0000-4000-8000-000000000001\",\n Action = \"add_tags\",\n Tags = new string[] { \"source-of-funds-reviewed\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/print/": { "get": { "summary": "打印案件（PDF）", "description": "将完整案件（摘要、主体、检查清单状态、备注、关联的会话/交易、事件、FIU 报告列表）渲染为 PDF 并返回预签名下载 URL。", "operationId": "print_case", "x-didit-sdk": { "resource": "cases", "method": "print", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/print/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.print(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.print(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Print(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().print(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->print('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.print(\"c1a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.PrintAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "预签名的 PDF URL。", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/": { "get": { "operationId": "list_case_notes", "x-didit-sdk": { "resource": "cases.notes", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "对结果进行排序时使用哪个字段。", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "每页返回的结果数量。", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "返回结果的起始索引。", "schema": { "type": "integer" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPaginatedCaseNoteList" } } }, "description": "" }, "403": { "description": "调用方缺少必需的案件权限。" }, "404": { "description": "该案件或备注对此调用方不可用。" } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.notes.list(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.notes.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Notes.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesNotesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().notes().list(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->notes->list('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.notes.list(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Notes.ListAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "operationId": "create_case_note", "x-didit-sdk": { "resource": "cases.notes", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNoteCreateRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNoteCreateRequest" }, "example": { "comment": "Proof of address matches the ID document." } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNoteCreateRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } }, "description": "" }, "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } }, "description": "" }, "403": { "description": "调用方缺少必需的案件权限。" }, "404": { "description": "该案件或备注对此调用方不可用。" }, "409": { "description": "此客户端引用已被用于其他备注或已被删除的备注。" } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "description": "添加案件范围内的备注。可选的 client_reference 可确保在未做更改的重试中返回相同备注，而不会产生重复活动或通知。reply_to 必须指向该案件中的有效备注。响应包含限定长度的父级摘录，且不会将该摘录复制到已保存的回复中。", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment=\"Proof of address matches the ID document.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.create(\"11111111-2222-3333-4444-555555555555\", {\n comment: \"Proof of address matches the ID document.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseCollaborationCaseNoteCreateRequest{\n\tComment: \"Proof of address matches the ID document.\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseCollaborationCaseNoteCreateRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().create(\"11111111-2222-3333-4444-555555555555\", CaseCollaborationCaseNoteCreateRequest.builder()\n .comment(\"Proof of address matches the ID document.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->create('11111111-2222-3333-4444-555555555555', [\n 'comment' => 'Proof of address matches the ID document.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment: \"Proof of address matches the ID document.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new CaseCollaborationCaseNoteCreateRequest\n{\n Comment = \"Proof of address matches the ID document.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/{note_uuid}/": { "patch": { "operationId": "root_partial_update", "x-didit-sdk": { "resource": "cases.notes", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "note_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPatchedCaseNoteUpdateRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPatchedCaseNoteUpdateRequest" }, "example": { "is_pinned": true } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseCollaborationPatchedCaseNoteUpdateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } }, "description": "" }, "403": { "description": "调用方缺少必需的案件权限。" }, "404": { "description": "该案件或备注对此调用方不可用。" } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "description": "置顶或取消置顶现有备注。置顶的备注排在最前面。置顶变更会记录在案件动态中，不会更改证据或来源决策。", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.update(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n is_pinned=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.update(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n {\n is_pinned: true,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.Update(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", didit.CaseCollaborationPatchedCaseNoteUpdateRequest{\n\tIsPinned: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseCollaborationPatchedCaseNoteUpdateRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().update(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", CaseCollaborationPatchedCaseNoteUpdateRequest.builder()\n .isPinned(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->update('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555', [\n 'is_pinned' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.update(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n is_pinned: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", new CaseCollaborationPatchedCaseNoteUpdateRequest\n{\n IsPinned = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "operationId": "delete_case_note", "x-didit-sdk": { "resource": "cases.notes", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "note_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "204": { "description": "该备注已被永久删除。回复仍将保留，但不包含已删除父级备注的引用片段。附件会被删除，除非其他备注仍在使用它们。" }, "403": { "description": "调用方缺少必需的案件权限。" }, "404": { "description": "该案件或备注对此调用方不可用。" } }, "tags": [ "Case Management" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Notes.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().notes().delete(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "cases->notes->delete('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Notes.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/presign/": { "post": { "summary": "上传备注附件", "description": "上传文件（JPEG、PNG、WebP、PDF、纯文本或 CSV；最大 5 MB）以附加到备注中。返回要在备注的 attachments 数组中传递的 s3_key。", "operationId": "upload_case_note_attachment", "x-didit-sdk": { "resource": "cases.notes", "method": "create_attachment_upload", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/notes/presign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'file=@evidence.pdf'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.create_attachment_upload(\n \"c1a5e000-0000-4000-8000-000000000001\",\n file=open(\"document.pdf\", \"rb\"),\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.createAttachmentUpload(\"c1a5e000-0000-4000-8000-000000000001\", {\n file: await fileFromPath(\"document.pdf\"),\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.CreateAttachmentUpload(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesNotesCreateAttachmentUploadParams{\n\tFile: didit.FileFromPath(\"document.pdf\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.CasesNotesCreateAttachmentUploadParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().createAttachmentUpload(\"c1a5e000-0000-4000-8000-000000000001\", CasesNotesCreateAttachmentUploadParams.builder()\n .file(Path.of(\"document.pdf\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->createAttachmentUpload('c1a5e000-0000-4000-8000-000000000001', [\n 'file' => File::fromPath('document.pdf'),\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.create_attachment_upload(\n \"c1a5e000-0000-4000-8000-000000000001\",\n file: Pathname(\"document.pdf\")\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.CreateAttachmentUploadAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesNotesCreateAttachmentUploadParams\n{\n File = FileUpload.FromPath(\"document.pdf\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "文件已上传。", "content": { "application/json": { "schema": { "type": "object", "properties": { "s3_key": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" }, "file_size": { "type": "integer" } } } } } }, "400": { "description": "无文件、不支持的内容类型，或文件超过 5 MB。", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "get": { "summary": "获取笔记附件 URL", "description": "为案件中某个备注已存储的附件生成新的预签名下载 URL。", "operationId": "get_case_note_attachment_url", "x-didit-sdk": { "resource": "cases.notes", "method": "retrieve_attachment_url", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" }, { "name": "s3_key", "in": "query", "schema": { "type": "string" }, "description": "附件的 s3_key，由上传接口返回或列在备注中。", "required": true } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/notes/presign/?s3_key=case-notes/c1a5e000-0000-4000-8000-000000000001/evidence.pdf' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.notes.retrieve_attachment_url(\n \"c1a5e000-0000-4000-8000-000000000001\",\n s3_key=\"your-s3-key\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.notes.retrieveAttachmentUrl(\"c1a5e000-0000-4000-8000-000000000001\", {\n s3_key: \"your-s3-key\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Notes.RetrieveAttachmentURL(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesNotesRetrieveAttachmentURLParams{\n\tS3Key: \"your-s3-key\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesNotesRetrieveAttachmentUrlParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().notes().retrieveAttachmentUrl(\"c1a5e000-0000-4000-8000-000000000001\", CasesNotesRetrieveAttachmentUrlParams.builder()\n .s3Key(\"your-s3-key\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->notes->retrieveAttachmentUrl('c1a5e000-0000-4000-8000-000000000001', [\n 's3_key' => 'your-s3-key',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.notes.retrieve_attachment_url(\n \"c1a5e000-0000-4000-8000-000000000001\",\n s3_key: \"your-s3-key\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Notes.RetrieveAttachmentUrlAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesNotesRetrieveAttachmentUrlParams\n{\n S3Key = \"your-s3-key\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "预签名 URL。", "content": { "application/json": { "schema": { "type": "object", "properties": { "s3_key": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "filename": { "type": "string" } } } } } }, "404": { "description": "s3_key 缺失或不属于该案件。", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/links/": { "get": { "summary": "列出案件链接", "description": "列出附加到案件的会话、企业会话和交易。", "operationId": "list_case_links", "x-didit-sdk": { "resource": "cases.links", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/links/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.links.list(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.links.list(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Links.List(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().links().list(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->links->list('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.links.list(\"c1a5e000-0000-4000-8000-000000000001\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Links.ListAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "案件链接。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CaseLink" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "添加案件链接", "description": "将某个会话、企业会话或交易关联至该案件。如果该实体属于与案件不同的主体，则会被拒绝并返回 400。", "operationId": "create_case_link", "x-didit-sdk": { "resource": "cases.links", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_type", "entity_uuid" ], "properties": { "entity_type": { "type": "string", "enum": [ "session", "business_session", "transaction" ] }, "entity_uuid": { "type": "string", "format": "uuid" } } }, "example": { "entity_type": "transaction", "entity_uuid": "77000000-0000-4000-8000-000000000077" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/links/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"entity_type\": \"transaction\", \"entity_uuid\": \"77000000-0000-4000-8000-000000000077\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.links.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n entity_type=\"transaction\",\n entity_uuid=\"77000000-0000-4000-8000-000000000077\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.links.create(\"c1a5e000-0000-4000-8000-000000000001\", {\n entity_type: \"transaction\",\n entity_uuid: \"77000000-0000-4000-8000-000000000077\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Links.Create(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesLinksCreateParams{\n\tEntityType: \"transaction\",\n\tEntityUUID: \"77000000-0000-4000-8000-000000000077\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesLinksCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().links().create(\"c1a5e000-0000-4000-8000-000000000001\", CasesLinksCreateParams.builder()\n .entityType(CasesLinksCreateParams.EntityType.of(\"transaction\"))\n .entityUuid(\"77000000-0000-4000-8000-000000000077\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->links->create('c1a5e000-0000-4000-8000-000000000001', [\n 'entity_type' => 'transaction',\n 'entity_uuid' => '77000000-0000-4000-8000-000000000077',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.links.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n entity_type: \"transaction\",\n entity_uuid: \"77000000-0000-4000-8000-000000000077\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Links.CreateAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesLinksCreateParams\n{\n EntityType = \"transaction\",\n EntityUuid = \"77000000-0000-4000-8000-000000000077\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "链接已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseLink" } } } }, "400": { "description": "主体属于与该案件主体不同的档案。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/links/{link_uuid}/": { "delete": { "summary": "移除案件关联", "description": "从案件中解除关联的会话、企业会话或交易。", "operationId": "delete_case_link", "x-didit-sdk": { "resource": "cases.links", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" }, { "name": "link_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "11000000-0000-4000-8000-000000000004" }, "description": "链接 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/links/11000000-0000-4000-8000-000000000004/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.links.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"11000000-0000-4000-8000-000000000004\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.links.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"11000000-0000-4000-8000-000000000004\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Links.Delete(ctx, \"c1a5e000-0000-4000-8000-000000000001\", \"11000000-0000-4000-8000-000000000004\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().links().delete(\"c1a5e000-0000-4000-8000-000000000001\", \"11000000-0000-4000-8000-000000000004\");" }, { "lang": "php", "label": "PHP", "source": "cases->links->delete('c1a5e000-0000-4000-8000-000000000001', '11000000-0000-4000-8000-000000000004');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.links.delete(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"11000000-0000-4000-8000-000000000004\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Links.DeleteAsync(\"c1a5e000-0000-4000-8000-000000000001\", \"11000000-0000-4000-8000-000000000004\");" } ], "responses": { "204": { "description": "链接已移除。" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/events/": { "get": { "summary": "列出案件事件", "description": "案件的只读审计时间线（创建、状态变更、分派、解决、上报、移交、标签/优先级/截止日期变更、实体操作等）。", "operationId": "list_case_events", "x-didit-sdk": { "resource": "cases", "method": "list_events", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "页面大小。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "从零开始的偏移量。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/events/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.list_events(\n \"c1a5e000-0000-4000-8000-000000000001\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.listEvents(\"c1a5e000-0000-4000-8000-000000000001\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.ListEventsAutoPaging(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesListEventsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().listEvents(\"c1a5e000-0000-4000-8000-000000000001\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->listEvents('c1a5e000-0000-4000-8000-000000000001') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.list_events(\"c1a5e000-0000-4000-8000-000000000001\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.ListEventsAsync(\"c1a5e000-0000-4000-8000-000000000001\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页事件，最新优先。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "匹配的行数。100 以内为准确数值，超过 100 时出于性能考虑封顶显示为 100。请根据 `next` 为 null 来判断是否为最后一页。" }, "next": { "type": "string", "nullable": true, "description": "下一页的绝对 URL，或者 null。" }, "previous": { "type": "string", "nullable": true, "description": "上一页的绝对 URL，或者 null。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseEvent" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/checklist/": { "get": { "summary": "列出案件清单", "description": "按序排列列出案件的清单项（创建时从蓝图的 content_config.checklist.items 复制）。", "operationId": "list_case_checklist", "x-didit-sdk": { "resource": "cases.checklist", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/checklist/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.checklist.list(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.checklist.list(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Checklist.List(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().checklist().list(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->checklist->list('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.checklist.list(\"c1a5e000-0000-4000-8000-000000000001\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Checklist.ListAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "检查清单项。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/CaseChecklistItem" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/checklist/{item_uuid}/": { "patch": { "summary": "切换清单项目状态", "description": "将清单项标记为已完成或未完成。只要有任何项目未完成，案件处理将被阻止，除非蓝图将该清单标记为可选。", "operationId": "toggle_case_checklist_item", "x-didit-sdk": { "resource": "cases.checklist", "method": "toggle_item", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" }, { "name": "item_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c4ec0000-0000-4000-8000-000000000005" }, "description": "检查清单项 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "is_completed" ], "properties": { "is_completed": { "type": "boolean" } } }, "example": { "is_completed": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/checklist/c4ec0000-0000-4000-8000-000000000005/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"is_completed\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.checklist.toggle_item(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"c4ec0000-0000-4000-8000-000000000005\",\n is_completed=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.checklist.toggleItem(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"c4ec0000-0000-4000-8000-000000000005\",\n {\n is_completed: true,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Checklist.ToggleItem(ctx, \"c1a5e000-0000-4000-8000-000000000001\", \"c4ec0000-0000-4000-8000-000000000005\", didit.CasesChecklistToggleItemParams{\n\tIsCompleted: true,\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesChecklistToggleItemParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().checklist().toggleItem(\"c1a5e000-0000-4000-8000-000000000001\", \"c4ec0000-0000-4000-8000-000000000005\", CasesChecklistToggleItemParams.builder()\n .isCompleted(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->checklist->toggleItem('c1a5e000-0000-4000-8000-000000000001', 'c4ec0000-0000-4000-8000-000000000005', [\n 'is_completed' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.checklist.toggle_item(\n \"c1a5e000-0000-4000-8000-000000000001\",\n \"c4ec0000-0000-4000-8000-000000000005\",\n is_completed: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Checklist.ToggleItemAsync(\"c1a5e000-0000-4000-8000-000000000001\", \"c4ec0000-0000-4000-8000-000000000005\", new CasesChecklistToggleItemParams\n{\n IsCompleted = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新清单项。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseChecklistItem" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/aml/": { "get": { "summary": "列出案件 AML 命中项", "description": "列出案件主体的 AML 筛查命中项。格式与 POST /v3/aml/ 返回的命中项相同。", "operationId": "list_case_aml_hits", "x-didit-sdk": { "resource": "cases", "method": "list_aml_hits", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/aml/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.list_aml_hits(\n \"c1a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.listAmlHits(\"c1a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ListAMLHits(ctx, \"c1a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().listAmlHits(\"c1a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->listAmlHits('c1a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.list_aml_hits(\"c1a5e000-0000-4000-8000-000000000001\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ListAmlHitsAsync(\"c1a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "AML 命中项。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AMLScreening" } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/statistics/": { "get": { "summary": "案件分析", "description": "指定日期范围内的案件分析汇总（默认为过去 30 天；最多 731 天）。图表、表格、总计、分配事件和当前队列计数均使用相同的应用范围过滤器。过滤器使用案件的当前值。日期适用于每个指标事件，因此在统计周期内分配或解决的历史案件仍会包含在内。队列深度与日期范围无关。无效的过滤器将返回 400；未知的蓝图或分配人将返回空结果。", "operationId": "get_case_analytics", "x-didit-sdk": { "resource": "cases", "method": "retrieve_statistics", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "范围开始（含）。默认为 30 天前。" }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "范围结束（含）。默认为今天。" }, { "name": "blueprint", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "按当前蓝图 UUID 过滤。" }, { "name": "assigned_to", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "按当前分配的审核员用户 UUID 过滤。" }, { "name": "priority", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "description": "按当前案件优先级过滤。" }, { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "description": "按案件创建来源过滤。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "description": "按当前案件状态过滤。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/statistics/?date_from=2026-06-01&date_to=2026-06-30' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.retrieve_statistics()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.retrieveStatistics();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RetrieveStatistics(ctx, didit.CasesRetrieveStatisticsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().retrieveStatistics();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->retrieveStatistics();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.retrieve_statistics\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RetrieveStatisticsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "分析 payload。", "content": { "application/json": { "schema": { "type": "object", "properties": { "series": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "created": { "type": "integer" }, "reviewed": { "type": "integer" } } } }, "tables": { "type": "object", "properties": { "officer": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "维度值：合规官邮箱、\"blueprint_name:uuid\"、来源或状态。缺失维度使用 \"unassigned\"/\"none\"。" }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } }, "blueprint": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "维度值：合规官邮箱、\"blueprint_name:uuid\"、来源或状态。缺失维度使用 \"unassigned\"/\"none\"。" }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } }, "source": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "维度值：合规官邮箱、\"blueprint_name:uuid\"、来源或状态。缺失维度使用 \"unassigned\"/\"none\"。" }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } }, "status": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "维度值：合规官邮箱、\"blueprint_name:uuid\"、来源或状态。缺失维度使用 \"unassigned\"/\"none\"。" }, "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } } } } }, "totals": { "type": "object", "properties": { "created": { "type": "integer" }, "assigned": { "type": "integer" }, "resolved": { "type": "integer" }, "threat_rate": { "type": "number", "format": "float" }, "false_positive_rate": { "type": "number", "format": "float" }, "unresolved": { "type": "integer" }, "reassignment_rate": { "type": "number", "format": "float" }, "escalation_rate": { "type": "number", "format": "float" }, "avg_assign_hours": { "type": "number", "format": "float" }, "avg_resolve_hours": { "type": "number", "format": "float" }, "avg_handling_hours": { "type": "number", "format": "float" } } }, "queue": { "type": "object", "description": "实时快照，不受日期范围限制。", "properties": { "open": { "type": "integer" }, "overdue": { "type": "integer" } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/bulk/status/": { "post": { "summary": "批量更新案件状态", "description": "在一次调用中对多个案件应用相同的状态流转：OPEN 表示重新打开，AWAITING_USER 表示请求信息，RESOLVED 表示解决（需要提供解决方案）。每个案件均独立评估；拦截失败（清单未完成、缺少必填备注）将按案件报告，不会中止整批操作。", "operationId": "bulk_update_case_status", "x-didit-sdk": { "resource": "cases", "method": "bulk_update_status", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "case_uuids", "status" ], "properties": { "case_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ], "description": "当 status 为 RESOLVED 时必填。" }, "note": { "type": "string", "nullable": true } } }, "example": { "case_uuids": [ "c1a5e000-0000-4000-8000-000000000001" ], "status": "RESOLVED", "resolution": "FALSE_POSITIVE" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/bulk/status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"case_uuids\": [\"c1a5e000-0000-4000-8000-000000000001\"], \"status\": \"RESOLVED\", \"resolution\": \"FALSE_POSITIVE\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.bulk_update_status(\n case_uuids=[\"c1a5e000-0000-4000-8000-000000000001\"],\n status=\"RESOLVED\",\n resolution=\"FALSE_POSITIVE\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.bulkUpdateStatus({\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n status: \"RESOLVED\",\n resolution: \"FALSE_POSITIVE\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.BulkUpdateStatus(ctx, didit.CasesBulkUpdateStatusParams{\n\tCaseUUIDs: []string{\"c1a5e000-0000-4000-8000-000000000001\"},\n\tStatus: \"RESOLVED\",\n\tResolution: didit.Some(didit.CasesBulkUpdateStatusParamsResolution(\"FALSE_POSITIVE\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesBulkUpdateStatusParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().bulkUpdateStatus(CasesBulkUpdateStatusParams.builder()\n .caseUuids(List.of(\"c1a5e000-0000-4000-8000-000000000001\"))\n .status(CasesBulkUpdateStatusParams.Status.of(\"RESOLVED\"))\n .resolution(CasesBulkUpdateStatusParams.Resolution.of(\"FALSE_POSITIVE\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->bulkUpdateStatus([\n 'case_uuids' => ['c1a5e000-0000-4000-8000-000000000001'],\n 'status' => 'RESOLVED',\n 'resolution' => 'FALSE_POSITIVE',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.bulk_update_status(\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n status: \"RESOLVED\",\n resolution: \"FALSE_POSITIVE\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.BulkUpdateStatusAsync(new CasesBulkUpdateStatusParams\n{\n CaseUuids = new string[] { \"c1a5e000-0000-4000-8000-000000000001\" },\n Status = \"RESOLVED\",\n Resolution = new CasesBulkUpdateStatusParamsResolution(\"FALSE_POSITIVE\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "按案件划分的结果。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBulkUpdateResult" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/bulk/assign/": { "post": { "summary": "批量分配案件", "description": "一次性分配（或通过 assignee_user_id: null 取消分配）多个案件。所有案件必须使用相同的蓝图；不匹配的案件将逐一报告，不会中止整批操作。", "operationId": "bulk_assign_cases", "x-didit-sdk": { "resource": "cases", "method": "bulk_assign", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Cases" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "case_uuids", "assignee_user_id" ], "properties": { "case_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1 }, "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true }, "assignee_email": { "type": "string", "format": "email", "nullable": true }, "assignee_name": { "type": "string", "nullable": true } } }, "example": { "case_uuids": [ "c1a5e000-0000-4000-8000-000000000001" ], "assignee_user_id": "9a000000-0000-4000-8000-0000000000aa" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/bulk/assign/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"case_uuids\": [\"c1a5e000-0000-4000-8000-000000000001\"], \"assignee_user_id\": \"9a000000-0000-4000-8000-0000000000aa\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.bulk_assign(\n case_uuids=[\"c1a5e000-0000-4000-8000-000000000001\"],\n assignee_user_id=\"9a000000-0000-4000-8000-0000000000aa\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.bulkAssign({\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.BulkAssign(ctx, didit.CasesBulkAssignParams{\n\tCaseUUIDs: []string{\"c1a5e000-0000-4000-8000-000000000001\"},\n\tAssigneeUserID: didit.String(\"9a000000-0000-4000-8000-0000000000aa\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesBulkAssignParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().bulkAssign(CasesBulkAssignParams.builder()\n .caseUuids(List.of(\"c1a5e000-0000-4000-8000-000000000001\"))\n .assigneeUserId(\"9a000000-0000-4000-8000-0000000000aa\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->bulkAssign([\n 'case_uuids' => ['c1a5e000-0000-4000-8000-000000000001'],\n 'assignee_user_id' => '9a000000-0000-4000-8000-0000000000aa',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.bulk_assign(\n case_uuids: [\"c1a5e000-0000-4000-8000-000000000001\"],\n assignee_user_id: \"9a000000-0000-4000-8000-0000000000aa\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.BulkAssignAsync(new CasesBulkAssignParams\n{\n CaseUuids = new string[] { \"c1a5e000-0000-4000-8000-000000000001\" },\n AssigneeUserId = \"9a000000-0000-4000-8000-0000000000aa\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "按案件划分的结果。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBulkUpdateResult" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/": { "get": { "summary": "列出蓝图", "description": "列出应用的案件蓝图。", "operationId": "list_case_blueprints", "x-didit-sdk": { "resource": "cases.blueprints", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "页面大小。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "从零开始的偏移量。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.blueprints.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.blueprints.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Blueprints.ListAutoPaging(ctx, didit.CasesBlueprintsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().blueprints().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Blueprints.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页蓝图列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "匹配行数，出于性能考虑上限为 100。" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseBlueprintListItem" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建蓝图", "description": "创建案件蓝图：通用设置（分配、上报、移交、双人复核配对）加上 content_config（驱动案件页面的六个部分）。设置 publish=false 可创建未发布的草稿；发布操作会创建其首个线上版本。丢弃从未发布的草稿会将其删除。", "operationId": "create_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "assignee_pool" ], "properties": { "name": { "type": "string", "maxLength": 24, "description": "最多 24 个字符，例如“AML 调查”。" }, "description": { "type": "string", "nullable": true }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "用户 UUID 列表。空数组将被拒绝并提示 \"Pick at least one assignee\"。" }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ], "default": "MANUAL" }, "max_active_cases": { "type": "integer", "nullable": true, "minimum": 1, "description": "自动模式阈值：“分配此蓝图的案件少于 N 个”。" }, "escalation_enabled": { "type": "boolean", "default": false }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "目标蓝图 UUID。在保存时不进行强制校验，但在 escalation_enabled 和 escalation_blueprint 均设置之前，上报操作将失败并返回 400。" }, "transfer_enabled": { "type": "boolean", "default": false }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "设置此项可启用双人复核：此蓝图上的决策结果将暂存到审核蓝图的队列中。" }, "require_resolution_note": { "type": "boolean", "default": false }, "content_config": { "$ref": "#/components/schemas/CaseContentConfig" }, "is_active": { "type": "boolean", "default": true }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760, "description": "新开启案件的默认截止时间。现有案件的截止时间保持不变。" }, "publish": { "type": "boolean", "writeOnly": true, "default": true, "description": "设置为 false 可保存未发布的草稿。在草稿显式发布之前，记录将保持非活动状态且版本为 0。省略此字段可保持现有集成的立即创建行为。" } } }, "example": { "name": "AML investigation", "assignee_pool": [ "9a000000-0000-4000-8000-0000000000aa" ], "assignment_method": "AUTOMATIC", "max_active_cases": 15, "require_resolution_note": true, "content_config": { "aml_control": { "enabled": true, "financial": true, "identity": false } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"AML investigation\", \"assignee_pool\": [\"9a000000-0000-4000-8000-0000000000aa\"], \"assignment_method\": \"AUTOMATIC\", \"max_active_cases\": 15, \"require_resolution_note\": true, \"content_config\": {\"aml_control\": {\"enabled\": true, \"financial\": true, \"identity\": false}}}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.create(\n name=\"AML investigation\",\n assignee_pool=[\"9a000000-0000-4000-8000-0000000000aa\"],\n assignment_method=\"AUTOMATIC\",\n max_active_cases=15,\n require_resolution_note=True,\n content_config={\n \"aml_control\": {\n \"enabled\": True,\n \"financial\": True,\n \"identity\": False,\n },\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.create({\n name: \"AML investigation\",\n assignee_pool: [\"9a000000-0000-4000-8000-0000000000aa\"],\n assignment_method: \"AUTOMATIC\",\n max_active_cases: 15,\n require_resolution_note: true,\n content_config: {\n aml_control: {\n enabled: true,\n financial: true,\n identity: false,\n },\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Create(ctx, didit.CasesBlueprintsCreateParams{\n\tName: \"AML investigation\",\n\tAssigneePool: []string{\"9a000000-0000-4000-8000-0000000000aa\"},\n\tAssignmentMethod: didit.Some(didit.CasesBlueprintsCreateParamsAssignmentMethod(\"AUTOMATIC\")),\n\tMaxActiveCases: didit.Int(15),\n\tRequireResolutionNote: didit.Bool(true),\n\tContentConfig: didit.Some(didit.CaseContentConfigParam{\n\t\tAMLControl: didit.Some(didit.CaseContentConfigParamAMLControl{\n\t\t\tEnabled: didit.Bool(true),\n\t\t\tFinancial: didit.Bool(true),\n\t\t\tIdentity: didit.Bool(false),\n\t\t}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseContentConfig;\nimport me.didit.types.CasesBlueprintsCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().create(CasesBlueprintsCreateParams.builder()\n .name(\"AML investigation\")\n .assigneePool(List.of(\"9a000000-0000-4000-8000-0000000000aa\"))\n .assignmentMethod(CasesBlueprintsCreateParams.AssignmentMethod.of(\"AUTOMATIC\"))\n .maxActiveCases(15L)\n .requireResolutionNote(true)\n .contentConfig(CaseContentConfig.builder()\n .amlControl(CaseContentConfig.AmlControl.builder()\n .enabled(true)\n .financial(true)\n .identity(false)\n .build())\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->create([\n 'name' => 'AML investigation',\n 'assignee_pool' => ['9a000000-0000-4000-8000-0000000000aa'],\n 'assignment_method' => 'AUTOMATIC',\n 'max_active_cases' => 15,\n 'require_resolution_note' => true,\n 'content_config' => [\n 'aml_control' => [\n 'enabled' => true,\n 'financial' => true,\n 'identity' => false,\n ],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.create(\n name: \"AML investigation\",\n assignee_pool: [\"9a000000-0000-4000-8000-0000000000aa\"],\n assignment_method: \"AUTOMATIC\",\n max_active_cases: 15,\n require_resolution_note: true,\n content_config: {\n aml_control: {\n enabled: true,\n financial: true,\n identity: false,\n },\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.CreateAsync(new CasesBlueprintsCreateParams\n{\n Name = \"AML investigation\",\n AssigneePool = new string[] { \"9a000000-0000-4000-8000-0000000000aa\" },\n AssignmentMethod = new CasesBlueprintsCreateParamsAssignmentMethod(\"AUTOMATIC\"),\n MaxActiveCases = 15,\n RequireResolutionNote = true,\n ContentConfig = new CaseContentConfig\n {\n AmlControl = new CaseContentConfigAmlControl\n {\n Enabled = true,\n Financial = true,\n Identity = false,\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "Blueprint 已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintDetail" } } } }, "400": { "description": "名称超过 24 个字符、assignee_pool 为空，或未找到交叉引用的蓝图（升级/审核员）。", "content": { "application/json": { "schema": { "type": "object" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/": { "get": { "summary": "获取蓝图", "description": "获取蓝图，包括其关联的创建源（AML 配置、交易规则、工作流节点）以及升级至该蓝图的其他蓝图。", "operationId": "get_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "blueprint_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b1de0000-0000-4000-8000-000000000002" }, "description": "Blueprint UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/b1de0000-0000-4000-8000-000000000002/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.retrieve(\n \"b1de0000-0000-4000-8000-000000000002\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.retrieve(\"b1de0000-0000-4000-8000-000000000002\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Retrieve(ctx, \"b1de0000-0000-4000-8000-000000000002\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().retrieve(\"b1de0000-0000-4000-8000-000000000002\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->retrieve('b1de0000-0000-4000-8000-000000000002');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.retrieve(\"b1de0000-0000-4000-8000-000000000002\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.RetrieveAsync(\"b1de0000-0000-4000-8000-000000000002\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Blueprint 详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新蓝图", "description": "部分更新蓝图的常规设置或 content_config。", "operationId": "update_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "blueprint_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b1de0000-0000-4000-8000-000000000002" }, "description": "Blueprint UUID。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 24, "description": "最多 24 个字符，例如“AML 调查”。" }, "description": { "type": "string", "nullable": true }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "用户 UUID 列表。空数组将被拒绝并提示 \"Pick at least one assignee\"。" }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "max_active_cases": { "type": "integer", "nullable": true, "minimum": 1, "description": "自动模式阈值：“分配此蓝图的案件少于 N 个”。" }, "escalation_enabled": { "type": "boolean" }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "目标蓝图 UUID。在保存时不进行强制校验，但在 escalation_enabled 和 escalation_blueprint 均设置之前，上报操作将失败并返回 400。" }, "transfer_enabled": { "type": "boolean" }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true, "description": "设置此项可启用双人复核：此蓝图上的决策结果将暂存到审核蓝图的队列中。" }, "require_resolution_note": { "type": "boolean" }, "content_config": { "$ref": "#/components/schemas/CaseContentConfig" }, "is_active": { "type": "boolean" }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760, "description": "新开启案件的默认截止时间。现有案件的截止时间保持不变。" }, "expected_version": { "type": "integer", "minimum": 1, "description": "编辑器打开的版本。过时的版本会返回 409，且不会更改审核策略。" } } }, "example": { "transfer_enabled": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/b1de0000-0000-4000-8000-000000000002/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"transfer_enabled\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.update(\n \"b1de0000-0000-4000-8000-000000000002\",\n transfer_enabled=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.update(\"b1de0000-0000-4000-8000-000000000002\", {\n transfer_enabled: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Update(ctx, \"b1de0000-0000-4000-8000-000000000002\", didit.CasesBlueprintsUpdateParams{\n\tTransferEnabled: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesBlueprintsUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().update(\"b1de0000-0000-4000-8000-000000000002\", CasesBlueprintsUpdateParams.builder()\n .transferEnabled(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->update('b1de0000-0000-4000-8000-000000000002', [\n 'transfer_enabled' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.update(\n \"b1de0000-0000-4000-8000-000000000002\",\n transfer_enabled: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.UpdateAsync(\"b1de0000-0000-4000-8000-000000000002\", new CasesBlueprintsUpdateParams\n{\n TransferEnabled = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新蓝图。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintDetail" } } } }, "409": { "description": "审核策略自 expected_version 以来已发生变更。在重试之前，请先查看最新版本。" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "删除蓝图", "description": "删除蓝图。删除始终会成功，且不会影响该蓝图关联的案件：现有案件将保留其蓝图引用，且其设置继续适用于这些案件。已删除的蓝图不再出现在蓝图列表中，也无法再选作转移目标；如果在等待双人审核（4-eyes）批准决议期间删除了经办人（maker）蓝图，决议被拒绝后案件将保留在复核人（checker）蓝图上。", "operationId": "delete_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "blueprint_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b1de0000-0000-4000-8000-000000000002" }, "description": "Blueprint UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/b1de0000-0000-4000-8000-000000000002/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.blueprints.delete(\n \"b1de0000-0000-4000-8000-000000000002\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.blueprints.delete(\"b1de0000-0000-4000-8000-000000000002\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Blueprints.Delete(ctx, \"b1de0000-0000-4000-8000-000000000002\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().blueprints().delete(\"b1de0000-0000-4000-8000-000000000002\");" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->delete('b1de0000-0000-4000-8000-000000000002');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.delete(\"b1de0000-0000-4000-8000-000000000002\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Blueprints.DeleteAsync(\"b1de0000-0000-4000-8000-000000000002\");" } ], "responses": { "204": { "description": "Blueprint 已删除。" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/presets/": { "get": { "summary": "列出蓝图预设", "description": "列出四种内置预设（筛查命中、AML 调查、可疑活动、KYC 审核）及其 content_config，以及各项是否已安装在此应用上。", "operationId": "list_case_blueprint_presets", "x-didit-sdk": { "resource": "cases.blueprints", "method": "list_presets", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/presets/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.list_presets()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.listPresets();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.ListPresets(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().listPresets();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->listPresets();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.list_presets\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.ListPresetsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "预设目录。", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "preset_key": { "type": "string", "enum": [ "screening_hit", "aml_investigation", "suspicious_activity", "kyc" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "content_config": { "$ref": "#/components/schemas/CaseContentConfig" }, "installed": { "type": "boolean" } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/presets/install/": { "post": { "summary": "安装蓝图预设", "description": "将一个或多个预设作为可编辑的蓝图复制到应用中。针对每个 preset_key 具有幂等性；省略 preset_keys 可安装所有尚未安装的预设。", "operationId": "install_case_blueprint_presets", "x-didit-sdk": { "resource": "cases.blueprints", "method": "install_presets", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Blueprints" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "preset_keys": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "screening_hit、aml_investigation、suspicious_activity、kyc 的子集。省略则安装全部。" } } }, "example": { "preset_keys": [ "aml_investigation", "kyc" ] } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/blueprints/presets/install/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"preset_keys\": [\"aml_investigation\", \"kyc\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.install_presets(\n preset_keys=[\"aml_investigation\", \"kyc\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.installPresets({\n preset_keys: [\"aml_investigation\", \"kyc\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.InstallPresets(ctx, didit.CasesBlueprintsInstallPresetsParams{\n\tPresetKeys: didit.Some([]string{\"aml_investigation\", \"kyc\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CasesBlueprintsInstallPresetsParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().installPresets(CasesBlueprintsInstallPresetsParams.builder()\n .presetKeys(List.of(\"aml_investigation\", \"kyc\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->installPresets([\n 'preset_keys' => ['aml_investigation', 'kyc'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.install_presets(preset_keys: [\"aml_investigation\", \"kyc\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.InstallPresetsAsync(new CasesBlueprintsInstallPresetsParams\n{\n PresetKeys = new string[] { \"aml_investigation\", \"kyc\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "已安装的一个或多个预设。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintPresetInstallResult" } } } }, "200": { "description": "没有可安装的新预设（所有请求的预设均已存在）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseBlueprintPresetInstallResult" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/report-templates/": { "get": { "summary": "列出报告模板", "description": "列出应用的 FIU 报告模板。", "operationId": "list_report_templates", "x-didit-sdk": { "resource": "report_templates", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "页面大小。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "从零开始的偏移量。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.report_templates.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.reportTemplates.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.ReportTemplates.ListAutoPaging(ctx, didit.ReportTemplatesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.reportTemplates().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.report_templates.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.ReportTemplates.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页模板列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "description": "匹配行数，出于性能考虑上限为 100。" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建报告模板", "description": "创建按司法管辖区和按报告类型的可复用 goAML 表头模板。如果 field_config 中缺少任何模板级别的必填字段（rentity_id、submission_code、currency_code_local），则会被拒绝并返回 400；无效模板无法保存，也不能用于创建报告。按申报级别的表头字段（action、submission_date、transactions）则改为在报告验证/定稿时进行强制检查。", "operationId": "create_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "jurisdiction", "report_type" ], "properties": { "name": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 国家/地区代码，保存时转换为大写。" }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "field_config": { "type": "object", "description": "可复用的 goAML 请求头默认值。模板级别的必填字段：rentity_id、submission_code 和 currency_code_local（3 字母）。可选字段：enabled_fields（包含哪些可选报告块）以及 reporting_person、location、reason 和 action 默认值。每次申报的请求头字段（action、submission_date、transactions、jurisdiction）在报告通过核验或定稿时强制要求，而不是在模板上强制要求。" } } }, "example": { "name": "US SAR default", "jurisdiction": "US", "report_type": "SAR", "field_config": { "rentity_id": "FIU-US-00123", "submission_code": "E", "currency_code_local": "USD" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"US SAR default\", \"jurisdiction\": \"US\", \"report_type\": \"SAR\", \"field_config\": {\"rentity_id\": \"FIU-US-00123\", \"submission_code\": \"E\", \"currency_code_local\": \"USD\"}}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.report_templates.create(\n name=\"US SAR default\",\n jurisdiction=\"US\",\n report_type=\"SAR\",\n field_config={\"rentity_id\": \"FIU-US-00123\", \"submission_code\": \"E\", \"currency_code_local\": \"USD\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.reportTemplates.create({\n name: \"US SAR default\",\n jurisdiction: \"US\",\n report_type: \"SAR\",\n field_config: { rentity_id: \"FIU-US-00123\", submission_code: \"E\", currency_code_local: \"USD\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.ReportTemplates.Create(ctx, didit.ReportTemplatesCreateParams{\n\tName: \"US SAR default\",\n\tJurisdiction: \"US\",\n\tReportType: \"SAR\",\n\tFieldConfig: didit.Some(map[string]any{\"rentity_id\": \"FIU-US-00123\", \"submission_code\": \"E\", \"currency_code_local\": \"USD\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.ReportTemplatesCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.reportTemplates().create(ReportTemplatesCreateParams.builder()\n .name(\"US SAR default\")\n .jurisdiction(\"US\")\n .reportType(ReportTemplatesCreateParams.ReportType.of(\"SAR\"))\n .fieldConfig(Map.of(\"rentity_id\", \"FIU-US-00123\", \"submission_code\", \"E\", \"currency_code_local\", \"USD\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->create([\n 'name' => 'US SAR default',\n 'jurisdiction' => 'US',\n 'report_type' => 'SAR',\n 'field_config' => ['rentity_id' => 'FIU-US-00123', 'submission_code' => 'E', 'currency_code_local' => 'USD'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.report_templates.create(\n name: \"US SAR default\",\n jurisdiction: \"US\",\n report_type: \"SAR\",\n field_config: { rentity_id: \"FIU-US-00123\", submission_code: \"E\", currency_code_local: \"USD\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.ReportTemplates.CreateAsync(new ReportTemplatesCreateParams\n{\n Name = \"US SAR default\",\n Jurisdiction = \"US\",\n ReportType = \"SAR\",\n FieldConfig = new Dictionary { [\"rentity_id\"] = \"FIU-US-00123\", [\"submission_code\"] = \"E\", [\"currency_code_local\"] = \"USD\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "模板已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } }, "400": { "description": "无法识别的司法管辖区，或 field_config 未通过必填字段验证。", "content": { "application/json": { "schema": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "string" } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/report-templates/{template_uuid}/": { "get": { "summary": "获取报告模板", "description": "获取报告模板。", "operationId": "get_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "template_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7ec00000-0000-4000-8000-000000000006" }, "description": "报告模板 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/7ec00000-0000-4000-8000-000000000006/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.report_templates.retrieve(\n \"7ec00000-0000-4000-8000-000000000006\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.reportTemplates.retrieve(\"7ec00000-0000-4000-8000-000000000006\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.ReportTemplates.Retrieve(ctx, \"7ec00000-0000-4000-8000-000000000006\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.reportTemplates().retrieve(\"7ec00000-0000-4000-8000-000000000006\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->retrieve('7ec00000-0000-4000-8000-000000000006');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.report_templates.retrieve(\"7ec00000-0000-4000-8000-000000000006\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.ReportTemplates.RetrieveAsync(\"7ec00000-0000-4000-8000-000000000006\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "模板详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新报告模板", "description": "部分更新报告模板。保存时会重新验证必填的 goAML 字段。", "operationId": "update_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "template_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7ec00000-0000-4000-8000-000000000006" }, "description": "报告模板 UUID。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 国家/地区代码，保存时转换为大写。" }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "field_config": { "type": "object", "description": "可复用的 goAML 请求头默认值。模板级别的必填字段：rentity_id、submission_code 和 currency_code_local（3 字母）。可选字段：enabled_fields（包含哪些可选报告块）以及 reporting_person、location、reason 和 action 默认值。每次申报的请求头字段（action、submission_date、transactions、jurisdiction）在报告通过核验或定稿时强制要求，而不是在模板上强制要求。" } } }, "example": { "field_config": { "rentity_id": "FIU-US-00124" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/7ec00000-0000-4000-8000-000000000006/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"field_config\": {\"rentity_id\": \"FIU-US-00124\"}}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.report_templates.update(\n \"7ec00000-0000-4000-8000-000000000006\",\n field_config={\"rentity_id\": \"FIU-US-00124\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.reportTemplates.update(\"7ec00000-0000-4000-8000-000000000006\", {\n field_config: { rentity_id: \"FIU-US-00124\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.ReportTemplates.Update(ctx, \"7ec00000-0000-4000-8000-000000000006\", didit.ReportTemplatesUpdateParams{\n\tFieldConfig: didit.Some(map[string]any{\"rentity_id\": \"FIU-US-00124\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.ReportTemplatesUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.reportTemplates().update(\"7ec00000-0000-4000-8000-000000000006\", ReportTemplatesUpdateParams.builder()\n .fieldConfig(Map.of(\"rentity_id\", \"FIU-US-00124\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->update('7ec00000-0000-4000-8000-000000000006', [\n 'field_config' => ['rentity_id' => 'FIU-US-00124'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.report_templates.update(\n \"7ec00000-0000-4000-8000-000000000006\",\n field_config: { rentity_id: \"FIU-US-00124\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.ReportTemplates.UpdateAsync(\"7ec00000-0000-4000-8000-000000000006\", new ReportTemplatesUpdateParams\n{\n FieldConfig = new Dictionary { [\"rentity_id\"] = \"FIU-US-00124\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新模板。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportTemplateDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "删除报告模板", "description": "删除报告模板。已由其创建的报告不受影响。", "operationId": "delete_report_template", "x-didit-sdk": { "resource": "report_templates", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Report Templates" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "template_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "7ec00000-0000-4000-8000-000000000006" }, "description": "报告模板 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/report-templates/7ec00000-0000-4000-8000-000000000006/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.report_templates.delete(\n \"7ec00000-0000-4000-8000-000000000006\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.reportTemplates.delete(\"7ec00000-0000-4000-8000-000000000006\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.ReportTemplates.Delete(ctx, \"7ec00000-0000-4000-8000-000000000006\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.reportTemplates().delete(\"7ec00000-0000-4000-8000-000000000006\");" }, { "lang": "php", "label": "PHP", "source": "reportTemplates->delete('7ec00000-0000-4000-8000-000000000006');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.report_templates.delete(\"7ec00000-0000-4000-8000-000000000006\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.ReportTemplates.DeleteAsync(\"7ec00000-0000-4000-8000-000000000006\");" } ], "responses": { "204": { "description": "模板已删除。" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/regulatory-reports/": { "get": { "summary": "列出案件的报告", "description": "列出为该案件生成的 FIU 报告。", "operationId": "list_case_regulatory_reports", "x-didit-sdk": { "resource": "cases.regulatory_reports", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "页面大小。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "从零开始的偏移量。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.regulatory_reports.list(\n \"c1a5e000-0000-4000-8000-000000000001\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.regulatoryReports.list(\"c1a5e000-0000-4000-8000-000000000001\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.RegulatoryReports.ListAutoPaging(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesRegulatoryReportsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().regulatoryReports().list(\"c1a5e000-0000-4000-8000-000000000001\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->regulatoryReports->list('c1a5e000-0000-4000-8000-000000000001') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.regulatory_reports.list(\"c1a5e000-0000-4000-8000-000000000001\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.RegulatoryReports.ListAsync(\"c1a5e000-0000-4000-8000-000000000001\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "该案件的分页报告列表。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportList" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "从案件创建报告", "description": "为案件创建 FIU 报告草稿：状态为 DRAFT，根据可选模板以及案件的主体、关联交易和叙述自动填充。先验证后定稿，以生成 goAML XML 和 PDF。", "operationId": "create_case_regulatory_report", "x-didit-sdk": { "resource": "cases.regulatory_reports", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "case_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "c1a5e000-0000-4000-8000-000000000001" }, "description": "案件 UUID。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ], "description": "除非提供了模板，否则为必填项；否则使用模板的 report_type。" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "除非提供了模板，否则为必填项。" }, "template": { "type": "string", "format": "uuid", "nullable": true, "description": "报告模板 UUID；在合并案件衍生数据之前，其 field_config 用于初始化草稿。" }, "transactions": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true, "description": "要附加的交易；默认为该案件关联的交易。" }, "rentity_id": { "type": "string", "nullable": true }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ], "default": "E" }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "template": "7ec00000-0000-4000-8000-000000000006" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"template\": \"7ec00000-0000-4000-8000-000000000006\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.regulatory_reports.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n template=\"7ec00000-0000-4000-8000-000000000006\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.regulatoryReports.create(\"c1a5e000-0000-4000-8000-000000000001\", {\n template: \"7ec00000-0000-4000-8000-000000000006\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RegulatoryReports.Create(ctx, \"c1a5e000-0000-4000-8000-000000000001\", didit.CasesRegulatoryReportsCreateParams{\n\tTemplate: didit.String(\"7ec00000-0000-4000-8000-000000000006\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasesRegulatoryReportsCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().regulatoryReports().create(\"c1a5e000-0000-4000-8000-000000000001\", CasesRegulatoryReportsCreateParams.builder()\n .template(\"7ec00000-0000-4000-8000-000000000006\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->regulatoryReports->create('c1a5e000-0000-4000-8000-000000000001', [\n 'template' => '7ec00000-0000-4000-8000-000000000006',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.regulatory_reports.create(\n \"c1a5e000-0000-4000-8000-000000000001\",\n template: \"7ec00000-0000-4000-8000-000000000006\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RegulatoryReports.CreateAsync(\"c1a5e000-0000-4000-8000-000000000001\", new CasesRegulatoryReportsCreateParams\n{\n Template = \"7ec00000-0000-4000-8000-000000000006\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "草稿报告已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "400": { "description": "未找到引用的模板。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/": { "get": { "summary": "列出报告", "description": "应用范围内的 FIU 报告列表，可选择按 status、report_type 或 case 进行过滤。", "operationId": "list_regulatory_reports", "x-didit-sdk": { "resource": "regulatory_reports", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 }, "description": "页面大小。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "从零开始的偏移量。" }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "DRAFT", "VALIDATED", "FINALIZED" ] }, "description": "按状态过滤。" }, { "name": "report_type", "in": "query", "schema": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "description": "按报告类型过滤。" }, { "name": "case", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "过滤此案件下的报告。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.regulatory_reports.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.regulatoryReports.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.RegulatoryReports.ListAutoPaging(ctx, didit.RegulatoryReportsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.regulatoryReports().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.regulatory_reports.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.RegulatoryReports.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "应用中的分页报告。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportList" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建独立报告", "description": "从独立的报告页面创建 FIU 报告草稿：案件和模板均为必填项（与案件范围内的创建不同，后者可以省略模板）。", "operationId": "create_standalone_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "case", "template" ], "properties": { "case": { "type": "string", "format": "uuid" }, "template": { "type": "string", "format": "uuid" }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ], "description": "除非提供了模板，否则为必填项；否则使用模板的 report_type。" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "除非提供了模板，否则为必填项。" }, "transactions": { "type": "array", "items": { "type": "string", "format": "uuid" }, "nullable": true, "description": "要附加的交易；默认为该案件关联的交易。" }, "rentity_id": { "type": "string", "nullable": true }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ], "default": "E" }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "case": "c1a5e000-0000-4000-8000-000000000001", "template": "7ec00000-0000-4000-8000-000000000006" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"case\": \"c1a5e000-0000-4000-8000-000000000001\", \"template\": \"7ec00000-0000-4000-8000-000000000006\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.create(\n case=\"c1a5e000-0000-4000-8000-000000000001\",\n template=\"7ec00000-0000-4000-8000-000000000006\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.create({\n case: \"c1a5e000-0000-4000-8000-000000000001\",\n template: \"7ec00000-0000-4000-8000-000000000006\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Create(ctx, didit.RegulatoryReportsCreateParams{\n\tCase: \"c1a5e000-0000-4000-8000-000000000001\",\n\tTemplate: \"7ec00000-0000-4000-8000-000000000006\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RegulatoryReportsCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().create(RegulatoryReportsCreateParams.builder()\n .case_(\"c1a5e000-0000-4000-8000-000000000001\")\n .template(\"7ec00000-0000-4000-8000-000000000006\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->create([\n 'case' => 'c1a5e000-0000-4000-8000-000000000001',\n 'template' => '7ec00000-0000-4000-8000-000000000006',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.create(\n case: \"c1a5e000-0000-4000-8000-000000000001\",\n template: \"7ec00000-0000-4000-8000-000000000006\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.CreateAsync(new RegulatoryReportsCreateParams\n{\n Case = \"c1a5e000-0000-4000-8000-000000000001\",\n Template = \"7ec00000-0000-4000-8000-000000000006\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "草稿报告已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "400": { "description": "未找到引用的模板。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/": { "get": { "summary": "获取报告", "description": "获取监管报告。", "operationId": "get_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "报告 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.retrieve(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.retrieve(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Retrieve(ctx, \"5ec00000-0000-4000-8000-000000000007\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().retrieve(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->retrieve('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.retrieve(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.RetrieveAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "报告详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新报告", "description": "编辑草稿或已核验报告的字段。已定稿的报告无法编辑（409）。", "operationId": "update_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "报告 UUID。" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2 }, "rentity_id": { "type": "string", "nullable": true }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ], "default": "E" }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } } } }, "example": { "rentity_id": "FIU-US-00123", "currency_code_local": "USD" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"rentity_id\": \"FIU-US-00123\", \"currency_code_local\": \"USD\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.update(\n \"5ec00000-0000-4000-8000-000000000007\",\n rentity_id=\"FIU-US-00123\",\n currency_code_local=\"USD\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.update(\"5ec00000-0000-4000-8000-000000000007\", {\n rentity_id: \"FIU-US-00123\",\n currency_code_local: \"USD\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Update(ctx, \"5ec00000-0000-4000-8000-000000000007\", didit.RegulatoryReportsUpdateParams{\n\tRentityID: didit.String(\"FIU-US-00123\"),\n\tCurrencyCodeLocal: didit.String(\"USD\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RegulatoryReportsUpdateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().update(\"5ec00000-0000-4000-8000-000000000007\", RegulatoryReportsUpdateParams.builder()\n .rentityId(\"FIU-US-00123\")\n .currencyCodeLocal(\"USD\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->update('5ec00000-0000-4000-8000-000000000007', [\n 'rentity_id' => 'FIU-US-00123',\n 'currency_code_local' => 'USD',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.update(\n \"5ec00000-0000-4000-8000-000000000007\",\n rentity_id: \"FIU-US-00123\",\n currency_code_local: \"USD\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.UpdateAsync(\"5ec00000-0000-4000-8000-000000000007\", new RegulatoryReportsUpdateParams\n{\n RentityId = \"FIU-US-00123\",\n CurrencyCodeLocal = \"USD\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已更新报告。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "409": { "description": "报告已定稿。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "删除报告", "description": "永久删除一份监管报告。该报告、其复制的陈述与原因、其交易关联以及生成的 goAML XML 和 PDF 都将被清除，包括这些文件的所有存储版本。该报告将从列表中消失，且下载 URL 将失效。其他记录（包括案件、交易、人员和企业）不会被删除。此操作无法撤销。\n\n删除草稿或已验证状态的报告无需请求体。删除已定稿的报告需要在请求体中提供 `confirm_delete: true`。如果报告不存在，请求返回 `404`；如果未经确认即尝试删除已定稿的报告，将返回 `400` 且不会删除任何内容。", "operationId": "delete_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "报告 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl (draft report)", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "curl", "label": "curl (finalized report)", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"confirm_delete\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.regulatory_reports.delete(\n \"5ec00000-0000-4000-8000-000000000007\",\n confirm_delete=True,\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.regulatoryReports.delete(\"5ec00000-0000-4000-8000-000000000007\", {\n confirm_delete: true,\n});" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RegulatoryReportsDeleteParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.regulatoryReports().delete(\"5ec00000-0000-4000-8000-000000000007\", RegulatoryReportsDeleteParams.builder()\n .confirmDelete(true)\n .build());" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->delete('5ec00000-0000-4000-8000-000000000007', [\n 'confirm_delete' => true,\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.regulatory_reports.delete(\n \"5ec00000-0000-4000-8000-000000000007\",\n confirm_delete: true\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.RegulatoryReports.DeleteAsync(\"5ec00000-0000-4000-8000-000000000007\", new RegulatoryReportsDeleteParams\n{\n ConfirmDelete = true,\n});" } ], "responses": { "204": { "description": "报告已删除，包括其生成的文件。" }, "400": { "description": "发送已定稿报告时未包含 `confirm_delete: true`。未删除任何内容。", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_delete": { "type": "array", "items": { "type": "string" } } } }, "example": { "confirm_delete": [ "This field is required to delete a finalized report." ] } } } }, "403": { "description": "该 API 密钥无法删除报告。该 endpoint 需要 `write:cases` 权限。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "404": { "description": "在此应用中未找到报告。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "409": { "description": "该报告正在删除。请重试请求以完成其文件的清除。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } }, "example": { "detail": "This report is being deleted. Retry deleting it to finish erasing its files.", "code": "report_deletion_pending" } } } }, "503": { "description": "报告文件目前无法清除。该报告仍保留在原处。请重试请求。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string" } } }, "example": { "detail": "The report files could not be erased. Please retry deleting the report.", "code": "report_storage_unavailable" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "description": "仅定稿报告必需。", "content": { "application/json": { "schema": { "type": "object", "properties": { "confirm_delete": { "type": "boolean", "description": "设为 true 以确认永久删除最终报告及其生成的文件。" } }, "example": { "confirm_delete": true } }, "example": { "confirm_delete": true } } } } } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/validate/": { "post": { "summary": "验证报告", "description": "对照强制性的 goAML 请求头字段（申报主体 ID、提交代码、本币、所采取的操作、提交日期），以及至少一笔附加交易和 2 位字母管辖区代码对报告进行核验，且不生成任何文件。同时将结果存储在该报告中：更新 validation_errors 和 validated_at，且未定稿报告的状态将变为 VALIDATED（无错误）或重置回 DRAFT（存在错误）。", "operationId": "validate_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "validate", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "报告 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/validate/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.validate(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.validate(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Validate(ctx, \"5ec00000-0000-4000-8000-000000000007\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().validate(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->validate('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.validate(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.ValidateAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "验证结果。", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "DRAFT", "VALIDATED", "FINALIZED" ] }, "is_valid": { "type": "boolean" }, "errors": { "type": "array", "description": "有效时为空。", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/finalize/": { "post": { "summary": "完成报告", "description": "重新验证，然后生成 goAML XML 和 PDF 并将两者上传至 S3。在 SAR/STR/TFR 报告中，这还会将案件的交易警报从 Pending SAR 移至 SAR filed。", "operationId": "finalize_regulatory_report", "x-didit-sdk": { "resource": "regulatory_reports", "method": "finalize", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "报告 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/finalize/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.finalize(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.finalize(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.Finalize(ctx, \"5ec00000-0000-4000-8000-000000000007\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().finalize_(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->finalize('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.finalize(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.FinalizeAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "报告已定稿；xml_s3_key 和 pdf_s3_key 已设置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "400": { "description": "报告验证失败。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } } } } } }, "409": { "description": "报告未处于可定稿状态。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/download-url/": { "get": { "summary": "获取报告下载 URL", "description": "为已定稿报告的 goAML XML 或 PDF 生成预签名 URL。", "operationId": "get_regulatory_report_download_url", "x-didit-sdk": { "resource": "regulatory_reports", "method": "retrieve_download_url", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Regulatory Reports" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "report_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "5ec00000-0000-4000-8000-000000000007" }, "description": "报告 UUID。" }, { "name": "file", "in": "query", "schema": { "type": "string", "enum": [ "pdf", "xml" ], "default": "pdf" }, "description": "要下载哪个文件。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/regulatory-reports/5ec00000-0000-4000-8000-000000000007/download-url/?file=xml' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.regulatory_reports.retrieve_download_url(\n \"5ec00000-0000-4000-8000-000000000007\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.regulatoryReports.retrieveDownloadUrl(\"5ec00000-0000-4000-8000-000000000007\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.RegulatoryReports.RetrieveDownloadURL(ctx, \"5ec00000-0000-4000-8000-000000000007\", didit.RegulatoryReportsRetrieveDownloadURLParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.regulatoryReports().retrieveDownloadUrl(\"5ec00000-0000-4000-8000-000000000007\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "regulatoryReports->retrieveDownloadUrl('5ec00000-0000-4000-8000-000000000007');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.regulatory_reports.retrieve_download_url(\"5ec00000-0000-4000-8000-000000000007\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.RegulatoryReports.RetrieveDownloadUrlAsync(\"5ec00000-0000-4000-8000-000000000007\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "预签名下载 URL。", "content": { "application/json": { "schema": { "type": "object", "properties": { "download_url": { "type": "string", "format": "uri" }, "file": { "type": "string", "enum": [ "pdf", "xml" ] } } } } } }, "409": { "description": "报告尚未定稿。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "status": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/rules/": { "get": { "summary": "列出规则", "description": "列出该应用的交易监控规则：包括您的自定义规则以及您已安装的任何规则库预设。可按 source、category、mode、bundle 或自由文本搜索进行过滤；使用 `ordering` 进行排序（run_count、approved_pct、reviewed_pct、declined_pct、latest_triggered_at、title、created_at、source，均可带有可选的前缀 `-`）。", "operationId": "listTransactionRules", "x-didit-sdk": { "resource": "transactions.rules", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "source", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "PRESET", "CUSTOM" ] }, "description": "PRESET 或 CUSTOM" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "按规则分类过滤" }, { "name": "mode", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ] }, "description": "ACTIVE、DISABLED 或 TEST" }, { "name": "bundle", "in": "query", "required": false, "schema": { "type": "string" }, "description": "按捆绑包过滤预设" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "针对标题和描述进行不区分大小写的匹配" }, { "name": "ordering", "in": "query", "required": false, "schema": { "type": "string" }, "description": "逗号分隔的排序字段，默认为 source,-run_count" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "页面大小" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "页面偏移量" } ], "responses": { "200": { "description": "分页规则列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/rules/?source=CUSTOM&ordering=-run_count' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.rules.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.rules.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Rules.ListAutoPaging(ctx, didit.TransactionsRulesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().rules().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.rules.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.Rules.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "创建规则", "description": "创建 CUSTOM 交易监控规则。每个应用的标题必须唯一（重复将返回 400）。针对 `AWAITING_USER` 的 `change_status` 操作必须携带 `workflow_id`。在 ACTIVE 模式下创建的规则会立即应用于新交易。推荐的工作流是先在 TEST 模式下创建并回测，然后再将模式切换为 ACTIVE。要修改库规则，请以副本形式创建：发送库规则的定义，并附带 `metadata.based_on`（其库键）和 `metadata.based_on_rule_uuid`。", "operationId": "createTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleCreateRequest" }, "example": { "title": "Structuring - inbound (custom)", "description": "20+ inbound EUR transfers, all under 10,000 EUR, 30 days", "category": "finance", "mode": "TEST", "evaluation_mode": "ALL", "scope": { "transaction_types": [ "finance" ], "directions": [ "INBOUND" ] }, "conditions": [ { "field": "currency", "operator": "eq", "value": "EUR" }, { "field": "amount", "operator": "lt", "value": 10000 } ], "aggregation": [ { "metric": "count", "operator": "gte", "value": 20, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } }, { "metric": "max", "field": "amount", "operator": "lt", "value": 10000, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } } ], "actions": [ { "type": "add_score", "value": 35 } ] } } } }, "responses": { "201": { "description": "已创建的规则。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } }, "400": { "description": "验证错误 - 标题重复、未知的运算符/指标、时间窗口格式错误、无效的作用域方向，或包含 AWAITING_USER 却缺少 workflow_id。", "content": { "application/json": { "schema": { "type": "object" }, "example": { "title": [ "A rule with this name already exists." ] } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/rules/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"title\": \"Structuring - inbound (custom)\", \"description\": \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\", \"category\": \"finance\", \"mode\": \"TEST\", \"evaluation_mode\": \"ALL\", \"scope\": {\"transaction_types\": [\"finance\"], \"directions\": [\"INBOUND\"]}, \"conditions\": [{\"field\": \"currency\", \"operator\": \"eq\", \"value\": \"EUR\"}, {\"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000}], \"aggregation\": [{\"metric\": \"count\", \"operator\": \"gte\", \"value\": 20, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}, {\"metric\": \"max\", \"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}], \"actions\": [{\"type\": \"add_score\", \"value\": 35}]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.create(\n title=\"Structuring - inbound (custom)\",\n description=\"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n category=\"finance\",\n mode=\"TEST\",\n evaluation_mode=\"ALL\",\n scope={\n \"transaction_types\": [\"finance\"],\n \"directions\": [\"INBOUND\"],\n },\n conditions=[{\n \"field\": \"currency\",\n \"operator\": \"eq\",\n \"value\": \"EUR\",\n }, {\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000,\n }],\n aggregation=[{\n \"metric\": \"count\",\n \"operator\": \"gte\",\n \"value\": 20.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }, {\n \"metric\": \"max\",\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }],\n actions=[{\n \"type\": \"add_score\",\n \"value\": 35,\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.create({\n title: \"Structuring - inbound (custom)\",\n description: \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n category: \"finance\",\n mode: \"TEST\",\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n actions: [{\n type: \"add_score\",\n value: 35,\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Create(ctx, didit.TransactionRuleCreateRequest{\n\tTitle: \"Structuring - inbound (custom)\",\n\tDescription: didit.String(\"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\"),\n\tCategory: \"finance\",\n\tMode: \"TEST\",\n\tEvaluationMode: didit.Some(didit.TransactionRuleCreateRequestEvaluationMode(\"ALL\")),\n\tScope: didit.Some(didit.TransactionRuleScopeParam{\n\t\tTransactionTypes: didit.Some([]string{\"finance\"}),\n\t\tDirections: didit.Some([]didit.TransactionRuleScopeDirections{\"INBOUND\"}),\n\t}),\n\tConditions: didit.Some([]didit.TransactionRuleConditionParam{{\n\t\tField: \"currency\",\n\t\tOperator: \"eq\",\n\t\tValue: didit.Some[any](\"EUR\"),\n\t}, {\n\t\tField: \"amount\",\n\t\tOperator: \"lt\",\n\t\tValue: didit.Some[any](10000),\n\t}}),\n\tAggregation: didit.Some([]didit.TransactionRuleAggregationParam{{\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"count\")),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"gte\")),\n\t\tValue: 20.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}, {\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"max\")),\n\t\tField: didit.String(\"amount\"),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"lt\")),\n\t\tValue: 10000.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}}),\n\tActions: didit.Some([]didit.TransactionRuleActionParam{{\n\t\tType: \"add_score\",\n\t\tValue: didit.Some[any](35),\n\t}}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.TransactionRuleAction;\nimport me.didit.types.TransactionRuleActionAddScore;\nimport me.didit.types.TransactionRuleAggregation;\nimport me.didit.types.TransactionRuleCondition;\nimport me.didit.types.TransactionRuleCreateRequest;\nimport me.didit.types.TransactionRuleScope;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().create(TransactionRuleCreateRequest.builder()\n .title(\"Structuring - inbound (custom)\")\n .description(\"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\")\n .category(\"finance\")\n .mode(TransactionRuleCreateRequest.Mode.of(\"TEST\"))\n .evaluationMode(TransactionRuleCreateRequest.EvaluationMode.of(\"ALL\"))\n .scope(TransactionRuleScope.builder()\n .transactionTypes(List.of(\"finance\"))\n .directions(List.of(TransactionRuleScope.Directions.of(\"INBOUND\")))\n .build())\n .conditions(List.of(\n TransactionRuleCondition.builder()\n .field(\"currency\")\n .operator(TransactionRuleCondition.Operator.of(\"eq\"))\n .value(\"EUR\")\n .build(),\n TransactionRuleCondition.builder()\n .field(\"amount\")\n .operator(TransactionRuleCondition.Operator.of(\"lt\"))\n .value(10000)\n .build()))\n .aggregation(List.of(\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"count\"))\n .operator(TransactionRuleAggregation.Operator.of(\"gte\"))\n .value(20.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build(),\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"max\"))\n .field(\"amount\")\n .operator(TransactionRuleAggregation.Operator.of(\"lt\"))\n .value(10000.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build()))\n .actions(List.of(TransactionRuleAction.ofAddScore(TransactionRuleActionAddScore.builder()\n .type(TransactionRuleActionAddScore.Type.of(\"add_score\"))\n .value(35L)\n .build())))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->create([\n 'title' => 'Structuring - inbound (custom)',\n 'description' => '20+ inbound EUR transfers, all under 10,000 EUR, 30 days',\n 'category' => 'finance',\n 'mode' => 'TEST',\n 'evaluation_mode' => 'ALL',\n 'scope' => [\n 'transaction_types' => ['finance'],\n 'directions' => ['INBOUND'],\n ],\n 'conditions' => [[\n 'field' => 'currency',\n 'operator' => 'eq',\n 'value' => 'EUR',\n ], [\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000,\n ]],\n 'aggregation' => [[\n 'metric' => 'count',\n 'operator' => 'gte',\n 'value' => 20.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ], [\n 'metric' => 'max',\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ]],\n 'actions' => [[\n 'type' => 'add_score',\n 'value' => 35,\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.create(\n title: \"Structuring - inbound (custom)\",\n description: \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n category: \"finance\",\n mode: \"TEST\",\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n actions: [{\n type: \"add_score\",\n value: 35,\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.CreateAsync(new TransactionRuleCreateRequest\n{\n Title = \"Structuring - inbound (custom)\",\n Description = \"20+ inbound EUR transfers, all under 10,000 EUR, 30 days\",\n Category = \"finance\",\n Mode = \"TEST\",\n EvaluationMode = new TransactionRuleCreateRequestEvaluationMode(\"ALL\"),\n Scope = new TransactionRuleScope\n {\n TransactionTypes = new string[] { \"finance\" },\n Directions = new TransactionRuleScopeDirections[] { \"INBOUND\" },\n },\n Conditions = new TransactionRuleCondition[]\n {\n new()\n {\n Field = \"currency\",\n Operator = \"eq\",\n Value = \"EUR\",\n },\n new()\n {\n Field = \"amount\",\n Operator = \"lt\",\n Value = 10000,\n },\n },\n Aggregation = new TransactionRuleAggregation[]\n {\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"count\"),\n Operator = new TransactionRuleAggregationOperator(\"gte\"),\n Value = 20.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"max\"),\n Field = \"amount\",\n Operator = new TransactionRuleAggregationOperator(\"lt\"),\n Value = 10000.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n },\n Actions = new TransactionRuleAction[]\n {\n new()\n {\n Type = new TransactionRuleActionType(\"add_score\"),\n Value = 35,\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/transactions/rules/{rule_uuid}/": { "parameters": [ { "name": "rule_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "来自列表或创建操作的规则 uuid。" } ], "get": { "summary": "获取规则", "description": "获取单个规则及其完整配置和执行计数器。", "operationId": "getTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "规则。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } }, "404": { "description": "此应用中不存在该规则。", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "更新规则", "description": "部分更新规则。自定义规则接受所有配置字段。库（PRESET）规则仅接受 `mode`：用于激活、禁用或将预设切换为 TEST；任何其他字段均会返回 400，因为 Didit 负责维护库规则并自动应用其更新。若要更改库规则的条件，请使用该库规则的定义以及 `metadata.based_on`（库键名）和 `metadata.based_on_rule_uuid`，通过 `POST /v3/transactions/rules/` 创建自定义副本，然后将库规则切换为 `mode: DISABLED` 关闭，以避免同一交易触发两次警报。暂缓发布的库规则的已安装副本处于关闭状态：将其 `mode` 设置为除 `DISABLED` 以外的任何值均会返回 400（\"This library rule cannot run yet: its conditions read data the rules engine cannot evaluate.\"）。", "operationId": "updateTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleUpdateRequest" }, "example": { "mode": "ACTIVE" } } } }, "responses": { "200": { "description": "已更新的规则。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleDetail" } } } }, "400": { "description": "验证错误，库规则上存在非 mode 字段，或者扣留的库规则上 mode 不为 DISABLED。", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"mode\": \"ACTIVE\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n mode=\"ACTIVE\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.update(\"11111111-2222-3333-4444-555555555555\", {\n mode: \"ACTIVE\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TransactionRuleUpdateRequest{\n\tMode: didit.Some(didit.TransactionRuleUpdateRequestMode(\"ACTIVE\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionRuleUpdateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().update(\"11111111-2222-3333-4444-555555555555\", TransactionRuleUpdateRequest.builder()\n .mode(TransactionRuleUpdateRequest.Mode.of(\"ACTIVE\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->update('11111111-2222-3333-4444-555555555555', [\n 'mode' => 'ACTIVE',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n mode: \"ACTIVE\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new TransactionRuleUpdateRequest\n{\n Mode = new TransactionRuleUpdateRequestMode(\"ACTIVE\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "删除规则", "description": "删除一条 CUSTOM 规则。删除会立即且永久生效：该规则将停止对新交易进行评估，并不再显示在列表中，而已评估交易的历史规则运行记录仍将保留。库规则无法删除，请改用安装 endpoint 卸载它们（它们始终可以从库中重新安装）。", "operationId": "deleteTransactionRule", "x-didit-sdk": { "resource": "transactions.rules", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "204": { "description": "已删除。" }, "400": { "description": "该规则是库中的预设规则 - 请改为卸载。", "content": { "application/json": { "schema": { "type": "object" }, "example": { "detail": "Library rules cannot be deleted. Uninstall them via the rules install endpoint instead." } } } }, "404": { "description": "此应用中不存在该规则。", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.transactions.rules.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.transactions.rules.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Transactions.Rules.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.transactions().rules().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.rules.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Transactions.Rules.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ] } }, "/v3/transactions/rules/backtest/": { "post": { "summary": "回测规则配置", "description": "在不创建规则或更改任何交易的情况下，对照您最近的交易（按最新优先排序，直至达到回测上限）评估假设的规则配置。在激活规则之前使用它，可查看该规则可能匹配的频率以及会影响多少主体。", "operationId": "backtestTransactionRules", "x-didit-sdk": { "resource": "transactions.rules", "method": "backtest", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleBacktestRequest" }, "example": { "conditions": [ { "field": "currency", "operator": "eq", "value": "EUR" }, { "field": "amount", "operator": "lt", "value": 10000 } ], "aggregation": [ { "metric": "count", "operator": "gte", "value": 20, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } }, { "metric": "max", "field": "amount", "operator": "lt", "value": 10000, "window": "30d", "filters": { "direction": "INBOUND", "transaction_type": "finance", "subject_vendor_data": "__current__", "currency": "EUR" } } ], "evaluation_mode": "ALL", "scope": { "transaction_types": [ "finance" ], "directions": [ "INBOUND" ] }, "period_days": 90 } } } }, "responses": { "200": { "description": "回测统计数据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleBacktestResult" }, "example": { "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/rules/backtest/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"conditions\": [{\"field\": \"currency\", \"operator\": \"eq\", \"value\": \"EUR\"}, {\"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000}], \"aggregation\": [{\"metric\": \"count\", \"operator\": \"gte\", \"value\": 20, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}, {\"metric\": \"max\", \"field\": \"amount\", \"operator\": \"lt\", \"value\": 10000, \"window\": \"30d\", \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}}], \"evaluation_mode\": \"ALL\", \"scope\": {\"transaction_types\": [\"finance\"], \"directions\": [\"INBOUND\"]}, \"period_days\": 90}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.backtest(\n conditions=[{\n \"field\": \"currency\",\n \"operator\": \"eq\",\n \"value\": \"EUR\",\n }, {\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000,\n }],\n aggregation=[{\n \"metric\": \"count\",\n \"operator\": \"gte\",\n \"value\": 20.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }, {\n \"metric\": \"max\",\n \"field\": \"amount\",\n \"operator\": \"lt\",\n \"value\": 10000.0,\n \"window\": \"30d\",\n \"filters\": {\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"},\n }],\n evaluation_mode=\"ALL\",\n scope={\n \"transaction_types\": [\"finance\"],\n \"directions\": [\"INBOUND\"],\n },\n period_days=90,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.backtest({\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n period_days: 90,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.Backtest(ctx, didit.TransactionRuleBacktestRequest{\n\tConditions: didit.Some([]didit.TransactionRuleConditionParam{{\n\t\tField: \"currency\",\n\t\tOperator: \"eq\",\n\t\tValue: didit.Some[any](\"EUR\"),\n\t}, {\n\t\tField: \"amount\",\n\t\tOperator: \"lt\",\n\t\tValue: didit.Some[any](10000),\n\t}}),\n\tAggregation: didit.Some([]didit.TransactionRuleAggregationParam{{\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"count\")),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"gte\")),\n\t\tValue: 20.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}, {\n\t\tMetric: didit.Some(didit.TransactionRuleAggregationMetric(\"max\")),\n\t\tField: didit.String(\"amount\"),\n\t\tOperator: didit.Some(didit.TransactionRuleAggregationOperator(\"lt\")),\n\t\tValue: 10000.0,\n\t\tWindow: didit.String(\"30d\"),\n\t\tFilters: didit.Some(map[string]any{\"direction\": \"INBOUND\", \"transaction_type\": \"finance\", \"subject_vendor_data\": \"__current__\", \"currency\": \"EUR\"}),\n\t}}),\n\tEvaluationMode: didit.Some(didit.TransactionRuleBacktestRequestEvaluationMode(\"ALL\")),\n\tScope: didit.Some(didit.TransactionRuleScopeParam{\n\t\tTransactionTypes: didit.Some([]string{\"finance\"}),\n\t\tDirections: didit.Some([]didit.TransactionRuleScopeDirections{\"INBOUND\"}),\n\t}),\n\tPeriodDays: didit.Int(90),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.TransactionRuleAggregation;\nimport me.didit.types.TransactionRuleBacktestRequest;\nimport me.didit.types.TransactionRuleCondition;\nimport me.didit.types.TransactionRuleScope;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().backtest(TransactionRuleBacktestRequest.builder()\n .conditions(List.of(\n TransactionRuleCondition.builder()\n .field(\"currency\")\n .operator(TransactionRuleCondition.Operator.of(\"eq\"))\n .value(\"EUR\")\n .build(),\n TransactionRuleCondition.builder()\n .field(\"amount\")\n .operator(TransactionRuleCondition.Operator.of(\"lt\"))\n .value(10000)\n .build()))\n .aggregation(List.of(\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"count\"))\n .operator(TransactionRuleAggregation.Operator.of(\"gte\"))\n .value(20.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build(),\n TransactionRuleAggregation.builder()\n .metric(TransactionRuleAggregation.Metric.of(\"max\"))\n .field(\"amount\")\n .operator(TransactionRuleAggregation.Operator.of(\"lt\"))\n .value(10000.0)\n .window(\"30d\")\n .filters(Map.of(\"direction\", \"INBOUND\", \"transaction_type\", \"finance\", \"subject_vendor_data\", \"__current__\", \"currency\", \"EUR\"))\n .build()))\n .evaluationMode(TransactionRuleBacktestRequest.EvaluationMode.of(\"ALL\"))\n .scope(TransactionRuleScope.builder()\n .transactionTypes(List.of(\"finance\"))\n .directions(List.of(TransactionRuleScope.Directions.of(\"INBOUND\")))\n .build())\n .periodDays(90L)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->backtest([\n 'conditions' => [[\n 'field' => 'currency',\n 'operator' => 'eq',\n 'value' => 'EUR',\n ], [\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000,\n ]],\n 'aggregation' => [[\n 'metric' => 'count',\n 'operator' => 'gte',\n 'value' => 20.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ], [\n 'metric' => 'max',\n 'field' => 'amount',\n 'operator' => 'lt',\n 'value' => 10000.0,\n 'window' => '30d',\n 'filters' => ['direction' => 'INBOUND', 'transaction_type' => 'finance', 'subject_vendor_data' => '__current__', 'currency' => 'EUR'],\n ]],\n 'evaluation_mode' => 'ALL',\n 'scope' => [\n 'transaction_types' => ['finance'],\n 'directions' => ['INBOUND'],\n ],\n 'period_days' => 90,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.backtest(\n conditions: [{\n field: \"currency\",\n operator: \"eq\",\n value: \"EUR\",\n }, {\n field: \"amount\",\n operator: \"lt\",\n value: 10000,\n }],\n aggregation: [{\n metric: \"count\",\n operator: \"gte\",\n value: 20.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }, {\n metric: \"max\",\n field: \"amount\",\n operator: \"lt\",\n value: 10000.0,\n window: \"30d\",\n filters: { direction: \"INBOUND\", transaction_type: \"finance\", subject_vendor_data: \"__current__\", currency: \"EUR\" },\n }],\n evaluation_mode: \"ALL\",\n scope: {\n transaction_types: [\"finance\"],\n directions: [\"INBOUND\"],\n },\n period_days: 90\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.BacktestAsync(new TransactionRuleBacktestRequest\n{\n Conditions = new TransactionRuleCondition[]\n {\n new()\n {\n Field = \"currency\",\n Operator = \"eq\",\n Value = \"EUR\",\n },\n new()\n {\n Field = \"amount\",\n Operator = \"lt\",\n Value = 10000,\n },\n },\n Aggregation = new TransactionRuleAggregation[]\n {\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"count\"),\n Operator = new TransactionRuleAggregationOperator(\"gte\"),\n Value = 20.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n new()\n {\n Metric = new TransactionRuleAggregationMetric(\"max\"),\n Field = \"amount\",\n Operator = new TransactionRuleAggregationOperator(\"lt\"),\n Value = 10000.0,\n Window = \"30d\",\n Filters = new Dictionary { [\"direction\"] = \"INBOUND\", [\"transaction_type\"] = \"finance\", [\"subject_vendor_data\"] = \"__current__\", [\"currency\"] = \"EUR\" },\n },\n },\n EvaluationMode = new TransactionRuleBacktestRequestEvaluationMode(\"ALL\"),\n Scope = new TransactionRuleScope\n {\n TransactionTypes = new string[] { \"finance\" },\n Directions = new TransactionRuleScopeDirections[] { \"INBOUND\" },\n },\n PeriodDays = 90,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/transactions/rules/library/": { "get": { "summary": "列出规则库", "description": "浏览完整的预设规则库（150+ 条规则），包含每个条目的完整配置以及针对此应用的 `is_installed` 标志。可按规则包、类别或自由文本搜索进行过滤。如果规则库中某条规则的条件所读取的数据规则引擎尚无法评估，则该规则会暂不提供，直到可以运行为止。暂不提供的规则不会列出。", "operationId": "listTransactionRuleLibrary", "x-didit-sdk": { "resource": "transactions.rules", "method": "list_library", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "bundle", "in": "query", "required": false, "schema": { "type": "string" }, "description": "按 bundle 过滤，例如 finance、aml_ctf、crypto_monitoring、travel_rule" }, { "name": "category", "in": "query", "required": false, "schema": { "type": "string" }, "description": "按分类过滤" }, { "name": "search", "in": "query", "required": false, "schema": { "type": "string" }, "description": "针对标题和描述进行不区分大小写的匹配" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "页面大小" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "页面偏移量" } ], "responses": { "200": { "description": "分页库条目。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleLibraryEntry" } } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/rules/library/?bundle=finance' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.rules.list_library():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.rules.listLibrary()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Rules.ListLibraryAutoPaging(ctx, didit.TransactionsRulesListLibraryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().rules().listLibrary()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->listLibrary() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.rules.list_library.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.Rules.ListLibraryAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/transactions/rules/install/": { "post": { "summary": "安装规则库规则", "description": "通过 `library_keys` 或整个 `bundle` 将一个或多个预设安装到应用中。安装的预设在交易监控开启时立即可用，否则保持停用状态；已安装的 key 会被跳过。若某条规则库规则的条件读取了规则引擎尚无法评估的数据，则该规则会被暂缓，直至其可以运行。在 `library_keys` 中指定此类规则的请求将返回 400 且不安装任何内容（“这些规则库规则暂时无法运行：其条件读取了规则引擎无法评估的数据。”后跟对应 key），而通过 `bundle` 安装则会跳过该规则。一旦暂缓规则的条件可以被评估，它将自动恢复生效。不在规则库中的 `library_keys` 条目会被跳过，而不是被拒绝。", "operationId": "installTransactionRuleLibrary", "x-didit-sdk": { "resource": "transactions.rules", "method": "install_library", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallRequest" }, "example": { "library_keys": [ "structuring-inbound", "structuring-outbound" ] } } } }, "responses": { "200": { "description": "已安装的内容。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallResult" }, "example": { "installed_library_keys": [ "structuring-inbound", "structuring-outbound" ], "installed_count": 2 } } } }, "400": { "description": "既未提供 library_keys 也未提供 bundle，`library_keys` 不是列表，或某个 `library_keys` 条目被扣留。未知的条目将被跳过并在不包含它的情况下返回 200。", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/rules/install/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"library_keys\": [\"structuring-inbound\", \"structuring-outbound\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.install_library(\n library_keys=[\"structuring-inbound\", \"structuring-outbound\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.installLibrary({\n library_keys: [\"structuring-inbound\", \"structuring-outbound\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.InstallLibrary(ctx, didit.TransactionRuleInstallRequest{\n\tLibraryKeys: didit.Some([]string{\"structuring-inbound\", \"structuring-outbound\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TransactionRuleInstallRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().installLibrary(TransactionRuleInstallRequest.builder()\n .libraryKeys(List.of(\"structuring-inbound\", \"structuring-outbound\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->installLibrary([\n 'library_keys' => ['structuring-inbound', 'structuring-outbound'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.install_library(library_keys: [\"structuring-inbound\", \"structuring-outbound\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.InstallLibraryAsync(new TransactionRuleInstallRequest\n{\n LibraryKeys = new string[] { \"structuring-inbound\", \"structuring-outbound\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "卸载规则库规则", "description": "通过 `library_keys` 或整个 `bundle` 从应用中移除已安装的预设。卸载的预设会立即停止评估，并可随时从库中重新安装。", "operationId": "uninstallTransactionRuleLibrary", "x-didit-sdk": { "resource": "transactions.rules", "method": "uninstall_library", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallRequest" }, "example": { "bundle": "responsible_gaming" } } } }, "responses": { "200": { "description": "移除的预设数量。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleInstallResult" }, "example": { "uninstalled_count": 5 } } } }, "400": { "description": "既未提供 library_keys 也未提供 bundle。", "content": { "application/json": { "schema": { "type": "object" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/transactions/rules/install/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"bundle\": \"responsible_gaming\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.rules.uninstall_library(\n bundle=\"responsible_gaming\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.rules.uninstallLibrary({\n bundle: \"responsible_gaming\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Rules.UninstallLibrary(ctx, didit.TransactionRuleInstallRequest{\n\tBundle: didit.String(\"responsible_gaming\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TransactionRuleInstallRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().rules().uninstallLibrary(TransactionRuleInstallRequest.builder()\n .bundle(\"responsible_gaming\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->rules->uninstallLibrary([\n 'bundle' => 'responsible_gaming',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.rules.uninstall_library(bundle: \"responsible_gaming\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Rules.UninstallLibraryAsync(new TransactionRuleInstallRequest\n{\n Bundle = \"responsible_gaming\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/": { "get": { "summary": "列出网络", "description": "列出此应用所属组织内检测到的欺诈网络，默认按最高风险优先排序。默认情况下排除已忽略的网络；传入 status 可包含它们。沙盒应用绝不会有网络：聚类会完全排除沙盒数据。每个响应都包含组织的 `sharing_mode` 以及跨组织信号是否适用于它（`cross_org_available`、`cross_org_unavailable_reason`）。`kpis` 聚合与您的过滤条件匹配的网络，`counts` 聚合该应用可见的所有网络；当您只需要分页数据时，传入 `summary=false` 可跳过这两者。需要具有完全访问权限的 API 密钥，或者控制台成员具备 `list:networks` 权限。", "operationId": "list_networks", "x-didit-sdk": { "resource": "networks", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "status", "in": "query", "schema": { "type": "string" }, "description": "要包含的逗号分隔的状态：active,in_review,resolved,dismissed。省略此参数以排除 dismissed。" }, { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "identity", "transactions" ] }, "description": "`transactions` 保留成员均为交易参与方的网络；`identity` 保留所有其他网络。省略则同时包含两者。它还会缩小 `counts.views` 和 `counts.facets` 的范围。传入任何其他值均返回 400。" }, { "name": "signal_type", "in": "query", "schema": { "type": "string" }, "description": "逗号分隔的信号类型：ip_address,device,face,document_number,phone,email,address。" }, { "name": "pattern_type", "in": "query", "schema": { "type": "string" }, "description": "逗号分隔的模式类型，例如 exact_same_device,same_email。" }, { "name": "risk_band", "in": "query", "schema": { "type": "string" }, "description": "以逗号分隔的区间：low、medium、high。" }, { "name": "min_size", "in": "query", "schema": { "type": "integer" }, "description": "最少成员数。" }, { "name": "max_size", "in": "query", "schema": { "type": "integer" }, "description": "成员数量上限。" }, { "name": "assignee", "in": "query", "schema": { "type": "string" }, "description": "逗号分隔的指派人：`unassigned`、成员邮箱（不区分大小写匹配），或 `me`（代表发起调用的控制台成员）。网络可以匹配任何值。`me` 需要控制台成员 token：使用 API 密钥将返回 400 `{\"assignee\": [\"\\\"me\\\" needs a user token; an API key has no assignee identity.\"]}`。" }, { "name": "priority", "in": "query", "schema": { "type": "string" }, "description": "逗号分隔的优先级：`low`、`medium`、`high`，或针对没有优先级的网络的 `none`。任何其他值都会返回 400 `{\"priority\": \"Unknown priority: .\"}`。" }, { "name": "risk_min", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 100 }, "description": "最低风险评分，介于 0 到 100 之间的整数。非整数值将返回 400 `{\"risk_min\": \"Use a whole number from 0 to 100.\"}`。" }, { "name": "has_case", "in": "query", "schema": { "type": "boolean" }, "description": "`true` 保留您的应用为其开启案件的网络，`false` 保留其他网络。任何其他值将被忽略。" }, { "name": "date_from", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "last_activity_at 的下限（ISO 8601 日期或日期时间）。" }, { "name": "date_to", "in": "query", "schema": { "type": "string", "format": "date" }, "description": "first_activity_at 的上限（ISO 8601 日期或日期时间）。" }, { "name": "q", "in": "query", "schema": { "type": "string" }, "description": "跨网络名称、成员名称、network_id (N-0001) 以及精确 pattern_type token 的自由文本搜索。" }, { "name": "ordering", "in": "query", "schema": { "type": "string" }, "description": "risk_score、-risk_score、last_activity_at、-last_activity_at、first_activity_at、-first_activity_at、network_number、-network_number 之一。默认值为 -risk_score,-last_activity_at。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 500 }, "description": "页面大小，1-500。默认为 100。" }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 }, "description": "第一条记录的从零开始的偏移量。" }, { "name": "summary", "in": "query", "schema": { "type": "boolean", "default": true }, "description": "`false` 仅返回页面及其 `count`，不包含 `kpis` 和 `counts`。默认为 `true`。除 `true` 或 `false` 之外的任何值均返回 400。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/?status=active,in_review&ordering=-risk_score' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.networks.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.networks.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Networks.ListAutoPaging(ctx, didit.NetworksListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.networks().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "networks->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.networks.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Networks.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页网络列表，包含组织的共享模式和跨组织可用性，除非 `summary=false`，否则还包括 `kpis` 和 `counts`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "integer", "nullable": true, "description": "下一页的偏移量，如果是最后一页则为 null。" }, "previous": { "type": "integer", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkListItem" } }, "kpis": { "type": "object", "description": "每个键对应符合当前过滤器的结果中的 {value, delta}。当 `summary=false` 时省略。", "properties": { "active": { "type": "object" }, "in_review": { "type": "object" }, "applicants_involved": { "type": "object" }, "detected_this_period": { "type": "object" }, "false_positive_rate": { "type": "object" } } }, "counts": { "$ref": "#/components/schemas/NetworkListCounts" }, "sharing_mode": { "type": "string", "enum": [ "off", "private", "global" ], "description": "该组织的跨组织共享模式。仅 `global` 会跨组织比对网络；`private` 和 `off` 则仅保留在组织自身历史记录内。", "example": "global" }, "cross_org_available": { "type": "boolean", "description": "跨组织信号是否适用于该组织。这需要同时具备 Enterprise 套餐和 `global` 共享模式。", "example": true }, "cross_org_unavailable_reason": { "type": "string", "enum": [ "plan", "sharing_mode" ], "nullable": true, "description": "跨组织信号不适用的原因，按此顺序检查。`plan`：无论共享模式为何，组织的套餐均不包含跨组织欺诈网络（需要 Enterprise 套餐）。`sharing_mode`：套餐包含该功能，但共享模式为 `private` 或 `off`。当 `cross_org_available` 为 `true` 时为 Null。", "example": null } }, "required": [ "count", "next", "previous", "results", "sharing_mode", "cross_org_available", "cross_org_unavailable_reason" ] } } } }, "400": { "description": "无效的过滤器、排序、分页或 `summary` 值。", "content": { "application/json": { "examples": { "Invalid summary": { "summary": "无效的摘要", "value": { "summary": [ "Must be \"true\" or \"false\"." ] } }, "Invalid scope": { "summary": "无效的作用域", "value": { "scope": [ "Use identity or transactions." ] } }, "Unsupported ordering": { "summary": "不支持的排序方式", "value": [ "Unsupported ordering." ] } } } } }, "401": { "description": "凭据缺失或无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Missing or invalid credentials": { "summary": "凭据缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "API 密钥属于另一个应用，或者是一个访问权限受限的密钥：Networks endpoint 需要具有完全访问权限的密钥。控制台成员 token 需要 `list:networks` 权限。若组织未启用 Networks，也会返回 `code: networks_not_entitled`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Networks not enabled": { "summary": "网络未启用", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "受限的 API 密钥", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "无权限", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/": { "get": { "summary": "获取网络", "description": "获取单个网络的完整详情：统计信息、欺诈标签和风险信号，以及组织的 `sharing_mode` 和跨组织可用性、您的应用在网络上的 `tags`、成员 `outcomes` 和模式评分（`patterns`）。需要完全访问权限的 API 密钥，或者控制台成员需具备 `read:networks` 权限。", "operationId": "get_network", "x-didit-sdk": { "resource": "networks", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "网络 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieve(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.Retrieve(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieve(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieve('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "网络详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [ { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "SUSPICIOUS", "color": "#6366F1", "source": "custom", "added_by": null, "added_at": "2026-10-13T08:15:00Z" } ], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "404": { "description": "未找到网络（或对当前应用不可见）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "401": { "description": "凭据缺失或无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Missing or invalid credentials": { "summary": "凭据缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "API 密钥属于另一个应用，或者是一个访问权限受限的密钥：Networks endpoint 需要具有完全访问权限的密钥。控制台成员 token 需要 `read:networks` 权限。若组织未启用 Networks，也会返回 `code: networks_not_entitled`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Networks not enabled": { "summary": "网络未启用", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "受限的 API 密钥", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "无权限", "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/graph/": { "get": { "summary": "获取网络图谱", "description": "将网络作为由主体节点（服务商用户、服务商企业、交易各方）和信号节点（关联它们的共享设备/IP/人脸/证件/电话/邮箱/地址值）组成的图谱进行获取，边表示从属关系。", "operationId": "get_network_graph", "x-didit-sdk": { "resource": "networks", "method": "retrieve_graph", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "网络 UUID。" }, { "name": "depth", "in": "query", "schema": { "type": "string", "enum": [ "1", "2", "3", "all" ] }, "description": "从重点主体开始包含的跳数。默认为全部（无限制）。" }, { "name": "focus_kind", "in": "query", "schema": { "type": "string", "enum": [ "vendor_user", "vendor_business", "transaction_party" ] }, "description": "作为图谱中心的主体类型。必须与 focus_id 一起提供；在深度受限且两者均未提供时，默认为任意成员。" }, { "name": "focus_id", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "作为图谱中心的主体 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/graph/?depth=2' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve_graph(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieveGraph(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RetrieveGraph(ctx, \"n3a5e000-0000-4000-8000-000000000001\", didit.NetworksRetrieveGraphParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieveGraph(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieveGraph('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve_graph(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveGraphAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "网络图谱。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkGraph" } } } }, "404": { "description": "未找到网络（或对当前应用不可见）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/members/": { "get": { "summary": "列出网络成员", "description": "列出属于该网络的主体（vendor 用户、vendor 企业或交易参与方）。", "operationId": "list_network_members", "x-didit-sdk": { "resource": "networks", "method": "list_members", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "网络 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/members/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.list_members(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.listMembers(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.ListMembers(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().listMembers(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->listMembers('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.list_members(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.ListMembersAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "网络成员。未分页。", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkMember" } } } } } } }, "404": { "description": "未找到网络（或对当前应用不可见）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/signals/": { "get": { "summary": "列出网络信号", "description": "列出关联该网络各成员的信号（共享的设备、IP、人脸、证件号、电话、邮箱或地址值）。", "operationId": "list_network_signals", "x-didit-sdk": { "resource": "networks", "method": "list_signals", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "网络 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/signals/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.list_signals(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.listSignals(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.ListSignals(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().listSignals(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->listSignals('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.list_signals(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.ListSignalsAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "网络信号。未分页。", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkSignal" } } } } } } }, "404": { "description": "未找到网络（或对当前应用不可见）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/timeline/": { "get": { "summary": "获取网络时间线", "description": "不带 `contract`：网络自身事件（检测、每个信号的最新观察结果及其审核），按时间从旧到新排序且不分页。`limit`、`cursor` 和 `event_type` 会被忽略。带 `contract=2`：类型化时间线，按时间从新到旧排序并通过游标分页。它还会添加成员账户的操作记录（验证尝试、交易、您通过事件 API 提交的登录记录以及它们命中的生效规则）以及为该网络开启的案件。`note_added` 事件仅返回给控制台成员，绝不返回给 API 密钥。需要完全访问权限的 API 密钥，或控制台成员具备 `read:networks` 权限。", "operationId": "get_network_timeline", "x-didit-sdk": { "resource": "networks", "method": "retrieve_timeline", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "网络 UUID。" }, { "name": "contract", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "2" ] }, "description": "`2` 返回带类型的时间线。省略则返回默认时间线。任何其他值都会返回 400。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500, "default": 100 }, "description": "仅适用于类型化时间线。每页事件数，1 到 500。默认为 100。" }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "仅适用于类型化时间线。上一页的 `next_cursor`。无效或空的游标返回 400。" }, { "name": "event_type", "in": "query", "required": false, "style": "form", "explode": true, "schema": { "type": "array", "maxItems": 20, "items": { "type": "string", "enum": [ "network_detected", "signal_observed", "network_active", "network_in_review", "network_resolved", "network_dismissed", "verification_attempt", "transaction", "login", "rule_hit", "case_linked", "note_added" ] } }, "description": "仅适用于类型化时间线。要保留的事件类型，可重复或以逗号分隔，最多 20 个值。默认为所有类型。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/timeline/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "curl", "label": "curl (typed timeline)", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/3fa85f64-5717-4562-b3fc-2c963f66afa6/timeline/?contract=2&limit=50&event_type=verification_attempt,login' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve_timeline(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieveTimeline(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RetrieveTimeline(ctx, \"n3a5e000-0000-4000-8000-000000000001\", didit.NetworksRetrieveTimelineParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieveTimeline(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieveTimeline('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve_timeline(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveTimelineAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "不带 `contract` 时：`{results}`，最旧的排在最前，不分页。带 `contract=2` 时：`{results, next_cursor}`，最新的排在最前。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/NetworkTimeline" }, { "$ref": "#/components/schemas/NetworkTimelinePage" } ] }, "examples": { "Default timeline": { "summary": "不带 contract", "value": { "results": [ { "event_type": "network_detected", "occurred_at": "2026-10-01T09:12:44Z", "label": "Network detected", "metadata": { "network_id": "N-0042" } }, { "event_type": "signal_observed", "occurred_at": "2026-10-12T16:03:10Z", "label": "device observed", "metadata": { "signal_type": "device", "subject_count": 3, "is_hub": false } }, { "event_type": "network_in_review", "occurred_at": "2026-10-12T16:30:00Z", "label": "Network in_review", "metadata": { "reason": "Shared device across three new accounts." } } ] } }, "Typed timeline": { "summary": "配合 contract=2", "value": { "results": [ { "id": "monitoring_event:9b2f1c3e-4d5a-4b6c-8d7e-0f1a2b3c4d5e", "event_type": "login", "occurred_at": "2026-10-12T18:41:02Z", "ingested_at": "2026-10-12T18:41:03Z", "label": "Login", "metadata": {}, "account": { "node_id": "vendor_user:5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "node_type": "account", "uuid": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "vendor_data": "user-1042", "display_name": "Alex Example", "ownership": "owned", "route": { "kind": "user", "id": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "source_ref": { "kind": "monitoring_event", "id": "9b2f1c3e-4d5a-4b6c-8d7e-0f1a2b3c4d5e", "ownership": "owned" }, "verification_attempt": null, "transaction": null, "login": { "action": "auth.login", "succeeded": true, "status": "APPROVED", "ip": { "address": "203.0.113.24", "country_code": "ES", "city": "Madrid", "connection_type": null, "is_vpn_or_tor": false, "is_data_center": false }, "device": { "fingerprint": "fp_0a1b2c3d", "label": "Chrome · Android" }, "is_first_login": false, "is_new_device": true }, "rule_hit": null, "case_linked": null, "note_added": null }, { "id": "session:1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "event_type": "verification_attempt", "occurred_at": "2026-10-12T16:03:10Z", "ingested_at": "2026-10-12T16:03:10Z", "label": "Verification attempt 2 of 2", "metadata": {}, "account": { "node_id": "vendor_user:5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "node_type": "account", "uuid": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "vendor_data": "user-1042", "display_name": "Alex Example", "ownership": "owned", "route": { "kind": "user", "id": "5f6e7d8c-9b0a-4c1d-8e2f-3a4b5c6d7e8f", "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "source_ref": { "kind": "session", "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "ownership": "owned", "route": { "kind": "session", "id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } }, "verification_attempt": { "session_id": "1c2d3e4f-5a6b-4c7d-8e9f-0a1b2c3d4e5f", "session_number": 1287, "attempt": 2, "attempt_count": 2, "status": "Approved", "status_changed_at": "2026-10-12T16:05:41Z", "decline_reasons": [] }, "transaction": null, "login": null, "rule_hit": null, "case_linked": null, "note_added": null }, { "id": "signal_observed:8d7c6b5a-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "event_type": "signal_observed", "occurred_at": "2026-10-12T16:03:10Z", "ingested_at": "2026-10-01T09:12:44Z", "label": "device observed", "metadata": { "signal_type": "device", "subject_count": 3, "is_hub": false }, "account": null, "source_ref": null, "verification_attempt": null, "transaction": null, "login": null, "rule_hit": null, "case_linked": null, "note_added": null } ], "next_cursor": "eyJ0IjoiMjAyNi0xMC0xMlQxNjowMzoxMCswMDowMCIsImMiOiIyMDI2LTEwLTAxVDA5OjEyOjQ0KzAwOjAwIiwiciI6MSwidSI6IjhkN2M2YjVhLTRlM2YtNGEyYi05YzFkLTBlOWY4YTdiNmM1ZCJ9" } } } } } }, "400": { "description": "当存在 `contract` 时：无效的 `contract`、`limit`、`cursor` 或 `event_type` 值。", "content": { "application/json": { "examples": { "Unsupported contract": { "summary": "不支持的合约", "value": { "contract": [ "\"3\" is not a valid choice." ] } }, "Invalid cursor": { "summary": "无效的游标", "value": { "cursor": [ "This cursor is not valid. Reload the feed." ] } }, "Limit too large": { "summary": "限制过大", "value": { "limit": [ "Ensure this value is less than or equal to 500." ] } }, "Unknown event type": { "summary": "未知事件类型", "value": { "event_type": { "0": [ "\"logout\" is not a valid choice." ] } } } } } } }, "401": { "description": "凭据缺失或无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Missing or invalid credentials": { "summary": "凭据缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "API 密钥属于另一个应用，或者是一个访问权限受限的密钥：Networks endpoint 需要具有完全访问权限的密钥。控制台成员 token 需要 `read:networks` 权限。若组织未启用 Networks，也会返回 `code: networks_not_entitled`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Networks not enabled": { "summary": "网络未启用", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "受限的 API 密钥", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "无权限", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未找到网络（或对当前应用不可见）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/map/": { "get": { "summary": "获取网络地图", "description": "该网络成员地址/位置汇聚的地理点，源自支撑其成员身份的会话、企业会话和交易。", "operationId": "get_network_map", "x-didit-sdk": { "resource": "networks", "method": "retrieve_map", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "n3a5e000-0000-4000-8000-000000000001" }, "description": "网络 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/n3a5e000-0000-4000-8000-000000000001/map/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.retrieve_map(\n \"n3a5e000-0000-4000-8000-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.retrieveMap(\"n3a5e000-0000-4000-8000-000000000001\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RetrieveMap(ctx, \"n3a5e000-0000-4000-8000-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().retrieveMap(\"n3a5e000-0000-4000-8000-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->retrieveMap('n3a5e000-0000-4000-8000-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.retrieve_map(\"n3a5e000-0000-4000-8000-000000000001\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RetrieveMapAsync(\"n3a5e000-0000-4000-8000-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "网络地图。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkMap" } } } }, "404": { "description": "未找到网络（或对当前应用不可见）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/sessions/{session_id}/networks/": { "get": { "summary": "列出某会话的网络", "description": "列出会话的供应商用户所属的网络。通过与会话 vendor_data 关联的用户进行解析。", "operationId": "list_session_network_memberships", "x-didit-sdk": { "resource": "sessions", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "会话 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/sessions/aaaaaaaa-0000-4000-8000-000000000001/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.sessions.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.sessions().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "该实体所属的网络。未分页。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "在此应用中未找到主体，或没有用于查询的关联主体。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/business-sessions/{business_session_id}/networks/": { "get": { "summary": "列出企业会话的网络", "description": "列出企业会话的供应商企业所属的网络。", "operationId": "list_business_session_network_memberships", "x-didit-sdk": { "resource": "business_sessions", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "business_session_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "企业会话 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/business-sessions/aaaaaaaa-0000-4000-8000-000000000002/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.business_sessions.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businessSessions.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.BusinessSessions.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businessSessions().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businessSessions->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.business_sessions.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.BusinessSessions.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "该实体所属的网络。未分页。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "在此应用中未找到主体，或没有用于查询的关联主体。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/users/{vendor_user_uuid}/networks/": { "get": { "summary": "列出用户的网络", "description": "列出供应商用户所属的网络。", "operationId": "list_user_network_memberships", "x-didit-sdk": { "resource": "users", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "vendor_user_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "厂商用户 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/users/aaaaaaaa-0000-4000-8000-000000000003/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.users.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.users.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Users.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.users().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "users->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.users.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Users.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "该实体所属的网络。未分页。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "在此应用中未找到主体，或没有用于查询的关联主体。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/{vendor_business_uuid}/networks/": { "get": { "summary": "列出企业的网络", "description": "列出供应商企业所属的网络。", "operationId": "list_business_network_memberships", "x-didit-sdk": { "resource": "businesses", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "vendor_business_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "厂商企业 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/businesses/aaaaaaaa-0000-4000-8000-000000000004/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.businesses.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.businesses.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Businesses.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.businesses().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "businesses->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.businesses.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Businesses.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "该实体所属的网络。未分页。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "在此应用中未找到主体，或没有用于查询的关联主体。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/{transaction_uuid}/networks/": { "get": { "summary": "列出交易的网络", "description": "列出交易底层的 KYC/KYB 主体所属的网络（通过交易的会话或企业会话解析）。", "operationId": "list_transaction_network_memberships", "x-didit-sdk": { "resource": "transactions", "method": "list_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "transaction_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "交易 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/aaaaaaaa-0000-4000-8000-000000000005/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.transactions.list_networks(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.transactions.listNetworks(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.ListNetworks(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.transactions().listNetworks(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->listNetworks('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.transactions.list_networks(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.ListNetworksAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "该实体所属的网络。未分页。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "在此应用中未找到主体，或没有用于查询的关联主体。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/{transaction_uuid}/parties/{transaction_party_uuid}/networks/": { "get": { "summary": "列出交易方的网络", "description": "列出交易相关方（汇款人、收款人或交易对手）所属的网络，该网络直接通过相关方本身解析，而非通过交易的基础会话解析。", "operationId": "list_transaction_party_network_memberships", "x-didit-sdk": { "resource": "transactions", "method": "list_party_networks", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "transaction_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "交易 UUID。" }, { "name": "transaction_party_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "交易当事方 UUID。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/aaaaaaaa-0000-4000-8000-000000000005/parties/bbbbbbbb-0000-4000-8000-000000000006/networks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.transactions.list_party_networks(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.transactions.listPartyNetworks(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.ListPartyNetworks(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.transactions().listPartyNetworks(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->listPartyNetworks('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.transactions.list_party_networks(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.ListPartyNetworksAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "该实体所属的网络。未分页。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EntityNetworkMembershipList" } } } }, "404": { "description": "在此应用中未找到主体，或没有用于查询的关联主体。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/biometric-templates/": { "get": { "summary": "列出保留的生物特征模板", "description": "选择启用的应用在会话被删除时（参见 `DELETE /v3/session/{sessionId}/delete/`），会保留一个锚定到用户的、独立管理的无图像人脸生物特征模板。模板是具有有限 `expires_at` 的生物识别数据；它们绝不包含图像、会话数据或身份字段，并在用户删除、隐私清除、过期或明确清除时被清除。这些 endpoint 仅接受应用 API 密钥（`x-api-key`）；Business Console 用户 token 将被拒绝并返回 `403`。\n\n返回应用当前持有的模板的分页列表。已清除的模板不会被列出。", "operationId": "list_biometric_templates", "x-didit-sdk": { "resource": "biometric_templates", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "vendor_data", "required": false, "description": "对所属用户的当前 `vendor_data` 进行不区分大小写的子字符串匹配。", "schema": { "type": "string" } }, { "in": "query", "name": "vendor_user_uuid", "required": false, "description": "对所属用户的精确匹配。", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "required": false, "description": "生命周期状态。已清除的模板绝不会被列出。", "schema": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed" ] } }, { "in": "query", "name": "source_type", "required": false, "description": "模板的创建方式。", "schema": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ] } }, { "in": "query", "name": "retained_from", "required": false, "description": "在此时间或之后保留的模板。", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "retained_to", "required": false, "description": "在此时间或之前保留的模板。不得早于 `retained_from`（`400`）。", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "ordering", "required": false, "description": "排序顺序。", "schema": { "type": "string", "enum": [ "retained_at", "-retained_at", "expires_at", "-expires_at" ], "default": "-retained_at" } }, { "in": "query", "name": "limit", "required": false, "description": "页面大小。", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "required": false, "description": "分页偏移量。", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "分页模板列表。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "模板 ID。随机生成；并非衍生自已删除的会话或其人脸。" }, "vendor_user_uuid": { "type": "string", "format": "uuid", "description": "所有者用户。" }, "vendor_data": { "type": "string", "nullable": true, "description": "用户的当前 `vendor_data`，在您读取模板时解析（绝不会被复制）。" }, "source_type": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ], "description": "模板的创建方式：会话删除（API 或 Console）、应用的数据自动保留期限，或者根据您的指示由 Didit 执行的历史回填。" }, "provenance_reference": { "type": "string", "format": "uuid", "description": "将模板与其审计日志关联的不透明引用。它不是已删除会话的 id，且无法解析为该 id。" }, "retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "在保留时间到达时适用的应用策略。" }, "retention_override": { "type": "boolean", "nullable": true, "description": "删除请求中发送的 `retain_face_embeddings` 值，应用策略时为 `null`。" }, "retained_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "模板到期并被自动清除的时间。始终设置。" }, "retained_by": { "type": "string", "nullable": true, "description": "发出指令的主体：API 密钥对应的应用 ID、控制台操作对应的控制台成员 ID，或自动数据保留对应的 `service:` 标识符。绝不为邮箱地址。" }, "retained_by_type": { "type": "string", "enum": [ "API_KEY", "CONSOLE_USER", "SYSTEM" ] }, "instruction_class": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ] }, "instruction_source": { "type": "string", "enum": [ "api", "console", "automatic_retention", "backfill", "privacy_erasure", "explicit_template_purge", "vendor_user_delete", "expiry", "reconciliation", "migration", "system" ] }, "instruction_id": { "type": "string", "description": "删除请求中发送的 `instruction_id`，或由 Didit 生成的 id。" }, "held_out_of_use": { "type": "boolean", "description": "仅在法律保留生效期间为 `true`。处于保留状态的模板将从所有匹配中排除。" }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed", "purged" ], "description": "只有处于 `active` 状态、未被暂停、未超过 `expires_at` 且其用户仍然存在的模板才会参与比对。" }, "purged_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "examples": { "One active template": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "vendor_data": "user-42", "source_type": "session_delete", "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f", "retention_policy": "retain_until_user_deleted", "retention_override": null, "retained_at": "2026-08-28T10:15:42.318402Z", "expires_at": "2027-08-28T10:15:42.318402Z", "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e", "retained_by_type": "API_KEY", "instruction_class": "operational_session_delete", "instruction_source": "api", "instruction_id": "post-approval-cleanup-2026-08", "held_out_of_use": false, "status": "active", "purged_at": null } ] } } } } } }, "400": { "description": "无效的过滤值，或 `retained_to` 早于 `retained_from`。按字段索引的验证错误。", "content": { "application/json": { "examples": { "Bad range": { "value": { "retained_to": [ "Must be on or after retained_from." ] } } } } } }, "403": { "description": "Console 用户 token，或该 API 密钥不被允许。这些 endpoint 仅接受应用 API 密钥。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/biometric-templates/?vendor_data=user-42&status=active' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.biometric_templates.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.biometricTemplates.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.BiometricTemplates.ListAutoPaging(ctx, didit.BiometricTemplatesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.biometricTemplates().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.biometric_templates.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.BiometricTemplates.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/biometric-templates/count/": { "get": { "summary": "统计保留的生物特征模板数量", "description": "选择启用的应用在会话被删除时（参见 `DELETE /v3/session/{sessionId}/delete/`），会保留一个锚定到用户的、独立管理的无图像人脸生物特征模板。模板是具有有限 `expires_at` 的生物识别数据；它们绝不包含图像、会话数据或身份字段，并在用户删除、隐私清除、过期或明确清除时被清除。这些 endpoint 仅接受应用 API 密钥（`x-api-key`）；Business Console 用户 token 将被拒绝并返回 `403`。\n\n返回使用与列表 endpoint 相同过滤器匹配的模板数量。用于检查带有 `delete_all: true` 的过滤批量清除将影响哪些模板。", "operationId": "count_biometric_templates", "x-didit-sdk": { "resource": "biometric_templates", "method": "count", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "query", "name": "vendor_data", "required": false, "description": "对所属用户的当前 `vendor_data` 进行不区分大小写的子字符串匹配。", "schema": { "type": "string" } }, { "in": "query", "name": "vendor_user_uuid", "required": false, "description": "对所属用户的精确匹配。", "schema": { "type": "string", "format": "uuid" } }, { "in": "query", "name": "status", "required": false, "description": "生命周期状态。已清除的模板绝不会被列出。", "schema": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed" ] } }, { "in": "query", "name": "source_type", "required": false, "description": "模板的创建方式。", "schema": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ] } }, { "in": "query", "name": "retained_from", "required": false, "description": "在此时间或之后保留的模板。", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "retained_to", "required": false, "description": "在此时间或之前保留的模板。不得早于 `retained_from`（`400`）。", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "计数。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer", "minimum": 0 } } }, "examples": { "Count": { "value": { "count": 128 } } } } } }, "400": { "description": "无效的过滤值，或 `retained_to` 早于 `retained_from`。按字段索引的验证错误。", "content": { "application/json": { "examples": { "Bad range": { "value": { "retained_to": [ "Must be on or after retained_from." ] } } } } } }, "403": { "description": "Console 用户 token，或该 API 密钥不被允许。这些 endpoint 仅接受应用 API 密钥。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/biometric-templates/count/?status=active' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.count()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.count();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.Count(ctx, didit.BiometricTemplatesCountParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().count();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->count();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.count\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.CountAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/biometric-templates/{template_uuid}/": { "get": { "summary": "获取保留的生物特征模板", "description": "选择启用的应用在会话被删除时（参见 `DELETE /v3/session/{sessionId}/delete/`），会保留一个锚定到用户的、独立管理的无图像人脸生物特征模板。模板是具有有限 `expires_at` 的生物识别数据；它们绝不包含图像、会话数据或身份字段，并在用户删除、隐私清除、过期或明确清除时被清除。这些 endpoint 仅接受应用 API 密钥（`x-api-key`）；Business Console 用户 token 将被拒绝并返回 `403`。\n\n返回一个模板。响应绝不包含图像、特征向量、已删除会话的 ID 或身份数据。", "operationId": "get_biometric_template", "x-didit-sdk": { "resource": "biometric_templates", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "template_uuid", "required": true, "description": "模板 ID，由会话删除 endpoint 在 `biometric_template_uuid` 中返回、在人脸搜索匹配中通过 `biometric_template_id` 返回，或由列表 endpoint 返回。", "schema": { "type": "string", "format": "uuid", "example": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b" } } ], "responses": { "200": { "description": "模板。", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "模板 ID。随机生成；并非衍生自已删除的会话或其人脸。" }, "vendor_user_uuid": { "type": "string", "format": "uuid", "description": "所有者用户。" }, "vendor_data": { "type": "string", "nullable": true, "description": "用户的当前 `vendor_data`，在您读取模板时解析（绝不会被复制）。" }, "source_type": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ], "description": "模板的创建方式：会话删除（API 或 Console）、应用的数据自动保留期限，或者根据您的指示由 Didit 执行的历史回填。" }, "provenance_reference": { "type": "string", "format": "uuid", "description": "将模板与其审计日志关联的不透明引用。它不是已删除会话的 id，且无法解析为该 id。" }, "retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "在保留时间到达时适用的应用策略。" }, "retention_override": { "type": "boolean", "nullable": true, "description": "删除请求中发送的 `retain_face_embeddings` 值，应用策略时为 `null`。" }, "retained_at": { "type": "string", "format": "date-time" }, "expires_at": { "type": "string", "format": "date-time", "description": "模板到期并被自动清除的时间。始终设置。" }, "retained_by": { "type": "string", "nullable": true, "description": "发出指令的主体：API 密钥对应的应用 ID、控制台操作对应的控制台成员 ID，或自动数据保留对应的 `service:` 标识符。绝不为邮箱地址。" }, "retained_by_type": { "type": "string", "enum": [ "API_KEY", "CONSOLE_USER", "SYSTEM" ] }, "instruction_class": { "type": "string", "enum": [ "operational_session_delete", "privacy_erasure" ] }, "instruction_source": { "type": "string", "enum": [ "api", "console", "automatic_retention", "backfill", "privacy_erasure", "explicit_template_purge", "vendor_user_delete", "expiry", "reconciliation", "migration", "system" ] }, "instruction_id": { "type": "string", "description": "删除请求中发送的 `instruction_id`，或由 Didit 生成的 id。" }, "held_out_of_use": { "type": "boolean", "description": "仅在法律保留生效期间为 `true`。处于保留状态的模板将从所有匹配中排除。" }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed", "purged" ], "description": "只有处于 `active` 状态、未被暂停、未超过 `expires_at` 且其用户仍然存在的模板才会参与比对。" }, "purged_at": { "type": "string", "format": "date-time", "nullable": true } } }, "examples": { "Active template": { "value": { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f", "vendor_data": "user-42", "source_type": "session_delete", "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f", "retention_policy": "retain_until_user_deleted", "retention_override": null, "retained_at": "2026-08-28T10:15:42.318402Z", "expires_at": "2027-08-28T10:15:42.318402Z", "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e", "retained_by_type": "API_KEY", "instruction_class": "operational_session_delete", "instruction_source": "api", "instruction_id": "post-approval-cleanup-2026-08", "held_out_of_use": false, "status": "active", "purged_at": null } } } } } }, "403": { "description": "Console 用户 token，或该 API 密钥不被允许。这些 endpoint 仅接受应用 API 密钥。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未知模板、其他应用的模板，或（在 `GET` 时）已被清除的模板。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Biometric template not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/biometric-templates/9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.retrieve(\n \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.retrieve(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.Retrieve(ctx, \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().retrieve(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->retrieve('9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.retrieve(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.RetrieveAsync(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "清除保留的生物特征模板", "description": "选择启用的应用在会话被删除时（参见 `DELETE /v3/session/{sessionId}/delete/`），会保留一个锚定到用户的、独立管理的无图像人脸生物特征模板。模板是具有有限 `expires_at` 的生物识别数据；它们绝不包含图像、会话数据或身份字段，并在用户删除、隐私清除、过期或明确清除时被清除。这些 endpoint 仅接受应用 API 密钥（`x-api-key`）；Business Console 用户 token 将被拒绝并返回 `403`。\n\n清除一个模板：它将从所有类型的匹配中移除，且存储的模板将被删除。该操作不可逆，并会与执行主体一起记录在审计日志中。\n\n**重试语义：** Didit 会先删除存储的模板，然后才将模板标记为已清除。如果生物识别存储不可用，调用将返回 `503`，模板状态变更为 `status: purge_failed` 并且已从匹配中排除；重复相同调用即可完成清除。重复清除已清除的模板将返回 `already_purged`。\n\n所属用户的 `POST /v3/users/delete/` 操作、对该用户会话带有 `deletion_instruction: privacy_erasure` 的任何删除操作，以及到达 `expires_at` 时，模板也会被自动清除。", "operationId": "purge_biometric_template", "x-didit-sdk": { "resource": "biometric_templates", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "template_uuid", "required": true, "description": "模板 ID，由会话删除 endpoint 在 `biometric_template_uuid` 中返回、在人脸搜索匹配中通过 `biometric_template_id` 返回，或由列表 endpoint 返回。", "schema": { "type": "string", "format": "uuid", "example": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b" } } ], "responses": { "200": { "description": "清除结果。", "content": { "application/json": { "schema": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "purged", "already_purged" ] } } }, "examples": { "Purged": { "value": { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "purged" } }, "Already purged": { "value": { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "already_purged" } } } } } }, "403": { "description": "Console 用户 token，或该 API 密钥不被允许。这些 endpoint 仅接受应用 API 密钥。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未知模板、其他应用的模板，或（在 `GET` 时）已被清除的模板。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "Biometric template not found." } } } } } }, "503": { "description": "在保留或清除生物特征模板时，生物特征存储库不可用。未删除任何内容；请重试相同的请求。重试具有幂等性，并最终收敛至单个模板。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Retryable": { "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/biometric-templates/9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.delete(\n \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.delete(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.Delete(ctx, \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().delete(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->delete('9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.delete(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.DeleteAsync(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/biometric-templates/delete/": { "post": { "summary": "批量清除保留的生物特征模板", "description": "已选择启用的应用在会话被删除时（参见 `DELETE /v3/session/{sessionId}/delete/`），会保留一个单独管理的、不含图像的人脸生物特征模板并锚定至用户。模板是具有有限有效期（由 `expires_at` 指定）的生物识别数据；它们绝不包含图像、会话数据或身份字段，并在用户删除、隐私擦除、过期或显式清除时被清除。这些 endpoint 仅接受应用 API 密钥（`x-api-key`）；Business Console 用户 token 将被拒绝并返回 `403`。\n\n可通过单次调用清除多个模板：指定 id 列表，或使用 `delete_all: true`（可选使用与列表 endpoint 相同的过滤器缩小范围）。模板会被逐一清除，每个结果会报告 `purged` 或 `already_purged`。如果生物识别存储库不可用，调用将在遇到第一个失败的模板时返回 `503`：请求中先前已清除的模板保持已清除状态，失败的模板状态变为 `purge_failed`（已排除在比对之外），重试该请求即可完成操作。\n\n**不带过滤器的 `delete_all: true` 会清除应用中的所有生物特征模板，且无法撤销。** 请先使用相同的过滤器调用计数 endpoint。", "operationId": "bulk_purge_biometric_templates", "x-didit-sdk": { "resource": "biometric_templates", "method": "batch_delete", "auth": "api_key", "server": true }, "tags": [ "Biometric Templates" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "template_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "description": "要清理的模板。除非 `delete_all` 为 `true`，否则此项必填。已经清理过的 ID 将报告为 `already_purged`。" }, "delete_all": { "type": "boolean", "default": false, "description": "为 `true` 时，清除与以下过滤器匹配的每个模板（未提供过滤器时为应用的所有模板）。`template_uuids` 将被忽略。不可逆。" }, "vendor_data": { "type": "string", "description": "仅适用于 `delete_all`：对所属用户的 `vendor_data` 进行不区分大小写的子字符串匹配。" }, "vendor_user_uuid": { "type": "string", "format": "uuid", "description": "仅适用于 `delete_all`：与所属用户精确匹配。" }, "status": { "type": "string", "enum": [ "pending", "active", "expired", "held_out_of_use", "purge_pending", "purge_failed" ], "description": "仅与 `delete_all` 一起使用。" }, "source_type": { "type": "string", "enum": [ "session_delete", "automatic_retention", "backfill" ], "description": "仅与 `delete_all` 一起使用。" }, "retained_from": { "type": "string", "format": "date-time", "description": "仅与 `delete_all` 一起使用。" }, "retained_to": { "type": "string", "format": "date-time", "description": "仅与 `delete_all` 一起使用。不得早于 `retained_from`。" } } }, "examples": { "By id": { "value": { "template_uuids": [ "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d" ] } }, "Every template of one User": { "value": { "delete_all": true, "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f" } }, "Every template in the application": { "value": { "delete_all": true } } } } } }, "responses": { "200": { "description": "按模板划分的清理结果。", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "outcome": { "type": "string", "enum": [ "purged", "already_purged" ] } } } } } }, "examples": { "Mixed": { "value": { "results": [ { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "purged" }, { "uuid": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "outcome": "already_purged" } ] } } } } } }, "400": { "description": "验证错误 — 未清除任何内容。", "content": { "application/json": { "examples": { "Missing selector": { "value": { "template_uuids": [ "This field is required unless delete_all is true." ] } }, "Bad range": { "value": { "retained_to": [ "Must be on or after retained_from." ] } } } } } }, "403": { "description": "Console 用户 token，或该 API 密钥不被允许。这些 endpoint 仅接受应用 API 密钥。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } }, "503": { "description": "在保留或清除生物特征模板时，生物特征存储库不可用。未删除任何内容；请重试相同的请求。重试具有幂等性，并最终收敛至单个模板。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Retryable": { "value": { "detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/biometric-templates/delete/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"delete_all\": true, \"vendor_user_uuid\": \"2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.biometric_templates.batch_delete(\n template_uuids=[\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.biometricTemplates.batchDelete({\n template_uuids: [\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.BiometricTemplates.BatchDelete(ctx, didit.BiometricTemplatesBatchDeleteParams{\n\tTemplateUUIDs: didit.Some([]string{\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.BiometricTemplatesBatchDeleteParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.biometricTemplates().batchDelete(BiometricTemplatesBatchDeleteParams.builder()\n .templateUuids(List.of(\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "biometricTemplates->batchDelete([\n 'template_uuids' => ['9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b', '1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.biometric_templates.batch_delete(template_uuids: [\"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.BiometricTemplates.BatchDeleteAsync(new BiometricTemplatesBatchDeleteParams\n{\n TemplateUuids = new string[] { \"9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b\", \"1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/kyb/shareholders/": { "post": { "summary": "KYB 公司登记企业含股东信息（独立项）", "operationId": "post_v3_kyb_shareholders", "x-didit-sdk": { "resource": "kyb", "method": "list_shareholders", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "检索由 `POST /v3/kyb/search/` 返回的某一候选企业的 Lite 档案**以及直接股东**（自然人和法人实体，含其股权区间）。\n\n**与搜索配对。** 传入候选企业的 `kyb_response_id`，必须与同一应用搜索返回的完全一致。请在您打算购买的等级（`POST /v3/kyb/search/` 上的 `tier`）进行搜索，因为搜索运行在为该等级提供服务的公司登记链上，而空的 Lite 搜索并不能证明公司登记中没有该公司。当该国家/地区的股权结构数据位于另一个公司登记时，Didit 会按注册号在该处重新查找该公司，无需额外费用。\n\n**计费。** 按该国家/地区的股东价格计费，参见 [KYB 公司登记定价](/zh/getting-started/kyb-registry-pricing)。当公司登记中没有该公司的股东记录（或该国家/地区根本不提供股权结构数据）时，将改为投递 Lite 档案并按其计费：请读取 `registry_tier_delivered` 和 `registry_ownership_status`。在进行任何公司登记调用之前，会根据股东价格核查余额（不足时返回 `403`）。\n\n**可用性。** 仅限 v3。每次调用都会创建一个企业会话（其 id 即为 `request_id`）。\n\n**待处理报告。** 当报告仍在生成中，或者股权结构部分尚未从公司登记中检索完毕时，endpoint 返回 202 Accepted、kyb_registry.fetch_status=pending、kyb_registry.registry_ownership_status=pending 以及 registry_tier_delivered=null。请保留 request_id 并调用 GET /v3/session/{request_id}/decision/，直到 registry_checks[0].company.fetch_status 解析完成。Didit 会自动完成报告，并在准备就绪后按实际投递的等级扣费。处于待处理状态时请勿重复购买；每次新的 POST 都会创建一个单独的请求。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistryCandidateRequest" }, "example": { "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/shareholders/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"kyb_response_id\": \"69aeeb95febb0f1704042259\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.list_shareholders(\n kyb_response_id=\"69aeeb95febb0f1704042259\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.listShareholders({\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.ListShareholders(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KYBRegistryCandidateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().listShareholders(KYBRegistryCandidateRequest.builder()\n .kybResponseId(\"69aeeb95febb0f1704042259\")\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->listShareholders([\n 'kyb_response_id' => '69aeeb95febb0f1704042259',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.list_shareholders(\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.ListShareholdersAsync(new KYBRegistryCandidateRequest\n{\n KybResponseId = \"69aeeb95febb0f1704042259\",\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "返回企业报告并按实际交付的等级计费。仍在准备中的股权结构报告可能会返回 202；请保留 request_id 以检索其已保存的决策。", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "为此检索创建的企业会话 ID。如果在响应返回后公司登记信息才解析完成，已存储的记录（在控制台中可见）将持续更新。" }, "registry_tier_requested": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "此 endpoint 销售的等级：针对 select 的 `basic` (Lite)、`shareholders`、`ubo`。" }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "实际交付并计费的等级。当该国家/地区的公司登记不包含股权结构数据，或登记机构没有该公司的股权结构记录时，该等级会低于请求的等级。", "nullable": true }, "kyb_registry": { "type": "object", "description": "完整的公司登记档案。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Didit 为此企业记录分配的 ID。" }, "node_id": { "type": "string", "example": "feature_kyb_registry" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review" ], "description": "Didit 对公司登记核验的评估（例如，当企业在登记处中处于非活跃状态或无法获取股权结构数据时为 `In Review`）。" }, "registry_status": { "type": "string", "nullable": true, "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off", null ], "description": "公司登记机构报告的归一化企业状态。" }, "data_resolved": { "type": "boolean", "description": "公司登记处返回完整资料后为 `true`。轮询后登记处仍在处理中时为 `false`，一旦登记处处理完成，存储的记录将自动补充完整。" }, "company_name": { "type": "string", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "example": "00445790" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2。", "example": "GB" }, "region": { "type": "string", "nullable": true, "description": "登记属于地区性时的行政区划代码（例如 `US-CA` 对应 `CA`）；否则为空。" }, "company_type": { "type": "string", "nullable": true, "example": "Public Limited Company" }, "incorporation_date": { "type": "string", "format": "date", "nullable": true, "example": "1947-11-27" }, "registered_address": { "type": "string", "nullable": true, "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA" }, "tax_number": { "type": "string", "nullable": true, "example": "GB412 8925 93" }, "risk_level": { "type": "string", "nullable": true, "description": "公司登记所报告的风险等级（如可用）。" }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "跨司法管辖区验证状态：当公司登记状态确认存续（`active`）时为 `verified`；当其显示公司不再存续（例如 `dissolved`）时为 `failed`；否则为 `unknown`。对于非来自公司登记且选择仍处于 `pending` 状态的公司，该值为 `null`。" }, "is_from_registry": { "type": "boolean", "description": "对于此 endpoint 始终为 `true`，该档案从官方登记机构检索获取。" }, "fetch_status": { "type": "string", "enum": [ "pending", "resolved" ], "description": "公司登记获取生命周期。由 `data_resolved` 镜像。" }, "alternative_names": { "type": "string", "nullable": true, "description": "上报时的替代名称、商业名称、曾用名或原始语言公司名称（文本格式）。" }, "nature_of_business": { "type": "string", "nullable": true, "description": "活动描述或分类代码（如有报告）。" }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "字符串形式的十进制金额（若有上报）。" }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "报告的 ISO 4217 代码（如有）。" }, "website": { "type": "string", "nullable": true, "example": "https://www.tesco.com/" }, "email": { "type": "string", "nullable": true, "example": "customer.service@tesco.co.uk" }, "phone": { "type": "string", "nullable": true, "example": "03301231688" }, "legal_entity_identifier": { "type": "string", "nullable": true, "description": "LEI（若已上报）。" }, "location_of_registration": { "type": "string", "nullable": true, "description": "企业注册所在的登记机构/司法管辖区（如有报告）。" }, "vat_number": { "type": "string", "nullable": true, "description": "欧盟增值税号，在托管登记步骤中收集或随后编辑时提供。在选择时通常尚未设置。增值税号和税号核验会在终端用户在托管流程中提交登记步骤时运行。" }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "在登记提交时验证增值税号（若无，则为 `tax_number`）的结果。`valid` / `invalid`：由相应国家/地区的官方登记处判定（欧盟 VIES、挪威、瑞士、巴西、哥伦比亚、哥斯达黎加、厄瓜多尔、巴拉圭；波兰还由其国内增值税登记册判定）。`format_valid` / `invalid_format`：在无法查询登记处时，由该国家/地区的格式和校验位规则判定。`could_not_validate`：登记处不可用。`not_applicable`：无号码、无登记处或规则的国家/地区，或者沙盒会话。" }, "vat_validated_number": { "type": "string", "nullable": true, "description": "已核验的号码，格式以数据源所知为准（例如从法国 SIREN 或荷兰 RSIN 派生的增值税号）。若未运行核验，则为 `null`。" }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "判定 `vat_validation_status` 的来源：官方登记，或 `format_rules`。未运行任何检查时为 `null`。" }, "vat_validated_name": { "type": "string", "nullable": true, "description": "向验证该号码的数据源登记的名称（如果该数据源公开名称）。仅当状态为 `valid` 时设置。" }, "vat_validated_address": { "type": "string", "nullable": true, "description": "核验该号码的数据源中登记的地址（若该数据源披露）。仅在状态为 `valid` 时设置。" }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "检查的时间戳。未运行检查时为 `null`。" }, "financial_summary": { "type": "object", "nullable": true, "description": "公司登记所报告的股份/资本详情（币种、总股数、股份类别，如可用）。" }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MELISSA BETHELL" }, "designation": { "type": "string", "nullable": true, "description": "原始登记处的职务名称（例如 `Director`、`Secretary`）。" }, "role": { "type": "string", "description": "根据职务衍生出的归一化角色。包含完整的 17 个值的模型集；该 endpoint 上的登记解析通常会输出 director、non_executive_director、secretary、chairman 或 company_officer。", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "company_officer", "settlor", "protector", "investor", "other" ] }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "description": "当公司登记处将该任命标记为已辞任时为 `false`。" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ], "description": "关联的 KYC 会话状态（若已为此负责人发起）；否则为 `null`。" }, "kyc_session_url": { "type": "string", "nullable": true, "description": "关联 KYC 会话的验证链接（如果存在）。" }, "first_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的名字；并非从全名中推断。" }, "last_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的姓氏。" }, "address": { "type": "string", "nullable": true, "description": "登记处报告的官员地址。" }, "appointment_date": { "type": "string", "nullable": true, "description": "管理人员被任命的日期。", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "任期结束的日期（若有报告）。", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "公司登记报告的完整出生日期。如果仅已知出生年份或月份，则为 null。", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "公司登记所报告的出生年份，包括完整日期不可用的情况。" }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "公司登记所报告的出生月份。仅知晓年份时为 null。" } } }, "description": "从公司登记中提取的董事、秘书和其他高管。" }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "所有者是自然人还是企业实体。" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "归一化的角色（例如 `ubo`、`shareholder`）。" }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "公司登记报告的股权范围下限（例如 `25%`）。" }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "公司登记报告的股权结构区间上限。" }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ] }, "kyc_session_url": { "type": "string", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "解析出的股权百分比（上限值，回退为下限值）。" }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "完整的出生日期（如有报告）。", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "有报告时的委任日期。", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } }, "description": "从登记处提取的实际受益人/重大控制权人。当登记处未公开股权结构时可能为空。" }, "addresses": { "type": "array", "nullable": true, "description": "登记处注明的每个地址，采用标准规范格式。如果未注明，则为 null。", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "登记机构对企业进行分类的业务活动，采用一种规范化格式。若未注明则为 null。", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "公司登记备案日期（如可用）。年度申报表和大会使用 last_annual_return_date 与 last_agm_date；它们与财务账目不同。" }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "description": "在此 endpoint 上始终为 `null`（终端用户编辑公司登记数据时由托管 KYB 流程使用）。" }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在此 endpoint 上始终为 `null`。" }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "当控制台审核员随后编辑该记录时设置。" }, "is_editable": { "type": "boolean", "description": "来自公司登记的数据是否仍可在托管流程/控制台中进行编辑。" }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "与顶级 `registry_tier_delivered` 相同。", "nullable": true }, "registry_ownership_status": { "type": "string", "nullable": true, "enum": [ "not_requested", "delivered", "not_held", "unavailable", "pending", null ], "description": "当股权结构数据返回时为 `delivered`；当股权登记处已响应但未列出此企业时为 `not_held`（参见 `registry_data.ownership_error`）；当请求了股权结构等级但登记处没有此企业的数据或无法查询时为 `unavailable`（参见 `registry_data.ownership_error`）；当股权结构部分尚未从登记处检索完成且 Didit 仍在处理时为 `pending`；在 Lite 等级上为 `not_requested`。" }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "工作流订购的公司登记等级：`basic`、`shareholders` 或 `ubo`。也可在 `ownership.tier_requested` 中查看。" }, "registry_monitoring": { "type": "object", "nullable": true, "description": "该企业的最新登记监控，不存在时为 `null`。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "监控器监视的企业字段。" } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "回显您发送的 `vendor_data`。" }, "metadata": { "type": "object", "nullable": true, "description": "您发送的 `metadata` 回显。" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved company": { "summary": "完整的公司登记档案（为简明起见截断了管理人员列表）", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d", "node_id": "feature_kyb_registry", "status": "In Review", "registry_status": "active", "data_resolved": true, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": "", "company_type": "Public Limited Company", "incorporation_date": "1947-11-27", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "tax_number": "GB412 8925 93", "risk_level": "low risk", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": "https://www.tesco.com/", "email": "customer.service@tesco.co.uk", "phone": "03301231688", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": { "currency": "Pound (£)", "total_number_of_shares": "8174378721", "meta_detail": { "Class_Of_Share": "Ordinary" } }, "officers": [ { "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b", "name": "CHRISTOPHER JON TAYLOR", "designation": "Secretary", "role": "secretary", "nationality": null, "is_active": true, "kyc_status": null, "kyc_session_url": null }, { "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c", "name": "MELISSA BETHELL", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": null, "kyc_session_url": null } ], "beneficial_owners": [], "addresses": [ { "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "type": "legal_entity_registry_address", "description": "registered office address" } ], "industries": null, "accounts": { "last_account": "26 February 2025", "next_account": "26 February 2026", "due_by_date": "26 August 2026" }, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } } } } } }, "400": { "description": "验证错误。字段级问题使用 DRF 的标准外层结构。", "content": { "application/json": { "examples": { "Missing kyb_response_id": { "summary": "`kyb_response_id` 为必填项", "value": { "kyb_response_id": [ "This field is required." ] } }, "save_api_request=false rejected": { "summary": "选择内容始终持久化保存", "value": { "save_api_request": [ "KYB registry select must be saved so billing and retrieval can be tracked." ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何筛查或服务商调用之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "202": { "description": "报告已接受并仍在处理中。当报告仍在准备中时，endpoint 返回 202 Accepted、kyb_registry.fetch_status=pending 以及 registry_tier_delivered=null。请保留 request_id 并轮询调用 GET /v3/session/{request_id}/decision/，直至 registry_checks[0].company.fetch_status 解决。Didit 会自动完成报告，并在报告准备就绪后按交付的等级扣费。处于待处理状态时请勿重复购买；每个新的 POST 都会创建一个单独的请求。", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1kyb~1shareholders~1/post/responses/200/content/application~1json/schema" }, "examples": { "Pending (registry still resolving)": { "summary": "股权结构报告仍在处理中；获取已保存的决策", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d", "node_id": "feature_kyb_registry", "status": "Not Finished", "registry_status": null, "data_resolved": false, "company_name": "Example Holdings Limited", "registration_number": "12345678", "country_code": "HK", "region": null, "company_type": null, "incorporation_date": null, "registered_address": null, "tax_number": null, "risk_level": null, "verification_status": null, "is_from_registry": true, "fetch_status": "pending", "alternative_names": null, "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": {}, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true, "registry_tier_delivered": null, "registry_ownership_status": "pending" }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00", "registry_tier_delivered": null, "registry_tier_requested": "shareholders" } } } } } } } } }, "/v3/kyb/ubo/": { "post": { "summary": "KYB 公司登记企业含实际受益人信息（独立项）", "operationId": "post_v3_kyb_ubo", "x-didit-sdk": { "resource": "kyb", "method": "list_ubos", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [], "description": "检索由 `POST /v3/kyb/search/` 返回的某一候选企业的 Lite 档案、直接股东**以及通过股权链穿透解析出的最终实际受益人**（`registry_data.ubo_resolution` 包含母公司层级链）。\n\n**与搜索配对。** 传入候选企业的 `kyb_response_id`，必须与同一应用搜索返回的完全一致。请在您打算购买的等级（`POST /v3/kyb/search/` 上的 `tier`）进行搜索，因为搜索运行在为该等级提供服务的公司登记链上，而空的 Lite 搜索并不能证明公司登记中没有该公司。当该国家/地区的股权结构数据位于另一个公司登记时，Didit 会按注册号在该处重新查找该公司，无需额外费用。\n\n**计费。** 按该国家/地区的 UBO 价格计费（参见 [KYB 公司登记定价](/zh/getting-started/kyb-registry-pricing)）。投递的等级是该国家/地区和公司登记所能提供的最高等级：当穿透解析后的报告未列出任何自然人作为实际受益人时投递 Shareholders，当根本没有股权结构记录时投递 Lite；`registry_tier_delivered` 说明实际计费的等级。在进行任何公司登记调用之前，会根据 UBO 价格核查余额（不足时返回 `403`）。\n\n**可用性。** 仅限 v3。每次调用都会创建一个企业会话（其 id 即为 `request_id`）。\n\n**待处理报告。** 当报告仍在生成中，或者股权结构部分尚未从公司登记中检索完毕时，endpoint 返回 202 Accepted、kyb_registry.fetch_status=pending、kyb_registry.registry_ownership_status=pending 以及 registry_tier_delivered=null。请保留 request_id 并调用 GET /v3/session/{request_id}/decision/，直到 registry_checks[0].company.fetch_status 解析完成。Didit 会自动完成报告，并在准备就绪后按实际投递的等级扣费。处于待处理状态时请勿重复购买；每次新的 POST 都会创建一个单独的请求。", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistryCandidateRequest" }, "example": { "kyb_response_id": "69aeeb95febb0f1704042259", "vendor_data": "company-1234" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/kyb/ubo/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"kyb_response_id\": \"69aeeb95febb0f1704042259\",\n \"vendor_data\": \"company-1234\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.kyb.list_ubos(\n kyb_response_id=\"69aeeb95febb0f1704042259\",\n vendor_data=\"company-1234\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.kyb.listUbos({\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.KYB.ListUBOs(ctx, didit.KYBRegistryCandidateRequest{\n\tKYBResponseID: \"69aeeb95febb0f1704042259\",\n\tVendorData: didit.String(\"company-1234\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.KYBRegistryCandidateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.kyb().listUbos(KYBRegistryCandidateRequest.builder()\n .kybResponseId(\"69aeeb95febb0f1704042259\")\n .vendorData(\"company-1234\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "kyb->listUbos([\n 'kyb_response_id' => '69aeeb95febb0f1704042259',\n 'vendor_data' => 'company-1234',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.kyb.list_ubos(\n kyb_response_id: \"69aeeb95febb0f1704042259\",\n vendor_data: \"company-1234\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Kyb.ListUbosAsync(new KYBRegistryCandidateRequest\n{\n KybResponseId = \"69aeeb95febb0f1704042259\",\n VendorData = \"company-1234\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "返回企业报告并按实际交付的等级计费。仍在准备中的股权结构报告可能会返回 202；请保留 request_id 以检索其已保存的决策。", "content": { "application/json": { "schema": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "为此检索创建的企业会话 ID。如果在响应返回后公司登记信息才解析完成，已存储的记录（在控制台中可见）将持续更新。" }, "registry_tier_requested": { "type": "string", "enum": [ "basic", "shareholders", "ubo" ], "description": "此 endpoint 销售的等级：针对 select 的 `basic` (Lite)、`shareholders`、`ubo`。" }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "实际交付并计费的等级。当该国家/地区的公司登记不包含股权结构数据、登记机构没有该公司的股权结构记录，或 `ubo` 请求的解析报告未将任何自然人列为实际受益人时，该等级会低于请求的等级。", "nullable": true }, "kyb_registry": { "type": "object", "description": "完整的公司登记档案。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Didit 为此企业记录分配的 ID。" }, "node_id": { "type": "string", "example": "feature_kyb_registry" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review" ], "description": "Didit 对公司登记核验的评估（例如，当企业在登记处中处于非活跃状态或无法获取股权结构数据时为 `In Review`）。" }, "registry_status": { "type": "string", "nullable": true, "enum": [ "active", "dissolved", "deregistered", "see full details", "authorised", "appointed representative", "unauthorised", "inactive", "no longer authorised", "closed", "struck off", null ], "description": "公司登记机构报告的归一化企业状态。" }, "data_resolved": { "type": "boolean", "description": "公司登记处返回完整资料后为 `true`。轮询后登记处仍在处理中时为 `false`，一旦登记处处理完成，存储的记录将自动补充完整。" }, "company_name": { "type": "string", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "example": "00445790" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2。", "example": "GB" }, "region": { "type": "string", "nullable": true, "description": "登记属于地区性时的行政区划代码（例如 `US-CA` 对应 `CA`）；否则为空。" }, "company_type": { "type": "string", "nullable": true, "example": "Public Limited Company" }, "incorporation_date": { "type": "string", "format": "date", "nullable": true, "example": "1947-11-27" }, "registered_address": { "type": "string", "nullable": true, "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA" }, "tax_number": { "type": "string", "nullable": true, "example": "GB412 8925 93" }, "risk_level": { "type": "string", "nullable": true, "description": "公司登记所报告的风险等级（如可用）。" }, "verification_status": { "type": "string", "enum": [ "verified", "failed", "unknown" ], "nullable": true, "description": "跨司法管辖区验证状态：当公司登记状态确认存续（`active`）时为 `verified`；当其显示公司不再存续（例如 `dissolved`）时为 `failed`；否则为 `unknown`。对于非来自公司登记且选择仍处于 `pending` 状态的公司，该值为 `null`。" }, "is_from_registry": { "type": "boolean", "description": "对于此 endpoint 始终为 `true`，该档案从官方登记机构检索获取。" }, "fetch_status": { "type": "string", "enum": [ "pending", "resolved" ], "description": "公司登记获取生命周期。由 `data_resolved` 镜像。" }, "alternative_names": { "type": "string", "nullable": true, "description": "上报时的替代名称、商业名称、曾用名或原始语言公司名称（文本格式）。" }, "nature_of_business": { "type": "string", "nullable": true, "description": "活动描述或分类代码（如有报告）。" }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "nullable": true, "description": "字符串形式的十进制金额（若有上报）。" }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "报告的 ISO 4217 代码（如有）。" }, "website": { "type": "string", "nullable": true, "example": "https://www.tesco.com/" }, "email": { "type": "string", "nullable": true, "example": "customer.service@tesco.co.uk" }, "phone": { "type": "string", "nullable": true, "example": "03301231688" }, "legal_entity_identifier": { "type": "string", "nullable": true, "description": "LEI（若已上报）。" }, "location_of_registration": { "type": "string", "nullable": true, "description": "企业注册所在的登记机构/司法管辖区（如有报告）。" }, "vat_number": { "type": "string", "nullable": true, "description": "欧盟增值税号，在托管登记步骤中收集或随后编辑时提供。在选择时通常尚未设置。增值税号和税号核验会在终端用户在托管流程中提交登记步骤时运行。" }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "在登记提交时验证增值税号（若无，则为 `tax_number`）的结果。`valid` / `invalid`：由相应国家/地区的官方登记处判定（欧盟 VIES、挪威、瑞士、巴西、哥伦比亚、哥斯达黎加、厄瓜多尔、巴拉圭；波兰还由其国内增值税登记册判定）。`format_valid` / `invalid_format`：在无法查询登记处时，由该国家/地区的格式和校验位规则判定。`could_not_validate`：登记处不可用。`not_applicable`：无号码、无登记处或规则的国家/地区，或者沙盒会话。" }, "vat_validated_number": { "type": "string", "nullable": true, "description": "已核验的号码，格式以数据源所知为准（例如从法国 SIREN 或荷兰 RSIN 派生的增值税号）。若未运行核验，则为 `null`。" }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "判定 `vat_validation_status` 的来源：官方登记，或 `format_rules`。未运行任何检查时为 `null`。" }, "vat_validated_name": { "type": "string", "nullable": true, "description": "向验证该号码的数据源登记的名称（如果该数据源公开名称）。仅当状态为 `valid` 时设置。" }, "vat_validated_address": { "type": "string", "nullable": true, "description": "核验该号码的数据源中登记的地址（若该数据源披露）。仅在状态为 `valid` 时设置。" }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "检查的时间戳。未运行检查时为 `null`。" }, "financial_summary": { "type": "object", "nullable": true, "description": "公司登记所报告的股份/资本详情（币种、总股数、股份类别，如可用）。" }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "MELISSA BETHELL" }, "designation": { "type": "string", "nullable": true, "description": "原始登记处的职务名称（例如 `Director`、`Secretary`）。" }, "role": { "type": "string", "description": "根据职务衍生出的归一化角色。包含完整的 17 个值的模型集；该 endpoint 上的登记解析通常会输出 director、non_executive_director、secretary、chairman 或 company_officer。", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "company_officer", "settlor", "protector", "investor", "other" ] }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean", "description": "当公司登记处将该任命标记为已辞任时为 `false`。" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ], "description": "关联的 KYC 会话状态（若已为此负责人发起）；否则为 `null`。" }, "kyc_session_url": { "type": "string", "nullable": true, "description": "关联 KYC 会话的验证链接（如果存在）。" }, "first_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的名字；并非从全名中推断。" }, "last_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的姓氏。" }, "address": { "type": "string", "nullable": true, "description": "登记处报告的官员地址。" }, "appointment_date": { "type": "string", "nullable": true, "description": "管理人员被任命的日期。", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "任期结束的日期（若有报告）。", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "公司登记报告的完整出生日期。如果仅已知出生年份或月份，则为 null。", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "公司登记所报告的出生年份，包括完整日期不可用的情况。" }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "公司登记所报告的出生月份。仅知晓年份时为 null。" } } }, "description": "从公司登记中提取的董事、秘书和其他高管。" }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "所有者是自然人还是企业实体。" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "归一化的角色（例如 `ubo`、`shareholder`）。" }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "公司登记报告的股权范围下限（例如 `25%`）。" }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "公司登记报告的股权结构区间上限。" }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "nullable": true, "enum": [ "Approved", "Declined", "Pending", null ] }, "kyc_session_url": { "type": "string", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "解析出的股权百分比（上限值，回退为下限值）。" }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "完整的出生日期（如有报告）。", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "有报告时的委任日期。", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } }, "description": "从登记处提取的实际受益人/重大控制权人。当登记处未公开股权结构时可能为空。" }, "addresses": { "type": "array", "nullable": true, "description": "登记处注明的每个地址，采用标准规范格式。如果未注明，则为 null。", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "登记机构对企业进行分类的业务活动，采用一种规范化格式。若未注明则为 null。", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "公司登记备案日期（如可用）。年度申报表和大会使用 last_annual_return_date 与 last_agm_date；它们与财务账目不同。" }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "nullable": true, "description": "在此 endpoint 上始终为 `null`（终端用户编辑公司登记数据时由托管 KYB 流程使用）。" }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true, "description": "在此 endpoint 上始终为 `null`。" }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true, "description": "当控制台审核员随后编辑该记录时设置。" }, "is_editable": { "type": "boolean", "description": "来自公司登记的数据是否仍可在托管流程/控制台中进行编辑。" }, "registry_tier_delivered": { "type": "string", "enum": [ "basic", "shareholders", "ubo", null ], "description": "与顶级 `registry_tier_delivered` 相同。", "nullable": true }, "registry_ownership_status": { "type": "string", "nullable": true, "enum": [ "not_requested", "delivered", "not_held", "unavailable", "pending", null ], "description": "当股权结构数据返回时为 `delivered`；当股权登记处已响应但未列出此企业时为 `not_held`（参见 `registry_data.ownership_error`）；当请求了股权结构等级但登记处没有此企业的数据或无法查询时为 `unavailable`（参见 `registry_data.ownership_error`）；当股权结构部分尚未从登记处检索完成且 Didit 仍在处理时为 `pending`；在 Lite 等级上为 `not_requested`。" }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "工作流订购的公司登记等级：`basic`、`shareholders` 或 `ubo`。也可在 `ownership.tier_requested` 中查看。" }, "registry_monitoring": { "type": "object", "nullable": true, "description": "该企业的最新登记监控，不存在时为 `null`。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "监控器监视的企业字段。" } } } } }, "vendor_data": { "type": "string", "nullable": true, "description": "回显您发送的 `vendor_data`。" }, "metadata": { "type": "object", "nullable": true, "description": "您发送的 `metadata` 回显。" }, "created_at": { "type": "string", "format": "date-time" } } }, "examples": { "Resolved company": { "summary": "完整的公司登记档案（为简明起见截断了管理人员列表）", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "f1e2d3c4-b5a6-4789-9c0d-1e2f3a4b5c6d", "node_id": "feature_kyb_registry", "status": "In Review", "registry_status": "active", "data_resolved": true, "company_name": "Tesco PLC", "registration_number": "00445790", "country_code": "GB", "region": "", "company_type": "Public Limited Company", "incorporation_date": "1947-11-27", "registered_address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "tax_number": "GB412 8925 93", "risk_level": "low risk", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "TESCO STORES (HOLDINGS) PUBLIC LIMITED COMPANY", "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": "https://www.tesco.com/", "email": "customer.service@tesco.co.uk", "phone": "03301231688", "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": { "currency": "Pound (£)", "total_number_of_shares": "8174378721", "meta_detail": { "Class_Of_Share": "Ordinary" } }, "officers": [ { "uuid": "a1b2c3d4-e5f6-4789-9a0b-1c2d3e4f5a6b", "name": "CHRISTOPHER JON TAYLOR", "designation": "Secretary", "role": "secretary", "nationality": null, "is_active": true, "kyc_status": null, "kyc_session_url": null }, { "uuid": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c", "name": "MELISSA BETHELL", "designation": "Director", "role": "director", "nationality": "British", "is_active": true, "kyc_status": null, "kyc_session_url": null } ], "beneficial_owners": [], "addresses": [ { "address": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, United Kingdom, AL7 1GA", "type": "legal_entity_registry_address", "description": "registered office address" } ], "industries": null, "accounts": { "last_account": "26 February 2025", "next_account": "26 February 2026", "due_by_date": "26 August 2026" }, "registry_data": { "ubo_resolution": { "parent_chain": [], "subsidiaries": [], "unresolved": [] } }, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00" } } } } } }, "400": { "description": "验证错误。字段级问题使用 DRF 的标准外层结构。", "content": { "application/json": { "examples": { "Missing kyb_response_id": { "summary": "`kyb_response_id` 为必填项", "value": { "kyb_response_id": [ "This field is required." ] } }, "save_api_request=false rejected": { "summary": "选择内容始终持久化保存", "value": { "save_api_request": [ "KYB registry select must be saved so billing and retrieval can be tracked." ] } } } } } }, "403": { "description": "权限被拒绝。当缺少 `x-api-key` 请求头或调用组织的余额无法覆盖此次调用时返回；错误、已撤销或已过期的密钥返回 `401`。缺少密钥时返回 `403` 及 `{\"detail\": ...}`；错误、已撤销或已过期的密钥返回 `401`。额度不足时会在进行任何筛查或服务商调用之前返回 `403` 及 `{\"error\": ...}`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效/已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付本次调用", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "429": { "description": "超出速率限制。POST/PATCH/DELETE endpoint 每个 API 密钥每分钟共享 300 次写入请求的额度（交易创建和事件摄入具有单独的 600 次额度）。响应包含 `X-RateLimit-Limit`、`X-RateLimit-Remaining`、`X-RateLimit-Reset` 和 `Retry-After` 响应头。", "content": { "application/json": { "examples": { "Write rate limit exceeded": { "summary": "当前分钟内的写入请求超过 300 次", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } }, "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "202": { "description": "报告已接受并仍在处理中。当报告仍在准备中时，endpoint 返回 202 Accepted、kyb_registry.fetch_status=pending 以及 registry_tier_delivered=null。请保留 request_id 并轮询调用 GET /v3/session/{request_id}/decision/，直至 registry_checks[0].company.fetch_status 解决。Didit 会自动完成报告，并在报告准备就绪后按交付的等级扣费。处于待处理状态时请勿重复购买；每个新的 POST 都会创建一个单独的请求。", "content": { "application/json": { "schema": { "$ref": "#/paths/~1v3~1kyb~1ubo~1/post/responses/200/content/application~1json/schema" }, "examples": { "Pending (registry still resolving)": { "summary": "股权结构报告仍在处理中；获取已保存的决策", "value": { "request_id": "9d4f2c7a-1b3e-4a5c-8d6f-0e9a8b7c6d5e", "kyb_registry": { "uuid": "7c0a4f7e-2b1d-4f6a-9c3e-8d5b2a1f0e9d", "node_id": "feature_kyb_registry", "status": "Not Finished", "registry_status": null, "data_resolved": false, "company_name": "Example Holdings Limited", "registration_number": "12345678", "country_code": "HK", "region": null, "company_type": null, "incorporation_date": null, "registered_address": null, "tax_number": null, "risk_level": null, "verification_status": null, "is_from_registry": true, "fetch_status": "pending", "alternative_names": null, "nature_of_business": null, "registered_capital": null, "registered_capital_amount": null, "registered_capital_currency": null, "website": null, "email": null, "phone": null, "legal_entity_identifier": null, "location_of_registration": null, "financial_summary": {}, "officers": [], "beneficial_owners": [], "addresses": null, "industries": null, "accounts": null, "registry_data": {}, "user_provided_data": null, "confirmed_by_user_at": null, "last_console_edit_at": null, "is_editable": true, "registry_tier_delivered": null, "registry_ownership_status": "pending" }, "vendor_data": "company-1234", "metadata": null, "created_at": "2026-06-11T10:45:00.000000+00:00", "registry_tier_delivered": null, "registry_tier_requested": "ubo" } } } } } } } } }, "/v3/id-verification/wallets/": { "get": { "operationId": "list_wallets", "x-didit-sdk": { "resource": "id_wallets", "method": "list", "auth": "api_key", "server": true }, "description": "每个数字身份钱包及其启动 endpoint、支持的国家/地区、必填字段，以及该应用当前是否可以在此环境中启动它。列出并不代表已上线。", "summary": "列出数字身份钱包", "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletCatalogResponse" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "缺少凭据（x-api-key 或 Authorization: Bearer）。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request GET \\\n --url https://verification.didit.me/v3/id-verification/wallets/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.list()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.list();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.List(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().list();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->list();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.list\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.ListAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/verifications/{request_id}/": { "get": { "operationId": "get_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "retrieve_verification", "auth": "api_key", "server": true }, "description": "钱包验证的状态和结果：验证通过后为规范化身份和钱包自身属性，已拒绝后为错误代码，待处理时为下一步操作。超过 expires_at 的验证判定为超时。", "summary": "获取钱包验证", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "start endpoint 返回的 request_id。", "required": true } ], "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "ftn", "name": "Finnish Trust Network", "issuing_authority": "Finnish banks and mobile operators (FTN)" }, "country": "FIN", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "缺少凭据（x-api-key 或 Authorization: Bearer）。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 not_found：此应用下没有任何钱包验证具有该 request_id。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request GET \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.retrieve_verification(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.retrieveVerification(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.RetrieveVerification(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().retrieveVerification(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->retrieveVerification('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.retrieve_verification(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.RetrieveVerificationAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/verifications/{request_id}/poll/": { "post": { "operationId": "poll_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "poll_verification", "auth": "api_key", "server": true }, "description": "Smart-ID 和 Mobile-ID：向提供商询问用户是确认、拒绝还是超时未响应提示，并在用户确认时核验签名的身份。重定向钱包通过用户的浏览器完成，因此对于这些钱包，此操作仅回读验证结果。随后返回当前的验证状态。", "summary": "轮询钱包验证", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "start endpoint 返回的 request_id。", "required": true } ], "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "smart_id", "name": "Smart-ID", "issuing_authority": "SK ID Solutions" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "in_app", "simulated": true, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "confirm_in_app", "verification_code": "1234", "poll_interval_seconds": 2 }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "缺少凭据（x-api-key 或 Authorization: Bearer）。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 not_found：此应用下没有任何钱包验证具有该 request_id。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/poll/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.poll_verification(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.pollVerification(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.PollVerification(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().pollVerification(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->pollVerification('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.poll_verification(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.PollVerificationAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/verifications/{request_id}/cancel/": { "post": { "operationId": "cancel_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "cancel_verification", "auth": "api_key", "server": true }, "description": "撤回待处理的验证：该验证将被拒绝为已取消且永不计费。已决策的验证将原样返回。Smart-ID 和 Mobile-ID：在轮询检查登录期间到达的取消请求将等待该轮询数秒，然后拒绝该验证；或者如果用户已确认，则返回已核验状态。用户当前正在完成的验证无法取消（409 verification_in_progress，附带 Retry-After）：请在相应秒数后重试以读取其结果。", "summary": "取消钱包验证", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "start endpoint 返回的 request_id。", "required": true } ], "tags": [ "Digital ID wallets" ], "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "ftn", "name": "Finnish Trust Network", "issuing_authority": "Finnish banks and mobile operators (FTN)" }, "country": "FIN", "status": "Declined", "outcome": "cancelled", "error": "cancelled_by_customer", "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": null, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "缺少凭据（x-api-key 或 Authorization: Bearer）。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 not_found：此应用下没有任何钱包验证具有该 request_id。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 verification_in_progress：用户当前正在完成此登录。Retry-After 请求头指示了何时重试；重试将返回已有决策的验证结果。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/cancel/ \\\n --header 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.cancel_verification(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.cancelVerification(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.CancelVerification(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().cancelVerification(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->cancelVerification('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.cancel_verification(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.CancelVerificationAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/id-verification/wallets/mitid/": { "post": { "operationId": "start_mitid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_mitid", "auth": "api_key", "server": true }, "description": "在无需任何工作流的情况下启动 MitID 登录（丹麦数字政府局；DNK）。仅在身份验证成功时计费一次。响应包含 next_action.type=redirect 以及引导用户浏览器跳转的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或从 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系服务商。", "summary": "开始 MitID 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartRequest" }, "example": { "country": "DNK", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "mitid", "name": "MitID", "issuing_authority": "Danish Agency for Digital Government" }, "country": "DNK", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/mitid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"DNK\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_mitid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"DNK\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startMitid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DNK\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartMitid(ctx, didit.IDWalletsStartMitidParams{\n\tBody: didit.DigitalIDWalletAPIMitidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIMitidWalletVerificationStartCountryEnum(\"DNK\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiMitidWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiMitidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startMitid(DigitalIdWalletApiMitidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiMitidWalletVerificationStartCountryEnum.of(\"DNK\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startMitid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'DNK',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_mitid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DNK\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartMitidAsync(new DigitalIdWalletApiMitidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiMitidWalletVerificationStartCountryEnum(\"DNK\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "mitid" } }, "/v3/id-verification/wallets/bankid-se/": { "post": { "operationId": "start_bankid_se_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_bankid_se", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 BankID (SWE) 登录（Finansiell ID-Teknik / 银行联盟；SWE）。仅在身份完成验证时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系提供商。", "summary": "开始 BankID (SWE) 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidSeWalletVerificationStartRequest" }, "example": { "country": "SWE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidSeWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidSeWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "bankid_se", "name": "BankID", "issuing_authority": "Finansiell ID-Teknik / bank consortium" }, "country": "SWE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/bankid-se/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"SWE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_bankid_se(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"SWE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBankidSe({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBankidSe(ctx, didit.IDWalletsStartBankidSeParams{\n\tBody: didit.DigitalIDWalletAPIBankidSeWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryEe9enum(\"SWE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBankidSeWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryEe9Enum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBankidSe(DigitalIdWalletApiBankidSeWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryEe9Enum.of(\"SWE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBankidSe([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'SWE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_bankid_se(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBankidSeAsync(new DigitalIdWalletApiBankidSeWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryEe9Enum(\"SWE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "bankid_se" } }, "/v3/id-verification/wallets/bankid-no/": { "post": { "operationId": "start_bankid_no_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_bankid_no", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 BankID (NOR) 登录（BankID BankAxept AS；NOR）。仅在身份完成验证时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系提供商。", "summary": "开始 BankID (NOR) 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidNoWalletVerificationStartRequest" }, "example": { "country": "NOR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidNoWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidNoWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "bankid_no", "name": "BankID", "issuing_authority": "BankID BankAxept AS" }, "country": "NOR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/bankid-no/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NOR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_bankid_no(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NOR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBankidNo({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBankidNo(ctx, didit.IDWalletsStartBankidNoParams{\n\tBody: didit.DigitalIDWalletAPIBankidNoWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryAfcEnum(\"NOR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBankidNoWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryAfcEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBankidNo(DigitalIdWalletApiBankidNoWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryAfcEnum.of(\"NOR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBankidNo([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NOR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_bankid_no(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBankidNoAsync(new DigitalIdWalletApiBankidNoWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryAfcEnum(\"NOR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "bankid_no" } }, "/v3/id-verification/wallets/vipps/": { "post": { "operationId": "start_vipps_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_vipps", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 Vipps 登录（Vipps MobilePay / BankID NO；NOR）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的 URL；用户返回至附加了 request_id 和 result 的 return_url。通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会与提供商通信。", "summary": "开始 Vipps 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiVippsWalletVerificationStartRequest" }, "example": { "country": "NOR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiVippsWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiVippsWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "vipps", "name": "Vipps", "issuing_authority": "Vipps MobilePay / BankID NO" }, "country": "NOR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/vipps/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NOR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_vipps(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NOR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startVipps({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartVipps(ctx, didit.IDWalletsStartVippsParams{\n\tBody: didit.DigitalIDWalletAPIVippsWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryAfcEnum(\"NOR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountryAfcEnum;\nimport me.didit.types.DigitalIdWalletApiVippsWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startVipps(DigitalIdWalletApiVippsWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryAfcEnum.of(\"NOR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startVipps([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NOR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_vipps(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartVippsAsync(new DigitalIdWalletApiVippsWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryAfcEnum(\"NOR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "vipps" } }, "/v3/id-verification/wallets/buypass/": { "post": { "operationId": "start_buypass_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_buypass", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 Buypass ID 登录（Buypass AS；NOR）。仅在身份完成验证时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系提供商。", "summary": "开始 Buypass ID 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBuypassWalletVerificationStartRequest" }, "example": { "country": "NOR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBuypassWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBuypassWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "buypass", "name": "Buypass ID", "issuing_authority": "Buypass AS" }, "country": "NOR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/buypass/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NOR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_buypass(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NOR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBuypass({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBuypass(ctx, didit.IDWalletsStartBuypassParams{\n\tBody: didit.DigitalIDWalletAPIBuypassWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryAfcEnum(\"NOR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBuypassWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryAfcEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBuypass(DigitalIdWalletApiBuypassWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryAfcEnum.of(\"NOR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBuypass([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NOR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_buypass(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NOR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBuypassAsync(new DigitalIdWalletApiBuypassWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryAfcEnum(\"NOR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "buypass" } }, "/v3/id-verification/wallets/itsme/": { "post": { "operationId": "start_itsme_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_itsme", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 itsme 登录（比利时 Mobile ID；BEL、LUX、NLD）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带追加的 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿从 URL 中读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系服务商。", "summary": "发起 itsme 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartRequest" }, "example": { "country": "BEL", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "itsme", "name": "itsme", "issuing_authority": "Belgian Mobile ID" }, "country": "BEL", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/itsme/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"BEL\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_itsme(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"BEL\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startItsme({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BEL\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartItsme(ctx, didit.IDWalletsStartItsmeParams{\n\tBody: didit.DigitalIDWalletAPIItsmeWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIItsmeWalletVerificationStartCountryEnum(\"BEL\"),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiItsmeWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startItsme(DigitalIdWalletApiItsmeWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum.of(\"BEL\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startItsme([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'BEL',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_itsme(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BEL\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartItsmeAsync(new DigitalIdWalletApiItsmeWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"BEL\",\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "itsme" } }, "/v3/id-verification/wallets/idin/": { "post": { "operationId": "start_idin_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_idin", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 iDIN 登录（荷兰银行 (Currence iDIN)；NLD）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带追加的 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿从 URL 中读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系服务商。", "summary": "发起 iDIN 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartRequest" }, "example": { "country": "NLD", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "idin", "name": "iDIN", "issuing_authority": "Dutch banks (Currence iDIN)" }, "country": "NLD", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/idin/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"NLD\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_idin(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"NLD\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startIdin({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NLD\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartIdin(ctx, didit.IDWalletsStartIdinParams{\n\tBody: didit.DigitalIDWalletAPIIdinWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIIdinWalletVerificationStartCountryEnum(\"NLD\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiIdinWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiIdinWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startIdin(DigitalIdWalletApiIdinWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiIdinWalletVerificationStartCountryEnum.of(\"NLD\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startIdin([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'NLD',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_idin(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"NLD\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartIdinAsync(new DigitalIdWalletApiIdinWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiIdinWalletVerificationStartCountryEnum(\"NLD\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "idin" } }, "/v3/id-verification/wallets/ftn/": { "post": { "operationId": "start_ftn_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_ftn", "auth": "api_key", "server": true }, "description": "在无需任何工作流的情况下启动 Finnish Trust Network 登录（芬兰各银行与移动运营商 (FTN)；FIN）。仅在身份验证成功时计费一次。响应包含 next_action.type=redirect 以及引导用户浏览器跳转的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或从 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系服务商。", "summary": "开始 Finnish Trust Network 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartRequest" }, "example": { "country": "FIN", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "ftn", "name": "Finnish Trust Network", "issuing_authority": "Finnish banks and mobile operators (FTN)" }, "country": "FIN", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"FIN\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_ftn(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"FIN\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startFtn({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FIN\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartFtn(ctx, didit.IDWalletsStartFtnParams{\n\tBody: didit.DigitalIDWalletAPIFtnWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIFtnWalletVerificationStartCountryEnum(\"FIN\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiFtnWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiFtnWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startFtn(DigitalIdWalletApiFtnWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiFtnWalletVerificationStartCountryEnum.of(\"FIN\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startFtn([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'FIN',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_ftn(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FIN\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartFtnAsync(new DigitalIdWalletApiFtnWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiFtnWalletVerificationStartCountryEnum(\"FIN\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "ftn" } }, "/v3/id-verification/wallets/personalausweis/": { "post": { "operationId": "start_personalausweis_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_personalausweis", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 Personalausweis 登录（Bundesministerium des Innern (eID)；DEU）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的 URL；用户返回至附加了 request_id 和 result 的 return_url。通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会与提供商通信。", "summary": "开始 Personalausweis 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest" }, "example": { "country": "DEU", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "personalausweis", "name": "Personalausweis", "issuing_authority": "Bundesministerium des Innern (eID)" }, "country": "DEU", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/personalausweis/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"DEU\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_personalausweis(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"DEU\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startPersonalausweis({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DEU\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartPersonalausweis(ctx, didit.IDWalletsStartPersonalausweisParams{\n\tBody: didit.DigitalIDWalletAPIPersonalausweisWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIPersonalausweisWalletVerificationStartCountryEnum(\"DEU\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startPersonalausweis(DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum.of(\"DEU\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startPersonalausweis([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'DEU',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_personalausweis(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"DEU\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartPersonalausweisAsync(new DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum(\"DEU\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "personalausweis" } }, "/v3/id-verification/wallets/frejaid/": { "post": { "operationId": "start_frejaid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_frejaid", "auth": "api_key", "server": true }, "description": "在无需任何工作流的情况下启动 Freja eID 登录（Freja eID Group；SWE）。仅在身份验证成功时计费一次。响应包含 next_action.type=redirect 以及引导用户浏览器跳转的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或从 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系服务商。", "summary": "开始 Freja eID 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFrejaidWalletVerificationStartRequest" }, "example": { "country": "SWE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFrejaidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFrejaidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "frejaid", "name": "Freja eID", "issuing_authority": "Freja eID Group" }, "country": "SWE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/frejaid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"SWE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_frejaid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"SWE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startFrejaid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartFrejaid(ctx, didit.IDWalletsStartFrejaidParams{\n\tBody: didit.DigitalIDWalletAPIFrejaidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryEe9enum(\"SWE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountryEe9Enum;\nimport me.didit.types.DigitalIdWalletApiFrejaidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startFrejaid(DigitalIdWalletApiFrejaidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryEe9Enum.of(\"SWE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startFrejaid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'SWE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_frejaid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"SWE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartFrejaidAsync(new DigitalIdWalletApiFrejaidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryEe9Enum(\"SWE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "frejaid" } }, "/v3/id-verification/wallets/uae-pass/": { "post": { "operationId": "start_uae_pass_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_uae_pass", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 UAE PASS 登录（UAE Digital Government Authority；ARE）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的 URL；用户返回至附加了 request_id 和 result 的 return_url。通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会与提供商通信。", "summary": "开始 UAE PASS 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartRequest" }, "example": { "country": "ARE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "uae_pass", "name": "UAE PASS", "issuing_authority": "UAE Digital Government Authority" }, "country": "ARE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/uae-pass/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"ARE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_uae_pass(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"ARE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startUaePass({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ARE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartUaePass(ctx, didit.IDWalletsStartUaePassParams{\n\tBody: didit.DigitalIDWalletAPIUaePassWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIUaePassWalletVerificationStartCountryEnum(\"ARE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiUaePassWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startUaePass(DigitalIdWalletApiUaePassWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum.of(\"ARE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startUaePass([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'ARE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_uae_pass(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ARE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartUaePassAsync(new DigitalIdWalletApiUaePassWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum(\"ARE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "uae_pass" } }, "/v3/id-verification/wallets/govbr/": { "post": { "operationId": "start_govbr_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_govbr", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 gov.br 登录（Governo Federal do Brasil；BRA）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的 URL；用户返回至附加了 request_id 和 result 的 return_url。通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会与提供商通信。", "summary": "发起 gov.br 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartRequest" }, "example": { "country": "BRA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "govbr", "name": "gov.br", "issuing_authority": "Governo Federal do Brasil" }, "country": "BRA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/govbr/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"BRA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_govbr(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"BRA\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startGovbr({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BRA\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartGovbr(ctx, didit.IDWalletsStartGovbrParams{\n\tBody: didit.DigitalIDWalletAPIGovbrWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIGovbrWalletVerificationStartCountryEnum(\"BRA\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiGovbrWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startGovbr(DigitalIdWalletApiGovbrWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum.of(\"BRA\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startGovbr([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'BRA',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_govbr(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"BRA\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartGovbrAsync(new DigitalIdWalletApiGovbrWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum(\"BRA\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "govbr" } }, "/v3/id-verification/wallets/oneid/": { "post": { "operationId": "start_oneid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_oneid", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 OneID 登录（OneID（英国银行验证的身份）；GBR）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的 URL；用户返回至附加了 request_id 和 result 的 return_url。通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会与提供商通信。", "summary": "开始 OneID 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiOneidWalletVerificationStartRequest" }, "example": { "country": "GBR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiOneidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiOneidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "oneid", "name": "OneID", "issuing_authority": "OneID (UK bank-verified identity)" }, "country": "GBR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/oneid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"GBR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_oneid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"GBR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startOneid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartOneid(ctx, didit.IDWalletsStartOneidParams{\n\tBody: didit.DigitalIDWalletAPIOneidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountry520enum(\"GBR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountry520Enum;\nimport me.didit.types.DigitalIdWalletApiOneidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startOneid(DigitalIdWalletApiOneidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountry520Enum.of(\"GBR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startOneid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'GBR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_oneid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartOneidAsync(new DigitalIdWalletApiOneidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountry520Enum(\"GBR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "oneid" } }, "/v3/id-verification/wallets/govuk-wallet/": { "post": { "operationId": "start_govuk_wallet_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_govuk_wallet", "auth": "api_key", "server": true }, "description": "在无需任何工作流的情况下启动 GOV.UK Wallet 登录（英国政府数字服务局；GBR）。仅在身份验证成功时计费一次。响应包含 next_action.type=redirect 以及引导用户浏览器跳转的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或从 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系服务商。", "summary": "开始 GOV.UK Wallet 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovukWalletWalletVerificationStartRequest" }, "example": { "country": "GBR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovukWalletWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGovukWalletWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "govuk_wallet", "name": "GOV.UK Wallet", "issuing_authority": "UK Government Digital Service" }, "country": "GBR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/govuk-wallet/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"GBR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_govuk_wallet(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"GBR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startGovukWallet({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartGovukWallet(ctx, didit.IDWalletsStartGovukWalletParams{\n\tBody: didit.DigitalIDWalletAPIGovukWalletWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountry520enum(\"GBR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountry520Enum;\nimport me.didit.types.DigitalIdWalletApiGovukWalletWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startGovukWallet(DigitalIdWalletApiGovukWalletWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountry520Enum.of(\"GBR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startGovukWallet([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'GBR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_govuk_wallet(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"GBR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartGovukWalletAsync(new DigitalIdWalletApiGovukWalletWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountry520Enum(\"GBR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "govuk_wallet" } }, "/v3/id-verification/wallets/smart-id/": { "post": { "operationId": "start_smart_id_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_smart_id", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 Smart-ID 登录（SK ID Solutions；EST、LVA、LTU、BEL）。仅在身份验证通过时计费一次。响应包含 next_action.type=confirm_in_app 以及向用户展示的比对码；用户在应用中确认比对码并输入其 PIN（切勿收集 PIN）。每隔 poll_interval_seconds 轮询一次 POST /v3/id-verification/wallets/verifications/{request_id}/poll/，或依赖 Webhook：Didit 也会在后台进行轮询。沙盒应用将获得确定性模拟（simulated: true），绝不会与提供商通信。", "summary": "开始 Smart-ID 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartRequest" }, "example": { "country": "EST", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "personal_code": "00000000000" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "smart_id", "name": "Smart-ID", "issuing_authority": "SK ID Solutions" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "in_app", "simulated": true, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "confirm_in_app", "verification_code": "1234", "poll_interval_seconds": 2 }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/smart-id/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"EST\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"personal_code\": \"00000000000\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_smart_id(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"EST\",\n personal_code=\"00000000000\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startSmartId({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartSmartID(ctx, didit.IDWalletsStartSmartIDParams{\n\tBody: didit.DigitalIDWalletAPISmartIDWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPISmartIDWalletVerificationStartCountryEnum(\"EST\"),\n\t\tPersonalCode: \"00000000000\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiSmartIdWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startSmartId(DigitalIdWalletApiSmartIdWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum.of(\"EST\"))\n .personalCode(\"00000000000\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startSmartId([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'EST',\n 'personal_code' => '00000000000',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_smart_id(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartSmartIdAsync(new DigitalIdWalletApiSmartIdWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"EST\",\n PersonalCode = \"00000000000\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "smart_id" } }, "/v3/id-verification/wallets/mobile-id/": { "post": { "operationId": "start_mobile_id_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_mobile_id", "auth": "api_key", "server": true }, "description": "在无需任何工作流的情况下启动 Mobile-ID 登录（SK ID Solutions 联合国家移动运营商；EST、LTU）。仅在身份验证成功时计费一次。响应包含 next_action.type=confirm_in_app 以及要展示给用户的比对码；用户在应用中确认比对码并输入其 PIN（切勿收集 PIN）。每隔 poll_interval_seconds 轮询一次 POST /v3/id-verification/wallets/verifications/{request_id}/poll/，或者依赖 Webhook：Didit 也会在后台进行轮询。沙盒应用将获得确定性模拟（simulated: true），绝不会联系服务商。", "summary": "开始 Mobile-ID 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest" }, "example": { "country": "EST", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "personal_code": "00000000000", "phone_number": "+37200000000" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "mobile_id", "name": "Mobile-ID", "issuing_authority": "SK ID Solutions with the national mobile operators" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "in_app", "simulated": true, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "confirm_in_app", "verification_code": "1234", "poll_interval_seconds": 2 }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/mobile-id/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"EST\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"personal_code\": \"00000000000\",\n \"phone_number\": \"+37200000000\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_mobile_id(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"EST\",\n personal_code=\"00000000000\",\n phone_number=\"+37200000000\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startMobileId({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\",\n phone_number: \"+37200000000\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartMobileID(ctx, didit.IDWalletsStartMobileIDParams{\n\tBody: didit.DigitalIDWalletAPIMobileIDWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIMobileIDWalletVerificationStartCountryEnum(\"EST\"),\n\t\tPersonalCode: \"00000000000\",\n\t\tPhoneNumber: \"+37200000000\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiMobileIdWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startMobileId(DigitalIdWalletApiMobileIdWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum.of(\"EST\"))\n .personalCode(\"00000000000\")\n .phoneNumber(\"+37200000000\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startMobileId([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'EST',\n 'personal_code' => '00000000000',\n 'phone_number' => '+37200000000',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_mobile_id(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n personal_code: \"00000000000\",\n phone_number: \"+37200000000\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartMobileIdAsync(new DigitalIdWalletApiMobileIdWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"EST\",\n PersonalCode = \"00000000000\",\n PhoneNumber = \"+37200000000\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "mobile_id" } }, "/v3/id-verification/wallets/idcard-ee/": { "post": { "operationId": "start_idcard_ee_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_idcard_ee", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起爱沙尼亚身份证（Police and Border Guard Board (Estonia)；EST）登录。仅在身份完成验证时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系提供商。", "summary": "开始爱沙尼亚身份证验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartRequest" }, "example": { "country": "EST", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "idcard_ee", "name": "Estonian ID-card", "issuing_authority": "Police and Border Guard Board (Estonia)" }, "country": "EST", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/idcard-ee/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"EST\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_idcard_ee(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"EST\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startIdcardEe({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartIdcardEe(ctx, didit.IDWalletsStartIdcardEeParams{\n\tBody: didit.DigitalIDWalletAPIIdcardEeWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIIdcardEeWalletVerificationStartCountryEnum(\"EST\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiIdcardEeWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startIdcardEe(DigitalIdWalletApiIdcardEeWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum.of(\"EST\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startIdcardEe([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'EST',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_idcard_ee(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"EST\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartIdcardEeAsync(new DigitalIdWalletApiIdcardEeWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum(\"EST\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "idcard_ee" } }, "/v3/id-verification/wallets/eparaksts-mobile/": { "post": { "operationId": "start_eparaksts_mobile_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_eparaksts_mobile", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 eParaksts mobile 登录（LVRTC (Latvian State Radio and Television Centre)；LVA）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的 URL；用户返回至附加了 request_id 和 result 的 return_url。通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会与提供商通信。", "summary": "发起 eParaksts 移动端验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest" }, "example": { "country": "LVA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "eparaksts_mobile", "name": "eParaksts mobile", "issuing_authority": "LVRTC (Latvian State Radio and Television Centre)" }, "country": "LVA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/eparaksts-mobile/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"LVA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_eparaksts_mobile(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"LVA\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startEparakstsMobile({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"LVA\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartEparakstsMobile(ctx, didit.IDWalletsStartEparakstsMobileParams{\n\tBody: didit.DigitalIDWalletAPIEparakstsMobileWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIEparakstsMobileWalletVerificationStartCountryEnum(\"LVA\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startEparakstsMobile(DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum.of(\"LVA\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startEparakstsMobile([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'LVA',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_eparaksts_mobile(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"LVA\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartEparakstsMobileAsync(new DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum(\"LVA\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "eparaksts_mobile" } }, "/v3/id-verification/wallets/bankid-cz/": { "post": { "operationId": "start_bankid_cz_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_bankid_cz", "auth": "api_key", "server": true }, "description": "在没有任何工作流的情况下启动 Bank iD 登录（Bankovní identita, a.s.；CZE）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或从 Webhook 读取结果，切勿从 URL 读取。沙盒应用会获得确定性的模拟结果（simulated: true），绝不会联系服务商。", "summary": "开始 Bank iD 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidCzWalletVerificationStartRequest" }, "example": { "country": "CZE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidCzWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiBankidCzWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "bankid_cz", "name": "Bank iD", "issuing_authority": "Bankovní identita, a.s." }, "country": "CZE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/bankid-cz/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"CZE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_bankid_cz(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"CZE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startBankidCz({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartBankidCz(ctx, didit.IDWalletsStartBankidCzParams{\n\tBody: didit.DigitalIDWalletAPIBankidCzWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryE2dEnum(\"CZE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiBankidCzWalletVerificationStartRequest;\nimport me.didit.types.DigitalIdWalletApiCountryE2dEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startBankidCz(DigitalIdWalletApiBankidCzWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryE2dEnum.of(\"CZE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startBankidCz([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'CZE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_bankid_cz(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartBankidCzAsync(new DigitalIdWalletApiBankidCzWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryE2dEnum(\"CZE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "bankid_cz" } }, "/v3/id-verification/wallets/mojeid/": { "post": { "operationId": "start_mojeid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_mojeid", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 MojeID 登录（CZ.NIC；CZE）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的 URL；用户返回至附加了 request_id 和 result 的 return_url。通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会与提供商通信。", "summary": "开始 MojeID 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMojeidWalletVerificationStartRequest" }, "example": { "country": "CZE", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMojeidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiMojeidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "mojeid", "name": "MojeID", "issuing_authority": "CZ.NIC" }, "country": "CZE", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/mojeid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"CZE\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_mojeid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"CZE\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startMojeid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartMojeid(ctx, didit.IDWalletsStartMojeidParams{\n\tBody: didit.DigitalIDWalletAPIMojeidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPICountryE2dEnum(\"CZE\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiCountryE2dEnum;\nimport me.didit.types.DigitalIdWalletApiMojeidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startMojeid(DigitalIdWalletApiMojeidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiCountryE2dEnum.of(\"CZE\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startMojeid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'CZE',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_mojeid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"CZE\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartMojeidAsync(new DigitalIdWalletApiMojeidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiCountryE2dEnum(\"CZE\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "mojeid" } }, "/v3/id-verification/wallets/diia/": { "post": { "operationId": "start_diia_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_diia", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 Diia 登录（Ministry of Digital Transformation of Ukraine；UKR）。仅在身份完成验证时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系提供商。", "summary": "开始 Diia 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartRequest" }, "example": { "country": "UKR", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "diia", "name": "Diia", "issuing_authority": "Ministry of Digital Transformation of Ukraine" }, "country": "UKR", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/diia/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"UKR\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_diia(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"UKR\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startDiia({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"UKR\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartDiia(ctx, didit.IDWalletsStartDiiaParams{\n\tBody: didit.DigitalIDWalletAPIDiiaWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIDiiaWalletVerificationStartCountryEnum(\"UKR\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiDiiaWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startDiia(DigitalIdWalletApiDiiaWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum.of(\"UKR\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startDiia([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'UKR',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_diia(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"UKR\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartDiiaAsync(new DigitalIdWalletApiDiiaWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum(\"UKR\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "diia" } }, "/v3/id-verification/wallets/franceconnect/": { "post": { "operationId": "start_franceconnect_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_franceconnect", "auth": "api_key", "server": true }, "description": "在无需任何工作流的情况下启动 FranceConnect 登录（DINUM（法国政府）；FRA）。仅在身份验证成功时计费一次。响应包含 next_action.type=redirect 以及引导用户浏览器跳转的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或从 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系服务商。", "summary": "开始 FranceConnect 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartRequest" }, "example": { "country": "FRA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "franceconnect", "name": "FranceConnect", "issuing_authority": "DINUM (French state)" }, "country": "FRA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/franceconnect/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"FRA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_franceconnect(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"FRA\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startFranceconnect({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FRA\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartFranceconnect(ctx, didit.IDWalletsStartFranceconnectParams{\n\tBody: didit.DigitalIDWalletAPIFranceconnectWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIFranceconnectWalletVerificationStartCountryEnum(\"FRA\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiFranceconnectWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startFranceconnect(DigitalIdWalletApiFranceconnectWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum.of(\"FRA\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startFranceconnect([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'FRA',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_franceconnect(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"FRA\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartFranceconnectAsync(new DigitalIdWalletApiFranceconnectWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum(\"FRA\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "franceconnect" } }, "/v3/id-verification/wallets/audkenni/": { "post": { "operationId": "start_audkenni_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_audkenni", "auth": "api_key", "server": true }, "description": "在没有任何工作流的情况下启动 Auðkenni 登录（Auðkenni（冰岛电子身份证件）；ISL）。仅在身份验证通过时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器访问的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或从 Webhook 读取结果，切勿从 URL 读取。沙盒应用会获得确定性的模拟结果（simulated: true），绝不会联系服务商。", "summary": "开始 Auðkenni 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartRequest" }, "example": { "country": "ISL", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "audkenni", "name": "Auðkenni", "issuing_authority": "Auðkenni (Icelandic electronic ID)" }, "country": "ISL", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/audkenni/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"ISL\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_audkenni(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"ISL\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startAudkenni({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ISL\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartAudkenni(ctx, didit.IDWalletsStartAudkenniParams{\n\tBody: didit.DigitalIDWalletAPIAudkenniWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIAudkenniWalletVerificationStartCountryEnum(\"ISL\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiAudkenniWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startAudkenni(DigitalIdWalletApiAudkenniWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum.of(\"ISL\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startAudkenni([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'ISL',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_audkenni(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"ISL\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartAudkenniAsync(new DigitalIdWalletApiAudkenniWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum(\"ISL\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "audkenni" } }, "/v3/id-verification/wallets/connectid/": { "post": { "operationId": "start_connectid_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_connectid", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 ConnectID 登录（Australian Payments Plus；AUS）。仅在身份完成验证时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系提供商。", "summary": "开始 ConnectID 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartRequest" }, "example": { "country": "AUS", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "connectid", "name": "ConnectID", "issuing_authority": "Australian Payments Plus" }, "country": "AUS", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/connectid/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"AUS\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_connectid(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"AUS\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startConnectid({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUS\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartConnectid(ctx, didit.IDWalletsStartConnectidParams{\n\tBody: didit.DigitalIDWalletAPIConnectidWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.Some(didit.DigitalIDWalletAPIConnectidWalletVerificationStartCountryEnum(\"AUS\")),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiConnectidWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startConnectid(DigitalIdWalletApiConnectidWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum.of(\"AUS\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startConnectid([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'AUS',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_connectid(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUS\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartConnectidAsync(new DigitalIdWalletApiConnectidWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = new DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum(\"AUS\"),\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "connectid" } }, "/v3/id-verification/wallets/eudi/": { "post": { "operationId": "start_eudi_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_eudi", "auth": "api_key", "server": true }, "description": "在不使用任何工作流的情况下发起 EUDI Wallet 登录（用户所属的成员国；签发机构因国家/地区而异；AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE, ISL, LIE, NOR）。仅在身份完成验证时计费一次。响应包含 next_action.type=redirect 以及用于引导用户浏览器的 URL；用户返回 return_url 时会附带 request_id 和 result。请通过 GET /v3/id-verification/wallets/verifications/{request_id}/ 或 Webhook 读取结果，切勿直接从 URL 读取。沙盒应用将获得确定性模拟（simulated: true），绝不会联系提供商。", "summary": "开始 EUDI Wallet 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest" }, "example": { "country": "AUT", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "return_url": "https://app.example.com/identity/complete" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "eudi", "name": "EUDI Wallet", "issuing_authority": "The user's own member state; the issuer differs per country" }, "country": "AUT", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "redirect", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "redirect", "url": "https://wallet.example.com/authorize" }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/eudi/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"AUT\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"return_url\": \"https://app.example.com/identity/complete\"\n}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.id_wallets.start_eudi(\n vendor_data=\"your-customer-reference\",\n metadata={\"reference\": \"example\"},\n country=\"AUT\",\n return_url=\"https://app.example.com/identity/complete\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.idWallets.startEudi({\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUT\",\n return_url: \"https://app.example.com/identity/complete\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDWallets.StartEudi(ctx, didit.IDWalletsStartEudiParams{\n\tBody: didit.DigitalIDWalletAPIEudiWalletVerificationStartRequest{\n\t\tVendorData: didit.String(\"your-customer-reference\"),\n\t\tMetadata: didit.Some(map[string]any{\"reference\": \"example\"}),\n\t\tCountry: didit.DigitalIDWalletAPIEudiWalletVerificationStartCountryEnum(\"AUT\"),\n\t\tReturnURL: \"https://app.example.com/identity/complete\",\n\t},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.DigitalIdWalletApiEudiWalletVerificationStartCountryEnum;\nimport me.didit.types.DigitalIdWalletApiEudiWalletVerificationStartRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.idWallets().startEudi(DigitalIdWalletApiEudiWalletVerificationStartRequest.builder()\n .vendorData(\"your-customer-reference\")\n .metadata(Map.of(\"reference\", \"example\"))\n .country(DigitalIdWalletApiEudiWalletVerificationStartCountryEnum.of(\"AUT\"))\n .returnUrl(\"https://app.example.com/identity/complete\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "idWallets->startEudi([\n 'vendor_data' => 'your-customer-reference',\n 'metadata' => ['reference' => 'example'],\n 'country' => 'AUT',\n 'return_url' => 'https://app.example.com/identity/complete',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.id_wallets.start_eudi(\n vendor_data: \"your-customer-reference\",\n metadata: { reference: \"example\" },\n country: \"AUT\",\n return_url: \"https://app.example.com/identity/complete\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.IdWallets.StartEudiAsync(new DigitalIdWalletApiEudiWalletVerificationStartRequest\n{\n VendorData = \"your-customer-reference\",\n Metadata = new Dictionary { [\"reference\"] = \"example\" },\n Country = \"AUT\",\n ReturnUrl = \"https://app.example.com/identity/complete\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-wallet-id": "eudi" } }, "/v3/organization/{organization_id}/application/{application_id}/cases/teams/": { "get": { "summary": "列出审核团队", "description": "需要针对所请求应用的 `list:cases` 权限。", "operationId": "list_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeam" } }, "count": { "type": "integer", "description": "匹配数量，上限为 100。按照 next 继续获取超出上限的数据。" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true } } } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.teams.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.teams.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Teams.ListAutoPaging(ctx, didit.CasesTeamsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().teams().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->teams->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.teams.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Teams.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "创建审核团队", "description": "需要针对所请求应用的 `write:cases` 权限。", "operationId": "create_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "responses": { "201": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeam" } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeamCreate" }, "example": { "name": "AML analysts", "members": [ { "user_id": "9a000000-0000-4000-8000-0000000000aa", "capacity": 10 } ] } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.teams.create(\n name=\"AML analysts\",\n members=[{\n \"user_id\": \"9a000000-0000-4000-8000-0000000000aa\",\n \"capacity\": 10,\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.teams.create({\n name: \"AML analysts\",\n members: [{\n user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n capacity: 10,\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Teams.Create(ctx, didit.CaseReviewTeamCreate{\n\tName: \"AML analysts\",\n\tMembers: []didit.CaseReviewTeamMemberParam{{\n\t\tUserID: \"9a000000-0000-4000-8000-0000000000aa\",\n\t\tCapacity: didit.Int(10),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseReviewTeamCreate;\nimport me.didit.types.CaseReviewTeamMember;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().teams().create(CaseReviewTeamCreate.builder()\n .name(\"AML analysts\")\n .members(List.of(CaseReviewTeamMember.builder()\n .userId(\"9a000000-0000-4000-8000-0000000000aa\")\n .capacity(10L)\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->teams->create([\n 'name' => 'AML analysts',\n 'members' => [[\n 'user_id' => '9a000000-0000-4000-8000-0000000000aa',\n 'capacity' => 10,\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.teams.create(\n name: \"AML analysts\",\n members: [{\n user_id: \"9a000000-0000-4000-8000-0000000000aa\",\n capacity: 10,\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Teams.CreateAsync(new CaseReviewTeamCreate\n{\n Name = \"AML analysts\",\n Members = new CaseReviewTeamMember[]\n {\n new()\n {\n UserId = \"9a000000-0000-4000-8000-0000000000aa\",\n Capacity = 10,\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/fraud/checks/{check_id}/": { "get": { "operationId": "root_retrieve", "x-didit-sdk": { "resource": "fraud_checks", "method": "retrieve", "auth": "api_key", "server": true }, "description": "通过 `check_id` 获取先前创建的检查。", "summary": "获取欺诈检查", "parameters": [ { "in": "path", "name": "check_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckResponse" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsErrorMessage" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsForbiddenErrorMessage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ "Fraud Check" ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.fraud_checks.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.fraudChecks.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.fraudChecks().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "fraudChecks->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.fraud_checks.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FraudChecks.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/": { "get": { "operationId": "organization_application_cases_requests_list", "x-didit-sdk": { "resource": "cases.requests", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "对结果进行排序时使用哪个字段。", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "每页返回的结果数量。", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "返回结果的起始索引。", "schema": { "type": "integer" } } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingPaginatedCaseRequestList" } } }, "description": "" }, "404": { "description": "此调用方无法访问该请求或案件。" }, "403": { "description": "调用方缺少必需的案件权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.requests.list(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.requests.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Requests.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesRequestsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().requests().list(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->requests->list('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.requests.list(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Requests.ListAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "operationId": "organization_application_cases_requests_create", "x-didit-sdk": { "resource": "cases.requests", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestConfirmRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestConfirmRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestConfirmRequest" } } }, "required": true }, "responses": { "404": { "description": "此调用方无法访问该请求或案件。" }, "403": { "description": "调用方缺少必需的案件权限。" }, "400": { "description": "无效的输入、不受支持的目的、不可用的已验证联系方式，或已存在不可变的响应。" }, "409": { "description": "预览已更改或已过期。确认前请重新预览。" }, "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "在 15 分钟内确认完全一致的已签名预览。仅接受固定模板以及属于案件主体的 OTP 验证联系方式。请求 ID 可确保重试具有幂等性。投递已排队；SENT、SIMULATED 和 UNKNOWN 是不同的结果。可操作的请求会将案件设为 Awaiting user。审核更新则保持其状态不变。", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.create(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id=\"11111111-2222-3333-4444-555555555555\",\n purpose=\"identity_document\",\n request_id=\"11111111-2222-3333-4444-555555555555\",\n expires_at=\"2026-01-15T10:00:00Z\",\n preview_token=\"your-preview-token\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.create(\"11111111-2222-3333-4444-555555555555\", {\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\",\n request_id: \"11111111-2222-3333-4444-555555555555\",\n expires_at: \"2026-01-15T10:00:00Z\",\n preview_token: \"your-preview-token\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CustomerMessagingCaseRequestConfirmRequest{\n\tContactID: \"11111111-2222-3333-4444-555555555555\",\n\tPurpose: didit.CustomerMessagingPurposeEnum(\"identity_document\"),\n\tRequestID: \"11111111-2222-3333-4444-555555555555\",\n\tExpiresAt: time.Date(2026, 1, 15, 10, 0, 0, 0, time.UTC),\n\tPreviewToken: \"your-preview-token\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport me.didit.Didit;\nimport me.didit.types.CustomerMessagingCaseRequestConfirmRequest;\nimport me.didit.types.CustomerMessagingPurposeEnum;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().create(\"11111111-2222-3333-4444-555555555555\", CustomerMessagingCaseRequestConfirmRequest.builder()\n .contactId(\"11111111-2222-3333-4444-555555555555\")\n .purpose(CustomerMessagingPurposeEnum.of(\"identity_document\"))\n .requestId(\"11111111-2222-3333-4444-555555555555\")\n .expiresAt(OffsetDateTime.parse(\"2026-01-15T10:00:00Z\"))\n .previewToken(\"your-preview-token\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->create('11111111-2222-3333-4444-555555555555', [\n 'contact_id' => '11111111-2222-3333-4444-555555555555',\n 'purpose' => 'identity_document',\n 'request_id' => '11111111-2222-3333-4444-555555555555',\n 'expires_at' => '2026-01-15T10:00:00Z',\n 'preview_token' => 'your-preview-token',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.create(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\",\n request_id: \"11111111-2222-3333-4444-555555555555\",\n expires_at: \"2026-01-15T10:00:00Z\",\n preview_token: \"your-preview-token\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new CustomerMessagingCaseRequestConfirmRequest\n{\n ContactId = \"11111111-2222-3333-4444-555555555555\",\n Purpose = \"identity_document\",\n RequestId = \"11111111-2222-3333-4444-555555555555\",\n ExpiresAt = DateTimeOffset.Parse(\"2026-01-15T10:00:00Z\"),\n PreviewToken = \"your-preview-token\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/fraud/checks/": { "post": { "operationId": "create_fraud_check", "x-didit-sdk": { "resource": "fraud_checks", "method": "create", "auth": "api_key", "server": true }, "description": "提交一个或多个带类型的标识符，并在单个响应中接收标准化结果、最新补充数据、覆盖相应国家/地区和标识符类型的权威核验、独立风险维度以及建议。\n\n这些画像支持标识符核验。基于自拍照的身份绑定（`biometric_identity`）需要画像版本 `2026-09-14.2` 和巴西 CPF；它仅在获得用户同意且您的组织有权使用时运行。早期版本将其报告为 `not_available_in_profile_version`。无法运行的模块将报告为已跳过并附带确定性原因；无法响应的数据源绝不会报告为身份不匹配。", "summary": "运行欺诈检查", "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" }, "example": { "client_reference": "review-attempt-001", "subject": { "identifiers": [ { "type": "email", "value": "applicant@example.com" } ], "attributes": { "first_name": "Alex", "last_name": "Example" } }, "checks": { "include": [ "networks_same_org", "networks_cross_org", "email_risk" ] } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckResponse" } } }, "description": "" }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsErrorMessage" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudClientCredentialsForbiddenErrorMessage" } } }, "description": "" }, "409": { "description": "冲突，返回且不扣费：`client_reference` 已被其他请求体使用；具有相同 `client_reference` 的检查仍在运行中（请在 `Retry-After` 秒后使用相同的引用重试）；或者本检查将记录到的验证在检查完成前已被删除。", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "examples": { "different_body": { "summary": "引用已被不同的请求体复用", "value": { "error": "client_reference has already been used with a different request body." } }, "still_running": { "summary": "带有此引用的核验仍在运行中", "value": { "error": "A check with this client_reference is already running. Retry with the same reference later." } }, "verification_deleted": { "summary": "验证在检查完成前已被删除", "value": { "error": "This verification was deleted before the check completed." } } } } }, "headers": { "Retry-After": { "description": "重试前需等待的秒数，在具有相同 `client_reference` 的检查仍在运行时返回。", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "tags": [ "Fraud Check" ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.fraud_checks.create(\n client_reference=\"review-attempt-001\",\n subject={\n \"identifiers\": [{\n \"type\": \"email\",\n \"value\": \"applicant@example.com\",\n }],\n \"attributes\": {\n \"first_name\": \"Alex\",\n \"last_name\": \"Example\",\n },\n },\n checks={\n \"include\": [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.fraudChecks.create({\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Create(ctx, didit.FraudCheckRequestRequest{\n\tClientReference: didit.String(\"review-attempt-001\"),\n\tSubject: didit.FraudCheckSubjectRequest{\n\t\tIdentifiers: []didit.FraudCheckIdentifierRequest{{\n\t\t\tType: didit.FraudTypeEnum(\"email\"),\n\t\t\tValue: \"applicant@example.com\",\n\t\t}},\n\t\tAttributes: didit.Some(didit.FraudCheckAttributesRequest{\n\t\t\tFirstName: didit.String(\"Alex\"),\n\t\t\tLastName: didit.String(\"Example\"),\n\t\t}),\n\t},\n\tChecks: didit.Some(didit.FraudCheckModuleSelectionRequest{\n\t\tInclude: didit.Some([]didit.FraudExcludeEnum{didit.FraudExcludeEnum(\"networks_same_org\"), didit.FraudExcludeEnum(\"networks_cross_org\"), didit.FraudExcludeEnum(\"email_risk\")}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.FraudCheckAttributesRequest;\nimport me.didit.types.FraudCheckIdentifierRequest;\nimport me.didit.types.FraudCheckModuleSelectionRequest;\nimport me.didit.types.FraudCheckRequestRequest;\nimport me.didit.types.FraudCheckSubjectRequest;\nimport me.didit.types.FraudExcludeEnum;\nimport me.didit.types.FraudTypeEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.fraudChecks().create(FraudCheckRequestRequest.builder()\n .clientReference(\"review-attempt-001\")\n .subject(FraudCheckSubjectRequest.builder()\n .identifiers(List.of(FraudCheckIdentifierRequest.builder()\n .type(FraudTypeEnum.of(\"email\"))\n .value(\"applicant@example.com\")\n .build()))\n .attributes(FraudCheckAttributesRequest.builder()\n .firstName(\"Alex\")\n .lastName(\"Example\")\n .build())\n .build())\n .checks(FraudCheckModuleSelectionRequest.builder()\n .include(List.of(FraudExcludeEnum.of(\"networks_same_org\"), FraudExcludeEnum.of(\"networks_cross_org\"), FraudExcludeEnum.of(\"email_risk\")))\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "fraudChecks->create([\n 'client_reference' => 'review-attempt-001',\n 'subject' => [\n 'identifiers' => [[\n 'type' => 'email',\n 'value' => 'applicant@example.com',\n ]],\n 'attributes' => [\n 'first_name' => 'Alex',\n 'last_name' => 'Example',\n ],\n ],\n 'checks' => [\n 'include' => ['networks_same_org', 'networks_cross_org', 'email_risk'],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.fraud_checks.create(\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FraudChecks.CreateAsync(new FraudCheckRequestRequest\n{\n ClientReference = \"review-attempt-001\",\n Subject = new()\n {\n Identifiers = new FraudCheckIdentifierRequest[]\n {\n new()\n {\n Type = \"email\",\n Value = \"applicant@example.com\",\n },\n },\n Attributes = new FraudCheckAttributesRequest\n {\n FirstName = \"Alex\",\n LastName = \"Example\",\n },\n },\n Checks = new FraudCheckModuleSelectionRequest\n {\n Include = new FraudExcludeEnum[] { \"networks_same_org\", \"networks_cross_org\", \"email_risk\" },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/{request_uuid}/cancel/": { "post": { "operationId": "organization_application_cases_requests_cancel_create", "x-didit-sdk": { "resource": "cases.requests", "method": "cancel", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" } } }, "description": "" }, "404": { "description": "此调用方无法访问该请求或案件。" }, "403": { "description": "调用方缺少必需的案件权限。" }, "400": { "description": "无效的输入、不受支持的目的、不可用的已验证联系方式，或已存在不可变的响应。" }, "409": { "description": "预览已更改或已过期。确认前请重新预览。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Cancel(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().cancel(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->cancel('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.CancelAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/options/": { "get": { "operationId": "organization_application_cases_requests_options_retrieve", "x-didit-sdk": { "resource": "cases.requests", "method": "retrieve_options", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestOptions" } } }, "description": "" }, "404": { "description": "此调用方无法访问该请求或案件。" }, "403": { "description": "调用方缺少必需的案件权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.retrieve_options(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.retrieveOptions(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.RetrieveOptions(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().retrieveOptions(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->retrieveOptions('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.retrieve_options(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.RetrieveOptionsAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/{request_uuid}/attachment/": { "get": { "operationId": "organization_application_cases_requests_attachment_retrieve", "x-didit-sdk": { "resource": "cases.requests", "method": "retrieve_attachment", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "image/jpeg": { "schema": { "type": "string", "format": "binary" } } }, "description": "" }, "404": { "description": "此调用方无法访问该请求或案件。" }, "403": { "description": "调用方缺少必需的案件权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\ncontent = client.cases.requests.retrieve_attachment(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.png\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst content = await didit.cases.requests.retrieveAttachment(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nawait writeFile(\"download.png\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresp, err := client.Cases.Requests.RetrieveAttachment(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.png\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().requests().retrieveAttachment(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.png\"));" }, { "lang": "php", "label": "PHP", "source": "cases->requests->retrieveAttachment('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.png');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ncontent = didit.cases.requests.retrieve_attachment(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nFile.binwrite(\"download.png\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar content = await client.Cases.Requests.RetrieveAttachmentAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.png\");" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/history/": { "get": { "operationId": "list_case_routing_rule_history", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "list_history", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "对结果进行排序时使用哪个字段。", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "每页返回的结果数量。", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "返回结果的起始索引。", "schema": { "type": "integer" } } ], "tags": [ "Case Assignment" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPaginatedPolicyRevisionList" } } }, "description": "" }, "403": { "description": "需要案件访问权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.routing_rules.list_history(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.routingRules.listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.RoutingRules.ListHistoryAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesRoutingRulesListHistoryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().routingRules().listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->listHistory('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.routing_rules.list_history(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.RoutingRules.ListHistoryAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/resubmission-preview/": { "post": { "summary": "预览重新提交电子邮件", "description": "渲染 KYC 或 KYB 重新提交时将附带的邮件，且不会更改会话、重置检查、延长到期时间、运行检查或发送邮件。需要 `write:sessions` 权限（受限范围的 API 密钥需要对决策拥有写入权限），且会话需处于 `Approved`、`Declined`、`In Review`、`Kyc Expired` 或 `Abandoned` 状态。服务器会验证所选的工作流步骤，并使用适用的已验证白标发件人和品牌标识渲染其固定的已翻译模板。请求中无法设置主题、正文或操作 URL。\n\n`email_address` 为可选参数。若未提供，邮件将发送至该人员自己的地址：即其在该工作流的邮箱验证步骤中核验的地址，或者在创建会话时于 `contact_details` 中提供的地址。若您传入地址，则以您传入的为准（`recipient_source: request`）。当没有任何已知地址且您未传入地址时，`recipient` 和 `preview_token` 将为空字符串，且无法发送任何邮件。\n\n响应包含收件人及其来源、发件人、主题、HTML、语言、已解析的步骤、确认后是否会发送邮件（`will_be_sent`、`not_sent_reason`）以及签名的 `preview_token`。当所有选定的步骤都无需该人员参与即可运行时，`requires_user_action` 为 `false`：重新提交将自动完成，且不会发送任何邮件（`not_sent_reason: no_user_action`）。\n\n此预览不会预留会话状态，也不会授权投递。检查预览后，调用 [更新会话状态](/zh/sessions-api/update-status)，并传入 `new_status: Resubmitted`、与预览相同的 `nodes_to_resubmit` 和 `email_language`、`send_email: true`、设置为 `recipient` 的 `email_address` 以及设置为 `preview_token` 的 `email_preview_token`。回执在 15 分钟后过期。若提供了回执，在进行任何变更或发送之前，输入、消息内容、发件人或会话状态发生更改时，都会返回 `409`。现有的集成可以省略回执。发生冲突后请重新生成预览。请将响应视为敏感验证内容；响应使用 `Cache-Control: no-store`。请在沙盒框架中渲染 HTML，切勿直接在您的应用 DOM 中渲染。", "operationId": "post_v3_session_resubmission_preview", "x-didit-sdk": { "resource": "sessions", "method": "preview_resubmission", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "要更新的验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID，服务会跨两种会话类型解析该 ID。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "nodes_to_resubmit": { "type": "array", "description": "要预览的步骤，使用与重新提交相同的验证、选择和工作流排序。省略此项将自动选择需要重新提交的已记录尝试。", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "在会话的工作流定义中显示的节点标识符（例如 `feature_ocr`、`feature_liveness`）。", "example": "feature_ocr" }, "feature": { "type": "string", "description": "节点的功能类型。别名 `ID_VERIFICATION`、`POA`、`PHONE` 和 `EMAIL` 会在服务端规范化为 `OCR`、`PROOF_OF_ADDRESS`、`PHONE_VERIFICATION` 和 `EMAIL_VERIFICATION`。`KYB_REGISTRY`、`KYB_KEY_PEOPLE` 和 `KYB` 虽然能通过模式验证，但始终会被示例中所示的业务规则 `400` 拒绝。", "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_DOCUMENTS", "ID_VERIFICATION", "POA", "PHONE", "EMAIL", "KYB_REGISTRY", "KYB_KEY_PEOPLE", "KYB", "GEOLOCATION" ], "example": "OCR" } } } }, "email_address": { "type": "string", "format": "email", "description": "可选。将邮件发送至此地址，而非此人的地址。如未提供，收件人为该人在流程中验证的地址，否则为 `contact_details` 中提供的地址。此调用不会发送邮件。", "example": "user@example.com" }, "email_language": { "type": "string", "description": "通知邮件的语言。在 schema 层面接受任何字符串；不支持的代码将以静默方式回退为英语（`en`）。", "default": "en", "example": "en" } } }, "examples": { "Person's Own Address": { "summary": "预览针对用户本人地址的地址证明重新提交", "value": { "nodes_to_resubmit": [ { "node_id": "feature_poa_1", "feature": "POA" } ], "email_language": "en" } }, "Named Recipient": { "summary": "预览指定地址的电子邮件", "value": { "nodes_to_resubmit": [ { "node_id": "feature_ocr", "feature": "OCR" } ], "email_address": "person@example.com", "email_language": "en" } } } } } }, "responses": { "200": { "description": "仅供预览。会话保持不变且不会发送电子邮件。", "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient", "recipient_source", "sender", "sender_name", "sender_email", "sender_kind", "subject", "html", "text", "language", "will_be_sent", "not_sent_reason", "preview_token", "nodes_to_resubmit", "requires_user_action" ], "properties": { "recipient": { "type": "string", "description": "邮件发送的目标地址。若该人员无已知地址，则为空字符串：此时无法发送邮件，且 `preview_token` 同样为空。确认时请将其作为 `email_address` 传递。", "example": "person@example.com" }, "recipient_source": { "type": "string", "enum": [ "email_verification", "contact_details", "request", "" ], "description": "`recipient` 的来源。`request`：您传递的 `email_address`。`email_verification`：用户在流程的邮箱验证步骤中验证的地址。`contact_details`：创建会话时在 `contact_details` 中提供的地址。没有地址时为空字符串。", "example": "email_verification" }, "sender": { "type": "string", "description": "发送邮件时使用的 `From` 请求头。", "example": "Example App " }, "sender_name": { "type": "string", "description": "`sender` 的显示名称部分。", "example": "Example App" }, "sender_email": { "type": "string", "format": "email", "description": "`sender` 的地址部分。", "example": "no-reply@mail.example.com" }, "sender_kind": { "type": "string", "enum": [ "customer", "didit" ], "description": "`customer`：邮件从您应用的已验证发送方域名发出（白标）。`didit`：从 Didit 自己的发送方发出。", "example": "customer" }, "subject": { "type": "string", "description": "与发送时完全一致的主题行。", "example": "Action Required: Complete your verification in Example App" }, "html": { "type": "string", "description": "发送时完全一致的电子邮件 HTML，其徽标作为 data URL 嵌入。请在沙盒 frame 中渲染，切勿直接在您的应用 DOM 中渲染。", "example": "..." }, "text": { "type": "string", "description": "电子邮件的纯文本内容，与该用户的“消息”会话中保留的一致，用于紧凑预览（HTML 仍为该用户收到的电子邮件形式）。", "example": "Almost there\n\nSome steps need to be completed again.\nHere’s what to fix:\n\nhttps://verify.didit.me/session/abc123" }, "language": { "type": "string", "description": "邮件所用的语言。如果您请求的 `email_language` 不支持，则为英语（`en`）。", "example": "en" }, "will_be_sent": { "type": "boolean", "description": "使用 `send_email: true` 确认更改是否会发送此电子邮件。当设置了 `not_sent_reason` 时为 `false`。", "example": true }, "not_sent_reason": { "type": "string", "nullable": true, "enum": [ "no_user_action", "no_recipient", "sandbox", null ], "description": "确认操作不会发送电子邮件的原因；若将发送邮件，则为 `null`。`no_user_action`：所有选定步骤均无需该用户参与即可运行，因此重新提交会自动完成且不发送任何电子邮件。`no_recipient`：未获知该用户的地址，且您未传入任何地址。`sandbox`：接收者未选择接收沙盒邮件投递的沙盒会话，因此发送仅为模拟。", "example": null }, "nodes_to_resubmit": { "type": "array", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "在会话的工作流定义中显示的节点标识符（例如 `feature_ocr`、`feature_liveness`）。", "example": "feature_ocr" }, "feature": { "type": "string", "description": "节点的功能类型。别名 `ID_VERIFICATION`、`POA`、`PHONE` 和 `EMAIL` 会在服务端规范化为 `OCR`、`PROOF_OF_ADDRESS`、`PHONE_VERIFICATION` 和 `EMAIL_VERIFICATION`。`KYB_REGISTRY`、`KYB_KEY_PEOPLE` 和 `KYB` 虽然能通过模式验证，但始终会被示例中所示的业务规则 `400` 拒绝。", "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_DOCUMENTS", "ID_VERIFICATION", "POA", "PHONE", "EMAIL", "KYB_REGISTRY", "KYB_KEY_PEOPLE", "KYB", "GEOLOCATION" ], "example": "OCR" } } } }, "requires_user_action": { "type": "boolean", "description": "所选检查中是否至少有一项需要用户交互。这并不预示最终的工作流结果。" }, "preview_token": { "type": "string", "description": "此特定邮件的签名收据，有效期为 15 分钟。将其作为 `email_preview_token` 传递给[更新会话状态](/zh/sessions-api/update-status)。当没有收件人时为空字符串。", "example": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } }, "examples": { "Will Be Sent": { "summary": "默认接收方：在流程中验证过的地址", "value": { "recipient": "person@example.com", "recipient_source": "email_verification", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Action Required: Complete your verification in Example App", "html": "...", "language": "en", "will_be_sent": true, "not_sent_reason": null, "nodes_to_resubmit": [ { "node_id": "feature_poa_1", "feature": "PROOF_OF_ADDRESS" } ], "requires_user_action": true, "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } }, "No User Action": { "summary": "仅选择了后端步骤，因此不会发送电子邮件", "value": { "recipient": "person@example.com", "recipient_source": "contact_details", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Action Required: Complete your verification in Example App", "html": "...", "language": "en", "will_be_sent": false, "not_sent_reason": "no_user_action", "nodes_to_resubmit": [ { "node_id": "feature_aml", "feature": "AML" } ], "requires_user_action": false, "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } } } }, "headers": { "Cache-Control": { "description": "始终为 `no-store`：预览包含验证内容，切勿缓存。", "schema": { "type": "string", "example": "no-store" } } } }, "400": { "description": "会话未处于此 endpoint 接受的状态、已处于 `Resubmitted` 状态、所选步骤无法重新提交，或某个字段无效。", "content": { "application/json": { "examples": { "Wrong Current Status": { "summary": "会话不处于此 endpoint 接受的状态", "value": { "detail": "Only sessions with status Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted can be updated. Current status: In Progress" } }, "Already Resubmitted": { "summary": "会话已处于 Resubmitted 状态", "value": [ "The new status is the same as the current status." ] }, "Nothing To Resubmit": { "summary": "自动选择未找到需要重新提交的步骤", "value": { "nodes_to_resubmit": "No features found that need resubmission. All features are already approved." } }, "Invalid Email": { "summary": "email_address 不是有效的邮箱地址", "value": { "email_address": [ "Enter a valid email address." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "已过有效期的作用域 API 密钥", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少凭据、调用方没有 `write:sessions` 权限、限定范围的 API 密钥缺少此 endpoint 所需的访问权限，或者 `session_id` 属于另一个应用。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "调用方缺少 write:sessions 权限", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "没有此访问权限的作用域 API 密钥", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "不存在具有此 `session_id` 的 KYC 或 KYB 会话。", "content": { "application/json": { "examples": { "Not Found": { "summary": "未知的 session_id", "value": { "detail": "Not found." } } } } } }, "429": { "description": "要重新提交的步骤全为仅后端步骤（AML、DATABASE_VALIDATION、IP_ANALYSIS），且会话在过去 30 秒内已经重新提交过仅后端步骤，因此 Update Session Status 会拒绝本次重新提交。请在 `Retry-After` 指定的时间间隔后重试。", "content": { "application/json": { "examples": { "Backend-only resubmit throttled": { "value": { "detail": "This session was already resubmitted for backend-only features within the last 30 seconds; repeating it cannot change the outcome. Wait before resubmitting again." } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.preview_resubmission(\n \"11111111-2222-3333-4444-555555555555\",\n nodes_to_resubmit=[{\n \"node_id\": \"feature_poa_1\",\n \"feature\": \"POA\",\n }],\n email_language=\"en\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.previewResubmission(\"11111111-2222-3333-4444-555555555555\", {\n nodes_to_resubmit: [{\n node_id: \"feature_poa_1\",\n feature: \"POA\",\n }],\n email_language: \"en\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.PreviewResubmission(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsPreviewResubmissionParams{\n\tNodesToResubmit: didit.Some([]didit.SessionsPreviewResubmissionParamsNodesToResubmit{{\n\t\tNodeID: \"feature_poa_1\",\n\t\tFeature: \"POA\",\n\t}}),\n\tEmailLanguage: didit.String(\"en\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsPreviewResubmissionParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().previewResubmission(\"11111111-2222-3333-4444-555555555555\", SessionsPreviewResubmissionParams.builder()\n .nodesToResubmit(List.of(SessionsPreviewResubmissionParams.NodesToResubmit.builder()\n .nodeId(\"feature_poa_1\")\n .feature(SessionsPreviewResubmissionParams.NodesToResubmit.Feature.of(\"POA\"))\n .build()))\n .emailLanguage(\"en\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->previewResubmission('11111111-2222-3333-4444-555555555555', [\n 'nodes_to_resubmit' => [[\n 'node_id' => 'feature_poa_1',\n 'feature' => 'POA',\n ]],\n 'email_language' => 'en',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.preview_resubmission(\n \"11111111-2222-3333-4444-555555555555\",\n nodes_to_resubmit: [{\n node_id: \"feature_poa_1\",\n feature: \"POA\",\n }],\n email_language: \"en\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.PreviewResubmissionAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsPreviewResubmissionParams\n{\n NodesToResubmit = new SessionsPreviewResubmissionParamsNodesToResubmit[]\n {\n new()\n {\n NodeId = \"feature_poa_1\",\n Feature = \"POA\",\n },\n },\n EmailLanguage = \"en\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/": { "get": { "summary": "获取路由规则", "description": "需要针对所请求应用的 `read:cases` 权限。", "operationId": "retrieve_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRule" } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" }, "404": { "description": "在此应用中未找到记录。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "更新路由规则", "description": "需要针对所请求应用的 `write:cases` 权限。", "operationId": "update_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRule" } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" }, "404": { "description": "在此应用中未找到记录。" }, "409": { "description": "自 expected_version 以来，该路由规则已发生更改。重试前请查看最新规则。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRuleUpdate" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n name=\"your-name\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.update(\"11111111-2222-3333-4444-555555555555\", {\n name: \"your-name\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseRoutingRuleUpdate{\n\tName: didit.String(\"your-name\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseRoutingRuleUpdate;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().update(\"11111111-2222-3333-4444-555555555555\", CaseRoutingRuleUpdate.builder()\n .name(\"your-name\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->update('11111111-2222-3333-4444-555555555555', [\n 'name' => 'your-name',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.update(\n \"11111111-2222-3333-4444-555555555555\",\n name: \"your-name\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new CaseRoutingRuleUpdate\n{\n Name = \"your-name\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/case-requests/{request_uuid}/": { "get": { "operationId": "case_requests_retrieve", "x-didit-sdk": { "resource": "case_requests", "method": "retrieve", "auth": "device_token", "server": false }, "parameters": [ { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPublic" } } }, "description": "" }, "404": { "description": "此调用方无法访问该请求或案件。" } }, "security": [ { "CaseRequestToken": [] } ], "description": "使用特定于请求的 token 访问单个客户请求。不会返回任何私密案件调查结果、原始身份数据或收款人地址。可操作的请求将在七天后过期。取消或案件解决会导致链接失效。响应不可变，并保留作为审核员评估的证据；它们绝不会批准或更新源验证。" }, "post": { "operationId": "case_requests_create", "x-didit-sdk": { "resource": "case_requests", "method": "respond", "auth": "device_token", "server": false }, "parameters": [ { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseCustomerResponseRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseCustomerResponseRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseCustomerResponseResult" } } }, "description": "" }, "404": { "description": "此调用方无法访问该请求或案件。" }, "400": { "description": "无效的输入、不受支持的目的、不可用的已验证联系方式，或已存在不可变的响应。" }, "409": { "description": "预览已更改或已过期。确认前请重新预览。" } }, "security": [ { "CaseRequestToken": [] } ], "description": "使用特定于请求的 token 访问单个客户请求。不会返回任何私密案件调查结果、原始身份数据或收款人地址。可操作的请求将在七天后过期。取消或案件解决会导致链接失效。响应不可变，并保留作为审核员评估的证据；它们绝不会批准或更新源验证。" } }, "/v3/fraud/checks/plan/": { "post": { "operationId": "plan_create", "x-didit-sdk": { "resource": "fraud_checks", "method": "plan", "auth": "api_key", "server": true }, "description": "验证所选检查并估算其价格，无需实际执行、创建会话或计费。", "summary": "计划欺诈检查", "tags": [ "Fraud Check" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" }, "example": { "client_reference": "review-attempt-001", "subject": { "identifiers": [ { "type": "email", "value": "applicant@example.com" } ], "attributes": { "first_name": "Alex", "last_name": "Example" } }, "checks": { "include": [ "networks_same_org", "networks_cross_org", "email_risk" ] } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/FraudCheckRequestRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudCheckPlan" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudBadRequestErrorMessage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.fraud_checks.plan(\n client_reference=\"review-attempt-001\",\n subject={\n \"identifiers\": [{\n \"type\": \"email\",\n \"value\": \"applicant@example.com\",\n }],\n \"attributes\": {\n \"first_name\": \"Alex\",\n \"last_name\": \"Example\",\n },\n },\n checks={\n \"include\": [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.fraudChecks.plan({\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.FraudChecks.Plan(ctx, didit.FraudCheckRequestRequest{\n\tClientReference: didit.String(\"review-attempt-001\"),\n\tSubject: didit.FraudCheckSubjectRequest{\n\t\tIdentifiers: []didit.FraudCheckIdentifierRequest{{\n\t\t\tType: didit.FraudTypeEnum(\"email\"),\n\t\t\tValue: \"applicant@example.com\",\n\t\t}},\n\t\tAttributes: didit.Some(didit.FraudCheckAttributesRequest{\n\t\t\tFirstName: didit.String(\"Alex\"),\n\t\t\tLastName: didit.String(\"Example\"),\n\t\t}),\n\t},\n\tChecks: didit.Some(didit.FraudCheckModuleSelectionRequest{\n\t\tInclude: didit.Some([]didit.FraudExcludeEnum{didit.FraudExcludeEnum(\"networks_same_org\"), didit.FraudExcludeEnum(\"networks_cross_org\"), didit.FraudExcludeEnum(\"email_risk\")}),\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.FraudCheckAttributesRequest;\nimport me.didit.types.FraudCheckIdentifierRequest;\nimport me.didit.types.FraudCheckModuleSelectionRequest;\nimport me.didit.types.FraudCheckRequestRequest;\nimport me.didit.types.FraudCheckSubjectRequest;\nimport me.didit.types.FraudExcludeEnum;\nimport me.didit.types.FraudTypeEnum;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.fraudChecks().plan(FraudCheckRequestRequest.builder()\n .clientReference(\"review-attempt-001\")\n .subject(FraudCheckSubjectRequest.builder()\n .identifiers(List.of(FraudCheckIdentifierRequest.builder()\n .type(FraudTypeEnum.of(\"email\"))\n .value(\"applicant@example.com\")\n .build()))\n .attributes(FraudCheckAttributesRequest.builder()\n .firstName(\"Alex\")\n .lastName(\"Example\")\n .build())\n .build())\n .checks(FraudCheckModuleSelectionRequest.builder()\n .include(List.of(FraudExcludeEnum.of(\"networks_same_org\"), FraudExcludeEnum.of(\"networks_cross_org\"), FraudExcludeEnum.of(\"email_risk\")))\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "fraudChecks->plan([\n 'client_reference' => 'review-attempt-001',\n 'subject' => [\n 'identifiers' => [[\n 'type' => 'email',\n 'value' => 'applicant@example.com',\n ]],\n 'attributes' => [\n 'first_name' => 'Alex',\n 'last_name' => 'Example',\n ],\n ],\n 'checks' => [\n 'include' => ['networks_same_org', 'networks_cross_org', 'email_risk'],\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.fraud_checks.plan(\n client_reference: \"review-attempt-001\",\n subject: {\n identifiers: [{\n type: \"email\",\n value: \"applicant@example.com\",\n }],\n attributes: {\n first_name: \"Alex\",\n last_name: \"Example\",\n },\n },\n checks: {\n include: [\"networks_same_org\", \"networks_cross_org\", \"email_risk\"],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.FraudChecks.PlanAsync(new FraudCheckRequestRequest\n{\n ClientReference = \"review-attempt-001\",\n Subject = new()\n {\n Identifiers = new FraudCheckIdentifierRequest[]\n {\n new()\n {\n Type = \"email\",\n Value = \"applicant@example.com\",\n },\n },\n Attributes = new FraudCheckAttributesRequest\n {\n FirstName = \"Alex\",\n LastName = \"Example\",\n },\n },\n Checks = new FraudCheckModuleSelectionRequest\n {\n Include = new FraudExcludeEnum[] { \"networks_same_org\", \"networks_cross_org\", \"email_risk\" },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/": { "get": { "summary": "列出路由规则", "description": "需要针对所请求应用的 `list:cases` 权限。", "operationId": "list_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingRule" } }, "count": { "type": "integer", "description": "匹配数量，上限为 100。按照 next 继续获取超出上限的数据。" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true } } } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.routing_rules.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.routingRules.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.RoutingRules.ListAutoPaging(ctx, didit.CasesRoutingRulesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().routingRules().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.routing_rules.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.RoutingRules.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "summary": "创建路由规则", "description": "需要针对所请求应用的 `write:cases` 权限。设置 publish=false 可创建未发布的草稿；发布（Publish）将创建其首个上线版本。舍弃从未发布的草稿会将其删除。", "operationId": "create_case_routing_rules", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "responses": { "201": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRule" } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingRuleCreate" }, "example": { "name": "AML screening alerts", "conditions": [ { "field": "source", "operator": "equals", "value": "AML_SCREENING" } ], "blueprint": "b1de0000-0000-4000-8000-000000000002" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.create(\n name=\"AML screening alerts\",\n conditions=[{\n \"field\": \"source\",\n \"operator\": \"equals\",\n \"value\": \"AML_SCREENING\",\n }],\n blueprint=\"b1de0000-0000-4000-8000-000000000002\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.create({\n name: \"AML screening alerts\",\n conditions: [{\n field: \"source\",\n operator: \"equals\",\n value: \"AML_SCREENING\",\n }],\n blueprint: \"b1de0000-0000-4000-8000-000000000002\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Create(ctx, didit.CaseRoutingRuleCreate{\n\tName: \"AML screening alerts\",\n\tConditions: []didit.CaseRoutingConditionParam{{\n\t\tField: \"source\",\n\t\tOperator: \"equals\",\n\t\tValue: \"AML_SCREENING\",\n\t}},\n\tBlueprint: \"b1de0000-0000-4000-8000-000000000002\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.CaseRoutingCondition;\nimport me.didit.types.CaseRoutingRuleCreate;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().create(CaseRoutingRuleCreate.builder()\n .name(\"AML screening alerts\")\n .conditions(List.of(CaseRoutingCondition.builder()\n .field(CaseRoutingCondition.Field.of(\"source\"))\n .operator(CaseRoutingCondition.Operator.of(\"equals\"))\n .value(CaseRoutingCondition.Value.ofString(\"AML_SCREENING\"))\n .build()))\n .blueprint(\"b1de0000-0000-4000-8000-000000000002\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->create([\n 'name' => 'AML screening alerts',\n 'conditions' => [[\n 'field' => 'source',\n 'operator' => 'equals',\n 'value' => 'AML_SCREENING',\n ]],\n 'blueprint' => 'b1de0000-0000-4000-8000-000000000002',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.create(\n name: \"AML screening alerts\",\n conditions: [{\n field: \"source\",\n operator: \"equals\",\n value: \"AML_SCREENING\",\n }],\n blueprint: \"b1de0000-0000-4000-8000-000000000002\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.CreateAsync(new CaseRoutingRuleCreate\n{\n Name = \"AML screening alerts\",\n Conditions = new CaseRoutingCondition[]\n {\n new()\n {\n Field = \"source\",\n Operator = \"equals\",\n Value = \"AML_SCREENING\",\n },\n },\n Blueprint = \"b1de0000-0000-4000-8000-000000000002\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/publish/": { "post": { "operationId": "publish_case_routing_rule", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "publish", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationCaseRoutingRule" } } }, "description": "" }, "403": { "description": "需要案件访问权限。" }, "409": { "description": "已发布的版本或草稿修订已更改。重试前请重新加载。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.publish(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Publish(ctx, \"11111111-2222-3333-4444-555555555555\", didit.RoutingPublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RoutingPublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().publish(\"11111111-2222-3333-4444-555555555555\", RoutingPublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->publish('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.PublishAsync(\"11111111-2222-3333-4444-555555555555\", new RoutingPublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/publish/": { "post": { "operationId": "publish_case_blueprint", "x-didit-sdk": { "resource": "cases.blueprints", "method": "publish", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationCaseBlueprint" } } }, "description": "" }, "409": { "description": "已发布的版本或保存的草稿修订已更改。重试前请重新加载。" }, "403": { "description": "缺少必需的案件权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.publish(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.Publish(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasePublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasePublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().publish(\"11111111-2222-3333-4444-555555555555\", CasePublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->publish('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.publish(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.PublishAsync(\"11111111-2222-3333-4444-555555555555\", new CasePublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/preview/": { "post": { "operationId": "organization_application_cases_requests_preview_create", "x-didit-sdk": { "resource": "cases.requests", "method": "preview", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestPreviewResponse" } } }, "description": "" }, "404": { "description": "此调用方无法访问该请求或案件。" }, "403": { "description": "调用方缺少必需的案件权限。" }, "400": { "description": "无效的输入、不受支持的目的、不可用的已验证联系方式，或已存在不可变的响应。" }, "409": { "description": "预览已更改或已过期。确认前请重新预览。" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "渲染生产环境电子邮件，而不发送或更改案件。返回确切的收件人、发件人、主题、正文和已签名的 preview_token。在 15 分钟内发送相同的 contact_id、purpose、language、request_id、expires_at 和 preview_token 以进行确认。", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.preview(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id=\"11111111-2222-3333-4444-555555555555\",\n purpose=\"identity_document\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.preview(\"11111111-2222-3333-4444-555555555555\", {\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Preview(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CustomerMessagingCaseRequestPreviewRequest{\n\tContactID: \"11111111-2222-3333-4444-555555555555\",\n\tPurpose: didit.CustomerMessagingPurposeEnum(\"identity_document\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CustomerMessagingCaseRequestPreviewRequest;\nimport me.didit.types.CustomerMessagingPurposeEnum;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().preview(\"11111111-2222-3333-4444-555555555555\", CustomerMessagingCaseRequestPreviewRequest.builder()\n .contactId(\"11111111-2222-3333-4444-555555555555\")\n .purpose(CustomerMessagingPurposeEnum.of(\"identity_document\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->preview('11111111-2222-3333-4444-555555555555', [\n 'contact_id' => '11111111-2222-3333-4444-555555555555',\n 'purpose' => 'identity_document',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.preview(\n \"11111111-2222-3333-4444-555555555555\",\n contact_id: \"11111111-2222-3333-4444-555555555555\",\n purpose: \"identity_document\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.PreviewAsync(\"11111111-2222-3333-4444-555555555555\", new CustomerMessagingCaseRequestPreviewRequest\n{\n ContactId = \"11111111-2222-3333-4444-555555555555\",\n Purpose = \"identity_document\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/action-receipts/": { "get": { "operationId": "action_receipts_retrieve", "x-didit-sdk": { "resource": "cases", "method": "list_action_receipts", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "query", "name": "offset", "schema": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0 } } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseActionReceiptPage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "列出主体操作回执，按最新优先排序，每页最多 20 条结果。使用 next_offset 获取下一页。输入的备注文本不会显示在历史记录中。", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.list_action_receipts(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.listActionReceipts(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ListActionReceipts(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesListActionReceiptsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().listActionReceipts(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->listActionReceipts('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.list_action_receipts(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ListActionReceiptsAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/{note_uuid}/": { "delete": { "operationId": "delete_network_note", "x-didit-sdk": { "resource": "networks.notes", "method": "delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "删除您的网络备注", "description": "需要 write:networks 权限以及备注的已验证作者身份。删除操作不可逆。关联的账户和验证数据不受影响。", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "网络 UUID。" }, { "name": "note_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "格式为 Bearer 的 Console 用户访问 token。" } ], "responses": { "204": { "description": "备注已删除。" }, "401": { "description": "需要身份验证。" }, "403": { "description": "缺少权限或 Networks 访问权限。" }, "404": { "description": "网络或备注对当前应用不可见。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\nclient.networks.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nawait didit.networks.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\nif err := client.Networks.Notes.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", didit.NetworksNotesDeleteParams{\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.core.RequestOptions;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nclient.networks().notes().delete(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build());" }, { "lang": "php", "label": "PHP", "source": "networks->notes->delete('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555', [\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\ndidit.networks.notes.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nawait client.Networks.Notes.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\", requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n});" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/action-receipts/{receipt_uuid}/retry/": { "post": { "operationId": "action_receipts_retry_create", "x-didit-sdk": { "resource": "cases", "method": "retry_action_receipt", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "receipt_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseActionCaseActionReceipt" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "仅使用已保存的输入重试此失败的主体操作。将检查当前的写入权限。已执行的操作将返回其回执，而不会再次执行。案件关闭与此操作无关。", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.retry_action_receipt(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.retryActionReceipt(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RetryActionReceipt(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().retryActionReceipt(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->retryActionReceipt('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.retry_action_receipt(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RetryActionReceiptAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/draft/": { "get": { "operationId": "get_case_blueprint_draft", "x-didit-sdk": { "resource": "cases.blueprints", "method": "retrieve_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftResponse" } } }, "description": "" }, "403": { "description": "缺少必需的案件权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.retrieve_draft(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.RetrieveDraft(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->retrieveDraft('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.retrieve_draft(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.RetrieveDraftAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "put": { "operationId": "save_case_blueprint_draft", "x-didit-sdk": { "resource": "cases.blueprints", "method": "save_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftWriteRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftWriteRequest" }, "example": { "expected_version": 1, "expected_revision": "4e5f0000-0000-4000-8000-000000000003", "changes": { "max_active_cases": 20 } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraft" } } }, "description": "" }, "409": { "description": "已发布的版本或保存的草稿修订已更改。重试前请重新加载。" }, "403": { "description": "缺少必需的案件权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.blueprints.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=1,\n expected_revision=\"4e5f0000-0000-4000-8000-000000000003\",\n changes={\"max_active_cases\": 20},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.blueprints.saveDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { max_active_cases: 20 },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Blueprints.SaveDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasePublicationPolicyDraftWriteRequest{\n\tExpectedVersion: 1,\n\tExpectedRevision: didit.String(\"4e5f0000-0000-4000-8000-000000000003\"),\n\tChanges: map[string]any{\"max_active_cases\": 20},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.CasePublicationPolicyDraftWriteRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().blueprints().saveDraft(\"11111111-2222-3333-4444-555555555555\", CasePublicationPolicyDraftWriteRequest.builder()\n .expectedVersion(1L)\n .expectedRevision(\"4e5f0000-0000-4000-8000-000000000003\")\n .changes(Map.of(\"max_active_cases\", 20))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->saveDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 1,\n 'expected_revision' => '4e5f0000-0000-4000-8000-000000000003',\n 'changes' => ['max_active_cases' => 20],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.blueprints.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { max_active_cases: 20 }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Blueprints.SaveDraftAsync(\"11111111-2222-3333-4444-555555555555\", new CasePublicationPolicyDraftWriteRequest\n{\n ExpectedVersion = 1,\n ExpectedRevision = \"4e5f0000-0000-4000-8000-000000000003\",\n Changes = new Dictionary { [\"max_active_cases\"] = 20 },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "operationId": "discard_case_blueprint_draft", "x-didit-sdk": { "resource": "cases.blueprints", "method": "discard_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "responses": { "204": { "description": "无响应正文" }, "409": { "description": "已发布的版本或保存的草稿修订已更改。重试前请重新加载。" }, "403": { "description": "缺少必需的案件权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPolicyDraftPreconditionRequest" } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.blueprints.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.blueprints.discardDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.Blueprints.DiscardDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasePublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CasePublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().blueprints().discardDraft(\"11111111-2222-3333-4444-555555555555\", CasePublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->discardDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.Blueprints.DiscardDraftAsync(\"11111111-2222-3333-4444-555555555555\", new CasePublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/teams/{record_uuid}/": { "get": { "summary": "获取审核团队", "description": "需要针对所请求应用的 `read:cases` 权限。", "operationId": "retrieve_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeam" } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" }, "404": { "description": "在此应用中未找到记录。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.teams.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.teams.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Teams.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().teams().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->teams->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.teams.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Teams.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "summary": "更新审核团队", "description": "需要针对所请求应用的 `write:cases` 权限。", "operationId": "update_case_teams", "x-didit-sdk": { "resource": "cases.teams", "method": "update", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "record_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeam" } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" }, "404": { "description": "在此应用中未找到记录。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseReviewTeamUpdate" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.teams.update(\n \"11111111-2222-3333-4444-555555555555\",\n name=\"your-name\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.teams.update(\"11111111-2222-3333-4444-555555555555\", {\n name: \"your-name\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Teams.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CaseReviewTeamUpdate{\n\tName: didit.String(\"your-name\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseReviewTeamUpdate;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().teams().update(\"11111111-2222-3333-4444-555555555555\", CaseReviewTeamUpdate.builder()\n .name(\"your-name\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->teams->update('11111111-2222-3333-4444-555555555555', [\n 'name' => 'your-name',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.teams.update(\n \"11111111-2222-3333-4444-555555555555\",\n name: \"your-name\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Teams.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new CaseReviewTeamUpdate\n{\n Name = \"your-name\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/report/": { "get": { "operationId": "download_network_report", "x-didit-sdk": { "resource": "networks", "method": "download_report", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "下载网络证据报告", "description": "下载当前组织网络、其观察到的账户关联、信号引用和审核状态的 PDF。需要 read:networks 权限。不包含全局情报和私有分析师备注。每个账户和信号列表上限为 500 条记录，并在未完整列出时在报告中注明。该请求不会更改网络状态。错误以 JSON 格式返回。", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "网络 UUID。" }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "格式为 Bearer 的 Console 用户访问 token。" } ], "responses": { "200": { "description": "网络证据报告。Cache-Control: no-store。", "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "需要身份验证。" }, "403": { "description": "缺少权限或 Networks 访问权限。" }, "404": { "description": "网络或备注对当前应用不可见。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\ncontent = client.networks.download_report(\n \"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nconst content = await didit.networks.downloadReport(\"11111111-2222-3333-4444-555555555555\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\nresp, err := client.Networks.DownloadReport(ctx, \"11111111-2222-3333-4444-555555555555\", didit.NetworksDownloadReportParams{\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.core.RequestOptions;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nclient.networks().downloadReport(\"11111111-2222-3333-4444-555555555555\", RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build())\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "networks->downloadReport('11111111-2222-3333-4444-555555555555', [\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]);\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\ncontent = didit.networks.download_report(\n \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nvar content = await client.Networks.DownloadReportAsync(\"11111111-2222-3333-4444-555555555555\", requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n});\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/notes/": { "get": { "operationId": "list_network_notes", "x-didit-sdk": { "resource": "networks.notes", "method": "list", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "列出私有网络备注", "description": "具有 read:networks 权限的 Console 用户可以读取该应用可见网络上的备注。备注保留在组织内部，不会贡献给共享情报。最新备注排在最前。", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "网络 UUID。" }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "格式为 Bearer 的 Console 用户访问 token。" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 30 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000, "default": 0 } } ], "responses": { "200": { "description": "一页备注。数量上限为 100；使用 next 继续。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkNote" } } } } } } }, "401": { "description": "需要身份验证。" }, "403": { "description": "缺少权限或 Networks 访问权限。" }, "404": { "description": "网络或备注对当前应用不可见。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\nfor item in client.networks.notes.list(\n \"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nfor await (const item of didit.networks.notes.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\niter := client.Networks.Notes.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.NetworksNotesListParams{\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.core.RequestOptions;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nfor (var item : client.networks().notes().list(\"11111111-2222-3333-4444-555555555555\", RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build())) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "networks->notes->list('11111111-2222-3333-4444-555555555555', [\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]) as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\ndidit.networks.notes.list(\n \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n).auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Networks.Notes.ListAsync(\"11111111-2222-3333-4444-555555555555\", requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n}))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] }, "post": { "operationId": "create_network_note", "x-didit-sdk": { "resource": "networks.notes", "method": "create", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Networks" ], "summary": "添加私有网络备注", "description": "需要具有 write:networks 权限的控制台用户。作者取自经过身份验证的用户。为每条备注提供一个新的随机 UUID client_reference；收到不确定响应后使用相同的请求体和引用重试以避免重复。将引用重复用于其他请求体、作者或网络将返回 409。当网络合并时，备注将跟随保留的调查案件。", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "网络 UUID。" }, { "name": "Authorization", "in": "header", "required": true, "schema": { "type": "string" }, "description": "格式为 Bearer 的 Console 用户访问 token。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "comment", "client_reference" ], "properties": { "comment": { "type": "string", "minLength": 1, "maxLength": 10000 }, "client_reference": { "type": "string", "format": "uuid" } } } } } }, "responses": { "201": { "description": "已保存的私密备注。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkNote" } } } }, "200": { "description": "已保存的私密备注。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkNote" } } } }, "400": { "description": "无效或为空的备注。" }, "409": { "description": "该引用已被用于另一条备注。" }, "401": { "description": "需要身份验证。" }, "403": { "description": "缺少权限或 Networks 访问权限。" }, "404": { "description": "网络或备注对当前应用不可见。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\nclient = Didit()\n\nresult = client.networks.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment=\"your-comment\",\n client_reference=\"11111111-2222-3333-4444-555555555555\",\n extra_headers={\"Authorization\": \"Bearer YOUR_CONSOLE_USER_TOKEN\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nconst didit = new Didit({\n fetch: (url, init) => {\n const headers = new Headers(init?.headers);\n headers.set(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\");\n return fetch(url, { ...init, headers });\n },\n});\n\nconst result = await didit.networks.notes.create(\"11111111-2222-3333-4444-555555555555\", {\n comment: \"your-comment\",\n client_reference: \"11111111-2222-3333-4444-555555555555\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nclient := didit.NewClient()\n\nresult, err := client.Networks.Notes.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.NetworksNotesCreateParams{\n\tComment: \"your-comment\",\n\tClientReference: \"11111111-2222-3333-4444-555555555555\",\n\tAuthorization: \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.core.RequestOptions;\nimport me.didit.types.NetworksNotesCreateParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nDidit client = new Didit();\n\nvar result = client.networks().notes().create(\"11111111-2222-3333-4444-555555555555\", NetworksNotesCreateParams.builder()\n .comment(\"your-comment\")\n .clientReference(\"11111111-2222-3333-4444-555555555555\")\n .build(), RequestOptions.builder()\n .header(\"Authorization\", \"Bearer YOUR_CONSOLE_USER_TOKEN\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->notes->create('11111111-2222-3333-4444-555555555555', [\n 'comment' => 'your-comment',\n 'client_reference' => '11111111-2222-3333-4444-555555555555',\n 'authorization' => 'Bearer YOUR_CONSOLE_USER_TOKEN',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\n# Also needs a console user's access token.\ndidit = Didit::Client.new\n\nresult = didit.networks.notes.create(\n \"11111111-2222-3333-4444-555555555555\",\n comment: \"your-comment\",\n client_reference: \"11111111-2222-3333-4444-555555555555\",\n request_options: { extra_headers: { \"Authorization\" => \"Bearer YOUR_CONSOLE_USER_TOKEN\" } }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\n// Also needs a console user's access token.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.Notes.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new NetworksNotesCreateParams\n{\n Comment = \"your-comment\",\n ClientReference = \"11111111-2222-3333-4444-555555555555\",\n}, requestOptions: new RequestOptions\n{\n Headers = new Dictionary\n {\n [\"Authorization\"] = \"Bearer YOUR_CONSOLE_USER_TOKEN\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/{record_uuid}/draft/": { "get": { "operationId": "get_case_routing_rule_draft", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "retrieve_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftResponse" } } }, "description": "" }, "403": { "description": "需要案件访问权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.retrieve_draft(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.RetrieveDraft(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().retrieveDraft(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->retrieveDraft('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.retrieve_draft(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.RetrieveDraftAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "put": { "operationId": "save_case_routing_rule_draft", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "save_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftWriteRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftWriteRequest" }, "example": { "expected_version": 1, "expected_revision": "4e5f0000-0000-4000-8000-000000000003", "changes": { "priority": 10 } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftWriteRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraft" } } }, "description": "" }, "403": { "description": "需要案件访问权限。" }, "409": { "description": "已发布的版本或草稿修订已更改。重试前请重新加载。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=1,\n expected_revision=\"4e5f0000-0000-4000-8000-000000000003\",\n changes={\"priority\": 10},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.saveDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { priority: 10 },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.SaveDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.RoutingPublicationPolicyDraftWriteRequest{\n\tExpectedVersion: 1,\n\tExpectedRevision: didit.String(\"4e5f0000-0000-4000-8000-000000000003\"),\n\tChanges: map[string]any{\"priority\": 10},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.RoutingPublicationPolicyDraftWriteRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().saveDraft(\"11111111-2222-3333-4444-555555555555\", RoutingPublicationPolicyDraftWriteRequest.builder()\n .expectedVersion(1L)\n .expectedRevision(\"4e5f0000-0000-4000-8000-000000000003\")\n .changes(Map.of(\"priority\", 10))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->saveDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 1,\n 'expected_revision' => '4e5f0000-0000-4000-8000-000000000003',\n 'changes' => ['priority' => 10],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.save_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 1,\n expected_revision: \"4e5f0000-0000-4000-8000-000000000003\",\n changes: { priority: 10 }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.SaveDraftAsync(\"11111111-2222-3333-4444-555555555555\", new RoutingPublicationPolicyDraftWriteRequest\n{\n ExpectedVersion = 1,\n ExpectedRevision = \"4e5f0000-0000-4000-8000-000000000003\",\n Changes = new Dictionary { [\"priority\"] = 10 },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "operationId": "discard_case_routing_rule_draft", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "discard_draft", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "record_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Assignment" ], "responses": { "204": { "description": "无响应正文" }, "403": { "description": "需要案件访问权限。" }, "409": { "description": "已发布的版本或草稿修订已更改。重试前请重新加载。" } }, "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoutingPublicationPolicyDraftPreconditionRequest" } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.cases.routing_rules.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version=0,\n expected_revision=\"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.cases.routingRules.discardDraft(\"11111111-2222-3333-4444-555555555555\", {\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\",\n});" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nif err := client.Cases.RoutingRules.DiscardDraft(ctx, \"11111111-2222-3333-4444-555555555555\", didit.RoutingPublicationPolicyDraftPreconditionRequest{\n\tExpectedVersion: 0,\n\tExpectedRevision: didit.String(\"11111111-2222-3333-4444-555555555555\"),\n}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.RoutingPublicationPolicyDraftPreconditionRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.cases().routingRules().discardDraft(\"11111111-2222-3333-4444-555555555555\", RoutingPublicationPolicyDraftPreconditionRequest.builder()\n .expectedVersion(0L)\n .expectedRevision(\"11111111-2222-3333-4444-555555555555\")\n .build());" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->discardDraft('11111111-2222-3333-4444-555555555555', [\n 'expected_version' => 0,\n 'expected_revision' => '11111111-2222-3333-4444-555555555555',\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.routing_rules.discard_draft(\n \"11111111-2222-3333-4444-555555555555\",\n expected_version: 0,\n expected_revision: \"11111111-2222-3333-4444-555555555555\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Cases.RoutingRules.DiscardDraftAsync(\"11111111-2222-3333-4444-555555555555\", new RoutingPublicationPolicyDraftPreconditionRequest\n{\n ExpectedVersion = 0,\n ExpectedRevision = \"11111111-2222-3333-4444-555555555555\",\n});" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/duplicates/": { "post": { "operationId": "duplicates_create", "x-didit-sdk": { "resource": "cases", "method": "find_duplicates", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true } ], "tags": [ "Case Management" ], "requestBody": { "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicateQueryRequest" } }, "application/json": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicateQueryRequest" }, "example": { "subject": { "type": "user", "uuid": "5b9a0000-0000-4000-8000-00000000f00d" } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicateQueryRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicatePage" } } }, "description": "" } }, "security": [ { "ApiKeyAuth": [] } ], "description": "在手动创建案件之前，查看目标主体或所属源记录的现有案件。将同时返回进行中和已解决的调查。每页最多包含 20 个案件；使用 next_offset 请求下一页。", "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.find_duplicates(\n subject={\n \"type\": \"user\",\n \"uuid\": \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.findDuplicates({\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.FindDuplicates(ctx, didit.CaseDuplicateCaseDuplicateQueryRequest{\n\tSubject: didit.Some(didit.CaseDuplicateCaseSubjectInputRequest{\n\t\tType: didit.CaseDuplicateTypeEnum(\"user\"),\n\t\tUUID: \"5b9a0000-0000-4000-8000-00000000f00d\",\n\t}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseDuplicateCaseDuplicateQueryRequest;\nimport me.didit.types.CaseDuplicateCaseSubjectInputRequest;\nimport me.didit.types.CaseDuplicateTypeEnum;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().findDuplicates(CaseDuplicateCaseDuplicateQueryRequest.builder()\n .subject(CaseDuplicateCaseSubjectInputRequest.builder()\n .type(CaseDuplicateTypeEnum.of(\"user\"))\n .uuid(\"5b9a0000-0000-4000-8000-00000000f00d\")\n .build())\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->findDuplicates([\n 'subject' => [\n 'type' => 'user',\n 'uuid' => '5b9a0000-0000-4000-8000-00000000f00d',\n ],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.find_duplicates(\n subject: {\n type: \"user\",\n uuid: \"5b9a0000-0000-4000-8000-00000000f00d\",\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.FindDuplicatesAsync(new CaseDuplicateCaseDuplicateQueryRequest\n{\n Subject = new CaseDuplicateCaseSubjectInputRequest\n {\n Type = \"user\",\n Uuid = \"5b9a0000-0000-4000-8000-00000000f00d\",\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/routing-rules/preview/": { "post": { "summary": "测试案件路由", "description": "需要针对所请求应用的 `read:cases` 权限。根据审核员当前的访问权限、可用性、技能和处理能力，评估当前规则或提供的草稿。该操作不会保存草稿或预留审核员处理能力。", "operationId": "preview_case_routing", "x-didit-sdk": { "resource": "cases.routing_rules", "method": "preview", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingPreview" } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CaseRoutingPreviewRequest" } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.routing_rules.preview(\n source=\"MANUAL\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.routingRules.preview({\n source: \"MANUAL\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.RoutingRules.Preview(ctx, didit.CaseRoutingPreviewRequest{\n\tSource: \"MANUAL\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.CaseRoutingPreviewRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().routingRules().preview(CaseRoutingPreviewRequest.builder()\n .source(CaseRoutingPreviewRequest.Source.of(\"MANUAL\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->routingRules->preview([\n 'source' => 'MANUAL',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.routing_rules.preview(source: \"MANUAL\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.RoutingRules.PreviewAsync(new CaseRoutingPreviewRequest\n{\n Source = \"MANUAL\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/reviewers/": { "get": { "summary": "列出符合资格的案件审核员", "description": "需要针对所请求应用的 `list:cases` 权限。", "operationId": "list_case_reviewers", "x-didit-sdk": { "resource": "cases", "method": "list_reviewers", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Case Assignment" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "responses": { "200": { "description": "成功", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" } } } } } } } } }, "400": { "description": "无效的输入。" }, "403": { "description": "权限不足。" }, "503": { "description": "无法验证审核员的访问权限。请稍后重试。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.list_reviewers()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.listReviewers();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.ListReviewers(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().listReviewers();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->listReviewers();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.list_reviewers\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.ListReviewersAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/cases/blueprints/{blueprint_uuid}/history/": { "get": { "operationId": "list_case_blueprint_history", "x-didit-sdk": { "resource": "cases.blueprints", "method": "list_history", "auth": "api_key", "server": true, "scope": "application" }, "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "in": "path", "name": "blueprint_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true }, { "name": "ordering", "required": false, "in": "query", "description": "对结果进行排序时使用哪个字段。", "schema": { "type": "string" } }, { "name": "limit", "required": false, "in": "query", "description": "每页返回的结果数量。", "schema": { "type": "integer" } }, { "name": "offset", "required": false, "in": "query", "description": "返回结果的起始索引。", "schema": { "type": "integer" } } ], "tags": [ "Case Management" ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CasePublicationPaginatedPolicyRevisionList" } } }, "description": "" }, "403": { "description": "缺少必需的案件权限。" } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nfor item in client.cases.blueprints.list_history(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nfor await (const item of didit.cases.blueprints.listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\niter := client.Cases.Blueprints.ListHistoryAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.CasesBlueprintsListHistoryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nfor (var item : client.cases().blueprints().listHistory(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "cases->blueprints->listHistory('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.cases.blueprints.list_history(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Cases.Blueprints.ListHistoryAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/documents/{documentId}/file/": { "get": { "summary": "下载已签署的证件", "description": "下载电子签名步骤中一份文件的已签署 PDF。请使用决策中 `signatures[].documents[]` 的 `signed_file` 路径。该 PDF 包含向签署人展示的文件，其上加盖了签署人的字段值，并附有证据页（除非 `signature_evidence_page` 已关闭）。高级（AES）PDF 还带有包含时间戳的 PAdES 签名；简单 PDF 则没有数字签名、印章或时间戳。Didit 在返回文件前会对照 `sha256_signed` 进行校验。\n\n适用于用户验证（KYC）和企业验证（KYB）会话。需要 `read:sessions` 权限；您的 API 密钥有效。请参阅[电子签名报告](/zh/core-technology/electronic-signature/report-electronic-signature#下载已签署文档)。", "operationId": "get_v3_session_signature_document_file", "x-didit-sdk": { "resource": "sessions.signatures", "method": "download_document", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "用户验证（KYC）或企业验证（KYB）会话。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "电子签名步骤：`signatures[]` 中项目的 `node_id`。", "schema": { "type": "string", "example": "feature_signature" } }, { "name": "documentId", "in": "path", "required": true, "description": "`signatures[].documents[]` 中证件的 `id`。", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "已签署的 PDF。", "headers": { "Content-Disposition": { "description": "包含文件名的附件。", "schema": { "type": "string", "example": "attachment; filename=\"agreement-signed.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "缺少凭据，或凭据无法读取此会话。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "没有匹配的已签名文档：会话、步骤或文档不存在、已被删除或尚未签名。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Not signed yet": { "summary": "签署人尚未签署", "value": { "code": "signature_not_signed", "detail": "signature_not_signed" } }, "Unknown document": { "summary": "该步骤中不存在此证件", "value": { "code": "signature_not_found", "detail": "signature_not_found" } } } } } }, "409": { "description": "存储的文件与其记录的 SHA-256 不再匹配。未返回任何内容。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Changed file": { "summary": "存储的文件与其哈希值不匹配", "value": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.signatures.download_document(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.signatures.downloadDocument(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Signatures.DownloadDocument(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().signatures().downloadDocument(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->downloadDocument('11111111-2222-3333-4444-555555555555', 'feature_signature', '11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.signatures.download_document(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Signatures.DownloadDocumentAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/evidence/": { "get": { "summary": "下载签名证据", "description": "下载签署人的证据 PDF：级别和格式、签署人、IP 地址、包含原始 SHA-256 及字段值的每份文件，以及每个已签署文件的 SHA-256，对于高级（AES）签名，还包括已验证的身份会话、验证码确认、证书和时间戳。请使用 `signatures[]` 中签署人条目的 `evidence_file` 路径。\n\n当企业验证（KYB）步骤包含多位签署人时，务必传递 `signature_id`：若未传递，该路由会选择该步骤中的一名签署人。需要 `read:sessions` 权限；您的 API 密钥有效。", "operationId": "get_v3_session_signature_evidence", "x-didit-sdk": { "resource": "sessions.signatures", "method": "download_evidence", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "用户验证（KYC）或企业验证（KYB）会话。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "电子签名步骤：`signatures[]` 中项目的 `node_id`。", "schema": { "type": "string", "example": "feature_signature" } }, { "name": "signature_id", "in": "query", "required": false, "description": "`signatures[]` 中签署人条目的 `id`。", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "佐证材料 PDF。", "headers": { "Content-Disposition": { "description": "包含文件名的附件。", "schema": { "type": "string", "example": "attachment; filename=\"signature-evidence.pdf\"" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "403": { "description": "缺少凭据，或凭据无法读取此会话。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "无匹配证据：会话、步骤或签署人不存在、已被删除，或尚未签署。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Not signed yet": { "summary": "签署人尚未签署", "value": { "code": "signature_not_signed", "detail": "signature_not_signed" } }, "Unknown signer": { "summary": "该步骤中不存在此签名", "value": { "code": "signature_not_found", "detail": "signature_not_found" } } } } } }, "409": { "description": "存储的文件与其记录的 SHA-256 不再匹配。未返回任何内容。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Changed file": { "summary": "存储的文件与其哈希值不匹配", "value": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.signatures.download_evidence(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.signatures.downloadEvidence(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n);\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Signatures.DownloadEvidence(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", didit.SessionsSignaturesDownloadEvidenceParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().signatures().downloadEvidence(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->downloadEvidence('11111111-2222-3333-4444-555555555555', 'feature_signature');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.signatures.download_evidence(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\"\n)\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Signatures.DownloadEvidenceAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\");\nawait content.SaveToAsync(\"download.pdf\");" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/fields/{fieldId}/image/": { "get": { "summary": "下载签名图像", "description": "以 PNG 格式下载签署人应用于字段的签名或首字母签名。请使用 `signatures[].documents[].fields[]` 中该字段的 `image_url`。需要 `read:sessions` 权限；您的 API 密钥有效。", "operationId": "get_v3_session_signature_field_image", "x-didit-sdk": { "resource": "sessions.signatures", "method": "download_field_image", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "用户验证（KYC）或企业验证（KYB）会话。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "电子签名步骤：`signatures[]` 中项目的 `node_id`。", "schema": { "type": "string", "example": "feature_signature" } }, { "name": "fieldId", "in": "path", "required": true, "description": "该签名人副本上的字段，如该字段的 `image_url` 中所示。", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "图像。", "content": { "image/png": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "description": "存储的图像与其记录的 SHA-256 不再匹配。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "example": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } }, "403": { "description": "缺少凭据，或凭据无法读取此会话。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "无匹配图像：会话、步骤或字段不存在、已被删除，或未应用任何签名或姓名缩写。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Unknown field": { "summary": "不存在该字段", "value": { "code": "signature_field_not_found", "detail": "signature_field_not_found" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.signatures.download_field_image(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.png\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.signatures.downloadFieldImage(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nawait writeFile(\"download.png\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.Signatures.DownloadFieldImage(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.png\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().signatures().downloadFieldImage(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.png\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->downloadFieldImage('11111111-2222-3333-4444-555555555555', 'feature_signature', '11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.png');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.signatures.download_field_image(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nFile.binwrite(\"download.png\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.Signatures.DownloadFieldImageAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", \"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.png\");" } ] } }, "/v3/session/{sessionId}/signatures/{nodeId}/validate/": { "post": { "summary": "再次验证签名", "description": "重新检查电子签名步骤的已签名证件。Didit 会重新读取每份已签名的 PDF，检查其 SHA-256，对于高级（AES）签名，还会验证 PAdES 签名、证书、吊销数据和时间戳（简单签名没有数字签名，因此仅检查文件完整性），然后将结果保存在每个签署人的 `validation` 中并返回更新后的项目。不会重新签名任何内容。发送 `signature_id` 以检查单个签署人；若不提供，则检查该步骤的所有签署人，如果其中有任何人未签名，则调用失败。\n\n需要 `write:sessions` 权限；您的 API 密钥有效。在控制台中，对应 **Validate again** 按钮。", "operationId": "post_v3_session_signature_validate", "x-didit-sdk": { "resource": "sessions.signatures", "method": "validate", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "用户验证（KYC）或企业验证（KYB）会话。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "nodeId", "in": "path", "required": true, "description": "电子签名步骤：`signatures[]` 中项目的 `node_id`。", "schema": { "type": "string", "example": "feature_signature" } } ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature_id": { "type": "string", "format": "uuid", "description": "`signatures[]` 中某个签署人条目的 `id`。" } } }, "example": { "signature_id": "0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10" } } } }, "responses": { "200": { "description": "已核验的签署人，包含其更新后的 `validation`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "signatures": { "type": "array", "items": { "$ref": "#/components/schemas/SignatureResult" } } } } } } }, "400": { "description": "存储的已签名 PDF 与其签名时记录的 SHA-256 不再匹配。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Document changed": { "summary": "已签名的文件与其哈希值不再匹配", "value": { "code": "signature_document_changed", "detail": "signature_document_changed" } } } } } }, "403": { "description": "缺少凭据，或凭据无法读取此会话。缺少密钥返回 `403`；错误、已撤销或已过期的密钥返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "You do not have permission to perform this action." } } } }, "404": { "description": "没有匹配的签名：会话、步骤或签名者不存在或已被删除。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Unknown signer": { "summary": "该步骤中不存在此签名", "value": { "code": "signature_not_found", "detail": "signature_not_found" } } } } } }, "409": { "description": "该步骤的签名人尚未签名，因此无需验证任何内容。", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "detail": { "type": "string" } } }, "examples": { "Not signed": { "summary": "签名人尚未签名", "value": { "code": "signature_not_signed", "detail": "signature_not_signed" } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.signatures.validate(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n signature_id=\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.signatures.validate(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n {\n signature_id: \"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Signatures.Validate(ctx, \"11111111-2222-3333-4444-555555555555\", \"feature_signature\", didit.SessionsSignaturesValidateParams{\n\tSignatureID: didit.String(\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsSignaturesValidateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().signatures().validate(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", SessionsSignaturesValidateParams.builder()\n .signatureId(\"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->signatures->validate('11111111-2222-3333-4444-555555555555', 'feature_signature', [\n 'signature_id' => '0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.signatures.validate(\n \"11111111-2222-3333-4444-555555555555\",\n \"feature_signature\",\n signature_id: \"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Signatures.ValidateAsync(\"11111111-2222-3333-4444-555555555555\", \"feature_signature\", new SessionsSignaturesValidateParams\n{\n SignatureId = \"0e6c2a8e-6c2f-4b8e-9a51-3f2f6a7d9b10\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/document-ai/{sessionId}/documents/{documentUuid}/": { "patch": { "summary": "更新 Document AI 证件", "description": "在 KYC 或 KYB 会话中修正 Document AI 从已上传证件中提取的字段、设置其审核状态，或同时执行这两项操作。`extracted_data` 必须是 JSON 对象，并按键逐一合并：您发送的键会替换已存储的值（以 `null` 发送的键会存储为 `null`），省略的键则保留其原有值。证件状态会在会话决策中作为其工作流节点的 Document AI 结果；会话状态本身不会重新计算。每次成功的调用（包括未更改任何内容的调用）都会发送一个触发器为 `manual_review` 的 `data.updated` [Webhook](https://docs.didit.me/zh/integration/webhooks)。限定权限范围的 API 密钥需要 `decisions: write` 权限；请参阅 [Document AI](https://docs.didit.me/zh/core-technology/document-ai/overview)。", "operationId": "patch_v3_document_ai_document", "x-didit-sdk": { "resource": "sessions", "method": "update_document_ai_data", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "验证会话的 UUID（由 `POST /v3/session/` 返回的 `session_id`）。支持用户验证（KYC）和企业验证（KYB）会话 ID：服务器会跨两种会话类型解析该 ID。必须是格式正确的 UUID；格式不正确的值无法匹配路由并返回 HTML `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "documentUuid", "in": "path", "required": true, "description": "Document AI 证件的 UUID（`GET /v3/session/{sessionId}/decision/` 中的 `document_ai_documents[].items[].uuid`）。它必须属于路径中的会话。", "schema": { "type": "string", "format": "uuid", "example": "44444444-5555-6666-7777-888888888888" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "extracted_data": { "type": "object", "additionalProperties": true, "description": "字段键（您为该证件配置的键）及其更正后的值。必须是 JSON 对象；按键逐项合并到存储的数据中。请直接省略该字段，而不要发送 `null`，否则会返回 `400`。", "example": { "invoice_number": "INV-2026-0042" } }, "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Not Finished" ], "description": "证件的新审核状态。", "example": "Approved" } } }, "example": { "extracted_data": { "invoice_number": "INV-2026-0042" }, "status": "Approved" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/document-ai/11111111-2222-3333-4444-555555555555/documents/44444444-5555-6666-7777-888888888888/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"extracted_data\": {\"invoice_number\": \"INV-2026-0042\"}, \"status\": \"Approved\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_document_ai_data(\n \"11111111-2222-3333-4444-555555555555\",\n \"44444444-5555-6666-7777-888888888888\",\n extracted_data={\"invoice_number\": \"INV-2026-0042\"},\n status=\"Approved\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateDocumentAiData(\n \"11111111-2222-3333-4444-555555555555\",\n \"44444444-5555-6666-7777-888888888888\",\n {\n extracted_data: { invoice_number: \"INV-2026-0042\" },\n status: \"Approved\",\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateDocumentAiData(ctx, \"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", didit.SessionsUpdateDocumentAiDataParams{\n\tExtractedData: didit.Some(map[string]any{\"invoice_number\": \"INV-2026-0042\"}),\n\tStatus: didit.Some(didit.SessionsUpdateDocumentAiDataParamsStatus(\"Approved\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUpdateDocumentAiDataParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateDocumentAiData(\"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", SessionsUpdateDocumentAiDataParams.builder()\n .extractedData(Map.of(\"invoice_number\", \"INV-2026-0042\"))\n .status(SessionsUpdateDocumentAiDataParams.Status.of(\"Approved\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateDocumentAiData('11111111-2222-3333-4444-555555555555', '44444444-5555-6666-7777-888888888888', [\n 'extracted_data' => ['invoice_number' => 'INV-2026-0042'],\n 'status' => 'Approved',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_document_ai_data(\n \"11111111-2222-3333-4444-555555555555\",\n \"44444444-5555-6666-7777-888888888888\",\n extracted_data: { invoice_number: \"INV-2026-0042\" },\n status: \"Approved\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateDocumentAiDataAsync(\"11111111-2222-3333-4444-555555555555\", \"44444444-5555-6666-7777-888888888888\", new SessionsUpdateDocumentAiDataParams\n{\n ExtractedData = new Dictionary { [\"invoice_number\"] = \"INV-2026-0042\" },\n Status = new SessionsUpdateDocumentAiDataParamsStatus(\"Approved\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "证件已更新。返回合并后的证件。", "content": { "application/json": { "schema": { "type": "object", "required": [ "uuid", "document_key", "original_filename", "file_url", "status", "extracted_data" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "证件标识符。" }, "document_key": { "type": "string", "description": "此上传内容所对应的已配置证件。" }, "original_filename": { "type": "string", "nullable": true, "description": "上传证件时使用的文件名。" }, "file_url": { "type": "string", "nullable": true, "description": "已上传文件的存储路径。这不是下载链接：请从会话决策中读取预签名的 `file_url` 来下载文件。" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "证件的审核状态。" }, "extracted_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "合并后提取的所有字段，以字段键作为键名。" } } }, "example": { "uuid": "44444444-5555-6666-7777-888888888888", "document_key": "invoice", "original_filename": "invoice-2026-09.pdf", "file_url": "document_ai/11111111-2222-3333-4444-555555555555-66666666-7777-8888-9999-000000000000.pdf", "status": "Approved", "extracted_data": { "invoice_number": "INV-2026-0042", "total_amount": 1250.0, "issue_date": "2026-09-01" } } } } }, "400": { "description": "验证错误，在查询证件之前进行检查：`status` 不是允许的值之一，或者 `extracted_data` 传入了 `null`。", "content": { "application/json": { "examples": { "Invalid status": { "summary": "status 不在枚举中", "value": { "status": [ "\"Rejected\" is not a valid choice." ] } }, "Null extracted_data": { "summary": "extracted_data 为 null", "value": { "extracted_data": [ "This field may not be null." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除或超出了限定作用域密钥的限制，或者不包含具有此 UUID 的当前证件。会话查找在凭证检查之前执行，因此即使没有有效密钥，未知的 `sessionId` 也会返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "summary": "不存在具有此 ID 的会话，或该会话已被删除", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "会话超出了限定作用域密钥的限制（对于刚刚删除的会话也会返回此错误）", "value": { "detail": "Session not found." } }, "Unknown document": { "summary": "documentUuid 不属于该会话", "value": { "detail": "Document AI document not found." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟 300 次写入（POST、PATCH、DELETE）请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 响应头显示了额度。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/aml/dataset-freshness/": { "get": { "summary": "获取 AML 数据集的新鲜程度", "description": "按来源类别（`sanctions`、`pep`、`warnings`、`adverse_media`）报告 AML 筛查背后的数据集时效性，作为[持续 AML 监控](https://docs.didit.me/zh/core-technology/aml-screening/continuous-monitoring-aml-screening#证明监控已运行)的审计证据。该响应是全平台范围的：路径中没有会话，请求体中没有客户数据，对每个应用返回相同的答案。\n\n对于接受的密钥始终返回 `200`。请先检查 `availability`：当其不是 `available` 时，`dataset_freshness` 为 `null`。日期绝不会预估：数据集未报告日期的类别不会出现在 `sources` 中，而仅有部分数据集报告了日期的类别其 `oldest_updated_at: null`。读数是在持续监控运行期间采集的，而不是在每次调用时采集；`captured_at` 说明了采集时间。\n\n受限 API 密钥需要 `sessions: read` 权限；仅限于某些工作流或仅限于已通过的会话的密钥无法调用此 endpoint。不收取任何费用。", "operationId": "get_aml_dataset_freshness", "x-didit-sdk": { "resource": "aml", "method": "retrieve_dataset_freshness", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "parameters": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/aml/dataset-freshness/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.aml.retrieve_dataset_freshness()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.aml.retrieveDatasetFreshness();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.AML.RetrieveDatasetFreshness(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.aml().retrieveDatasetFreshness();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "aml->retrieveDatasetFreshness();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.aml.retrieve_dataset_freshness\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Aml.RetrieveDatasetFreshnessAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "最新的数据集新鲜度读数，如果无法获取，则为带有原因的 `null`。", "content": { "application/json": { "schema": { "type": "object", "required": [ "dataset_freshness", "availability" ], "properties": { "dataset_freshness": { "allOf": [ { "$ref": "#/components/schemas/AMLDatasetFreshness" } ], "nullable": true, "description": "最新读数，当 `availability` 不是 `available` 时为 `null`。" }, "availability": { "type": "string", "enum": [ "available", "not_configured", "not_yet_collected" ], "description": "`available` 表示存在读数；`not_configured` 表示在此环境中未收集数据集日期；`not_yet_collected` 表示已配置收集但尚无读数。" } } }, "examples": { "Available": { "value": { "dataset_freshness": { "captured_at": "2026-10-17T06:00:12.345678+00:00", "provider": "aml_data_source", "catalog_version": "20261017054500-abc", "sources": { "sanctions": { "last_updated_at": "2026-10-17T04:10:00+00:00", "oldest_updated_at": "2026-10-15T22:30:00+00:00", "dataset_count": 48, "dated_dataset_count": 48 }, "pep": { "last_updated_at": "2026-10-16T23:05:00+00:00", "oldest_updated_at": null, "dataset_count": 12, "dated_dataset_count": 11 } } }, "availability": "available" } }, "Not collected yet": { "value": { "dataset_freshness": null, "availability": "not_yet_collected" } } } } } }, "401": { "description": "API 密钥已过期。仅创建时设置了到期日期的密钥才会过期；超过该日期后，使用它的每次请求都会返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "请求不被允许。缺失密钥将返回常规错误信息；错误、已撤销或已过期的密钥将收到 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "value": { "detail": "This API key has no read access to sessions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "使用此 API 密钥的 GET 请求每分钟超过 600 次。请等待 `Retry-After` 中指定的秒数，然后再重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "距离当前一分钟窗口重置的秒数。", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "在此预算中每分钟允许的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "窗口重置的 Unix 时间。", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/": { "get": { "summary": "列出名单", "description": "按由新到旧的顺序返回应用的名单：Didit 预配的系统名单（每种条目类型一个黑名单、**High Risk Countries** 自定义名单以及任何系统白名单）以及您创建的白名单和自定义名单。使用 `list_type` 和 `entry_type` 进行过滤；已删除的名单绝不会显示。结果通过 `limit` 和 `offset` 进行分页。作用域 API 密钥需要 `workflows: read` 权限。有关每种名单类型的作用，请参阅[名单](https://docs.didit.me/zh/management-api/lists/overview)。", "operationId": "list_lists", "x-didit-sdk": { "resource": "lists", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_type", "in": "query", "required": false, "description": "仅包含此类型的列表。", "schema": { "type": "string", "enum": [ "blocklist", "allowlist", "custom" ] } }, { "name": "entry_type", "in": "query", "required": false, "description": "仅包含此条目类型的列表。", "schema": { "type": "string", "enum": [ "face", "document", "phone", "email", "ip_address", "device_fingerprint", "wallet_address", "bank_account", "country", "user", "business", "key" ] } }, { "name": "ordering", "in": "query", "required": false, "description": "排序顺序：`-created_at`（从新到旧，默认值）或 `created_at`（从旧到新）。", "schema": { "type": "string", "enum": [ "-created_at", "created_at" ], "default": "-created_at" } }, { "name": "limit", "in": "query", "required": false, "description": "页面大小。默认为 50。大于 1000000 的值返回 `400`；0、负数或非数字值将回退为 50。", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 } }, { "name": "offset", "in": "query", "required": false, "description": "要返回的第一项的从零开始的索引。建议跟随 `next`。大于 1000000 的值将返回 `400`；负数或非数字值将回退为 0。", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/lists/?list_type=blocklist' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.lists.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.lists.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Lists.ListAutoPaging(ctx, didit.ListsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.lists().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "lists->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Lists.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "一页列表。", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "符合过滤条件的名单总数。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceList" } } } }, "examples": { "Lists": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "22222222-3333-4444-5555-666666666666", "name": "Trusted office IPs", "description": "Office egress ranges", "list_type": "allowlist", "entry_type": "ip_address", "is_system": false, "entry_count": 3, "last_entry_added_at": "2026-10-02T08:15:27.501334Z", "created_at": "2026-09-30T13:20:45.889120Z", "updated_at": "2026-09-30T13:20:45.889120Z" }, { "uuid": "11111111-2222-3333-4444-555555555555", "name": "Face Blocklist", "description": "Blocked biometric faces. When a face matching an entry in this list is detected during liveness verification, the session will be automatically declined.", "list_type": "blocklist", "entry_type": "face", "is_system": true, "entry_count": 12, "last_entry_added_at": "2026-10-09T16:42:03.118204Z", "created_at": "2026-01-14T10:02:11.402917Z", "updated_at": "2026-01-14T10:02:11.402917Z" } ] } } } } } }, "400": { "description": "查询参数无效。", "content": { "application/json": { "examples": { "Unknown list type": { "value": { "list_type": [ "\"denylist\" is not a valid choice." ] } }, "Unsupported ordering": { "value": { "ordering": [ "\"name\" is not a valid choice." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: read`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "429": { "description": "已超出每个 API 密钥每分钟 600 次请求的共享读取限制。在重试之前请遵循 `Retry-After`。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建列表", "description": "在 API 密钥所属的应用中创建白名单或自定义名单。无法创建黑名单：Didit 为每种条目类型预配一个系统黑名单，您可以通过[创建名单条目](https://docs.didit.me/zh/management-api/lists/create-entry)向其添加内容。`entry_type` 在创建后不可更改，并决定如何验证和匹配条目值。白名单条目将匹配项标记为可信（例如，人脸白名单会跳过重复人脸操作），且绝不会覆盖黑名单匹配；可使用 `value_type: \"list\"` 在工作流或交易规则条件中引用任意名单。限定权限范围的 API 密钥需要 `workflows: write` 权限。", "operationId": "create_list", "x-didit-sdk": { "resource": "lists", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "list_type", "entry_type" ], "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "名单名称。必须与该应用的所有其他名单名称不同，包括系统名单。" }, "description": { "type": "string", "default": "", "description": "可选的自由文本描述。" }, "list_type": { "type": "string", "enum": [ "allowlist", "custom" ], "description": "`allowlist` 或 `custom`。若为 `blocklist` 则以 `400` 拒绝。" }, "entry_type": { "type": "string", "enum": [ "face", "document", "phone", "email", "ip_address", "device_fingerprint", "wallet_address", "bank_account", "country", "user", "business", "key" ], "description": "该名单包含的内容：`face`、`document`（证件号码）、`phone`、`email`、`ip_address`（IP 地址或 CIDR 范围）、`device_fingerprint`、`wallet_address`、`bank_account`、`country`（ISO 3166-1 alpha-3）、`user` 或 `business`（您的 `vendor_data`），或 `key`（任意字符串）。它决定了条目值的验证和匹配方式。后续无法更改。" } } }, "examples": { "IP allowlist": { "value": { "name": "Trusted office IPs", "description": "Office egress ranges", "list_type": "allowlist", "entry_type": "ip_address" } }, "Custom country list": { "value": { "name": "Enhanced due diligence countries", "list_type": "custom", "entry_type": "country" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/lists/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"name\": \"Trusted office IPs\",\n \"description\": \"Office egress ranges\",\n \"list_type\": \"allowlist\",\n \"entry_type\": \"ip_address\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.create(\n name=\"Trusted office IPs\",\n description=\"Office egress ranges\",\n list_type=\"allowlist\",\n entry_type=\"ip_address\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.create({\n name: \"Trusted office IPs\",\n description: \"Office egress ranges\",\n list_type: \"allowlist\",\n entry_type: \"ip_address\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Create(ctx, didit.ListsCreateParams{\n\tName: \"Trusted office IPs\",\n\tDescription: didit.String(\"Office egress ranges\"),\n\tListType: \"allowlist\",\n\tEntryType: \"ip_address\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().create(ListsCreateParams.builder()\n .name(\"Trusted office IPs\")\n .description(\"Office egress ranges\")\n .listType(ListsCreateParams.ListType.of(\"allowlist\"))\n .entryType(ListsCreateParams.EntryType.of(\"ip_address\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->create([\n 'name' => 'Trusted office IPs',\n 'description' => 'Office egress ranges',\n 'list_type' => 'allowlist',\n 'entry_type' => 'ip_address',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.create(\n name: \"Trusted office IPs\",\n description: \"Office egress ranges\",\n list_type: \"allowlist\",\n entry_type: \"ip_address\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.CreateAsync(new ListsCreateParams\n{\n Name = \"Trusted office IPs\",\n Description = \"Office egress ranges\",\n ListType = \"allowlist\",\n EntryType = \"ip_address\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "名单已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceList" }, "examples": { "New allowlist": { "value": { "uuid": "22222222-3333-4444-5555-666666666666", "name": "Trusted office IPs", "description": "Office egress ranges", "list_type": "allowlist", "entry_type": "ip_address", "is_system": false, "entry_count": 0, "last_entry_added_at": null, "created_at": "2026-10-12T09:15:44.031876Z", "updated_at": "2026-10-12T09:15:44.031876Z" } } } } } }, "400": { "description": "请求体无效。", "content": { "application/json": { "examples": { "Blocklist refused": { "value": { "list_type": [ "Cannot create additional blocklist lists. System blocklists are auto-created for each application." ] } }, "Duplicate name": { "value": { "name": [ "A list with this name already exists for this application." ] } }, "Missing fields": { "value": { "name": [ "This field is required." ], "list_type": [ "This field is required." ], "entry_type": [ "This field is required." ] } }, "Unknown entry type": { "value": { "entry_type": [ "\"iban\" is not a valid choice." ] } }, "Name too long": { "value": { "name": [ "Ensure this field has no more than 255 characters." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/": { "get": { "summary": "获取列表", "description": "返回该应用的一个列表及其条目数量和最新条目的添加时间。属于其他应用或已被删除的列表将返回 `404`。此接口仅返回列表本身：如需读取其具体值，请使用[获取列表条目](https://docs.didit.me/zh/management-api/lists/list-entries)。有作用域限制的 API 密钥需要 `workflows: read` 权限。", "operationId": "get_list", "x-didit-sdk": { "resource": "lists", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "列表的 UUID，如列出列表或创建列表所返回。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "名单。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceList" }, "examples": { "System face blocklist": { "value": { "uuid": "11111111-2222-3333-4444-555555555555", "name": "Face Blocklist", "description": "Blocked biometric faces. When a face matching an entry in this list is detected during liveness verification, the session will be automatically declined.", "list_type": "blocklist", "entry_type": "face", "is_system": true, "entry_count": 12, "last_entry_added_at": "2026-10-09T16:42:03.118204Z", "created_at": "2026-01-14T10:02:11.402917Z", "updated_at": "2026-01-14T10:02:11.402917Z" } } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: read`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "404": { "description": "API 密钥所属的应用中不存在具有此 UUID 的列表，或者已被删除。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No List matches the given query." } } } } } }, "429": { "description": "已超出每个 API 密钥每分钟 600 次请求的共享读取限制。在重试之前请遵循 `Retry-After`。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新列表", "description": "重命名名单或修改其描述。系统仅读取 `name` 和 `description`；其他任何字段均被忽略，因此 `list_type` 和 `entry_type` 会保留创建时的值。系统名单不可修改，调用将返回 `400`。响应仅包含 `name` 和 `description`：如需获取完整名单，请调用[获取名单](https://docs.didit.me/zh/management-api/lists/get)。限定范围的 API 密钥需要 `workflows: write` 权限。", "operationId": "update_list", "x-didit-sdk": { "resource": "lists", "method": "update", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "列表的 UUID，如列出列表或创建列表所返回。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "新名称。必须与该应用的所有其他列表名称不同。" }, "description": { "type": "string", "description": "新描述。发送空字符串可清除该值。" } } }, "examples": { "Rename": { "value": { "name": "Trusted office and VPN IPs" } }, "Rename and describe": { "value": { "name": "Trusted office and VPN IPs", "description": "Office egress ranges and the corporate VPN" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"name\": \"Trusted office and VPN IPs\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.update(\n \"11111111-2222-3333-4444-555555555555\",\n name=\"Trusted office and VPN IPs\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.update(\"11111111-2222-3333-4444-555555555555\", {\n name: \"Trusted office and VPN IPs\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Update(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsUpdateParams{\n\tName: didit.String(\"Trusted office and VPN IPs\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsUpdateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().update(\"11111111-2222-3333-4444-555555555555\", ListsUpdateParams.builder()\n .name(\"Trusted office and VPN IPs\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->update('11111111-2222-3333-4444-555555555555', [\n 'name' => 'Trusted office and VPN IPs',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.update(\n \"11111111-2222-3333-4444-555555555555\",\n name: \"Trusted office and VPN IPs\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.UpdateAsync(\"11111111-2222-3333-4444-555555555555\", new ListsUpdateParams\n{\n Name = \"Trusted office and VPN IPs\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "名单已更新。仅返回可编辑字段。", "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "description" ], "properties": { "name": { "type": "string", "description": "更新后名单的名称。" }, "description": { "type": "string", "description": "更新后名单的描述。" } } }, "examples": { "Renamed": { "value": { "name": "Trusted office and VPN IPs", "description": "Office egress ranges" } } } } } }, "400": { "description": "该名单为系统名单，或请求体无效。", "content": { "application/json": { "examples": { "System list": { "value": { "non_field_errors": [ "System lists cannot be modified." ] } }, "Duplicate name": { "value": { "name": [ "A list with this name already exists for this application." ] } }, "Blank name": { "value": { "name": [ "This field may not be blank." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "API 密钥所属的应用中不存在具有此 UUID 的列表，或者已被删除。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No List matches the given query." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] }, "delete": { "summary": "删除名单", "description": "删除白名单或自定义名单及其条目。删除操作不可逆：该名单及其条目将不再出现在任何读取操作中，引用该名单的工作流和交易规则条件此后将把其视为空名单进行评估。已完成评估的会话和交易将保留其结果，该名称可重新用于新名单。系统名单无法删除，会返回 `400`；如需清空系统名单，请[删除其条目](https://docs.didit.me/zh/management-api/lists/delete-entry)。限定权限的 API 密钥需要具备 `workflows: write` 权限。", "operationId": "delete_list", "x-didit-sdk": { "resource": "lists", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "列表的 UUID，如列出列表或创建列表所返回。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.lists.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.lists.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Lists.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.lists().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "lists->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Lists.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "名单及其条目已被删除。无响应体。" }, "400": { "description": "该名单为系统名单。", "content": { "application/json": { "examples": { "System list": { "value": { "detail": "System lists cannot be deleted." } } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "API 密钥所属的应用中不存在具有此 UUID 的列表，或者已被删除。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No List matches the given query." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/entries/": { "get": { "summary": "列出名单条目", "description": "按由新到旧的顺序返回单个名单的当前条目。`search` 会不区分大小写地匹配条目的部分 `value` 或 `display_label`，而 `reference_session_id` 则将结果缩小为取自某个人验证会话的条目。`metadata` 中的图片 URL 是在每次调用时重新签发的短期有效签名 URL；未拥有 `media: read` 权限的作用域 API 密钥将在相应位置接收到 `null`。作用域 API 密钥需要 `workflows: read` 权限。", "operationId": "list_list_entries", "x-didit-sdk": { "resource": "lists.entries", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "列表的 UUID，如列出列表或创建列表所返回。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "search", "in": "query", "required": false, "description": "条目的 `value` 或 `display_label` 必须包含的不区分大小写的文本。", "schema": { "type": "string" } }, { "name": "reference_session_id", "in": "query", "required": false, "description": "仅从该人员验证会话中获取的条目，例如查看其哪些人脸已被列出。", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "页面大小。默认为 50。大于 1000000 的值返回 `400`；0、负数或非数字值将回退为 50。", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 } }, { "name": "offset", "in": "query", "required": false, "description": "要返回的第一项的从零开始的索引。建议跟随 `next`。大于 1000000 的值将返回 `400`；负数或非数字值将回退为 0。", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/?search=example.com' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.lists.entries.list(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.lists.entries.list(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Lists.Entries.ListAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.lists().entries().list(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "lists->entries->list('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.entries.list(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Lists.Entries.ListAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "一页条目，按最新优先排序。", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "符合过滤条件的条目总数。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ComplianceListEntry" } } } }, "examples": { "Entries": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "value": "X1234567", "display_label": "Jane Doe - X1234567", "comment": "", "added_by": "api", "reference_session_id": "33333333-4444-5555-6666-777777777777", "reference_session_number": 1042, "reference_session_type": "kyc", "reference_object_uuid": "66666666-7777-8888-9999-000000000000", "metadata": { "full_name": "Jane Doe", "issuing_state": "ESP", "document_type": "ID", "region": "", "document_number": "X1234567" }, "created_at": "2026-10-12T10:06:12.774915Z" }, { "uuid": "eeeeeeee-ffff-0000-1111-222222222222", "value": "y7654321", "display_label": "", "comment": "Reported by a partner", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": null, "metadata": null, "created_at": "2026-10-03T07:48:30.552810Z" } ] } } } } } }, "400": { "description": "查询参数无效。", "content": { "application/json": { "examples": { "Invalid session id": { "value": { "reference_session_id": [ "Must be a valid UUID." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: read`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "404": { "description": "API 密钥所属的应用中不存在具有此 UUID 的列表，或者已被删除。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "List not found." } } } } } }, "429": { "description": "已超出每个 API 密钥每分钟 600 次请求的共享读取限制。在重试之前请遵循 `Retry-After`。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建列表条目", "description": "通过以下三种方式之一向名单添加一个条目：通过 `value` 添加；通过带有 `reference_session_id` 的验证会话添加，此时 Didit 会从该会话中读取该名单条目类型的最新记录并将条目与其关联；或通过带有 `reference_object_uuid` 和 `metadata.reference_type` 的 `value` 添加，指向交易、用户或企业。在系统人脸、证件、电话和邮箱黑名单上，从会话中读取的记录也会被标记为列入黑名单，因此新的匹配会话将被拒绝；在系统用户和企业黑名单上，匹配的用户或企业将被设置为 `BLOCKED`。已完成的会话和交易不会被修改。限定范围的 API 密钥需要具备 `workflows: write` 权限。各模式详情请参阅[创建名单条目](https://docs.didit.me/zh/management-api/lists/create-entry)。", "operationId": "create_list_entry", "x-didit-sdk": { "resource": "lists.entries", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "要添加到的列表的 UUID。对于您只有图像的人脸，请改用上传人脸至列表。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "发送 `value`、`reference_session_id` 或两者。适用哪些字段取决于名单的 `entry_type`。", "properties": { "value": { "type": "string", "description": "要列出的值，根据列表的 `entry_type` 进行验证：`email` 为有效的邮箱地址；`phone` 为有效的国际号码，以 E.164 格式存储；`ip_address` 为 IP 地址或 CIDR 范围（例如 `10.0.0.0/8`）；`device_fingerprint` 为字母、数字、`-`、`_`、`:` 和 `.` 组成的至少 8 个字符（黑名单会拒绝多个不同设备报告过的指纹）；`country` 为 ISO 3166-1 alpha-2 或 alpha-3 代码，以 alpha-3 格式存储；`user` 和 `business` 为 `vendor_data`；任何其他类型为非空字符串。除电话号码和国家/地区代码外均以小写形式存储，列表对每个值只保存一次（不区分大小写）。除非发送了 `reference_session_id`，否则为必填项；当 `face_image_source` 为证件采集时必须留空。" }, "reference_session_id": { "type": "string", "format": "uuid", "description": "从您应用的个人验证或企业验证会话中提取值。Didit 读取该会话中名单条目类型（`face`、`document`、`phone`、`email`、`ip_address` 或 `device_fingerprint`）的最新记录，将条目链接到该会话和该记录，并为证件填充 `display_label` 和 `metadata`。对于 `device_fingerprint` 黑名单，仅包含设备类别指纹或在多台设备上完成的会话会被拒绝：请将精确指纹作为 `value` 发送。对于其他条目类型，或当会话没有此类记录时，也请发送 `value`；随后将存储您的 `value`，且条目仍会链接到该会话。" }, "reference_object_uuid": { "type": "string", "format": "uuid", "description": "当条目并非来自会话时，其所代表记录的 UUID：交易 UUID，或用户或企业的 `didit_internal_id`。与 `metadata.reference_type` 配合使用。当 `reference_session_id` 提供了记录时，将被会话的记录替换。" }, "face_image_source": { "type": "string", "enum": [ "liveness", "front_image_camera_front", "back_image_camera_front" ], "default": "liveness", "description": "带有 `reference_session_id` 的人脸名单：人脸取自该会话的哪张图像。`liveness`（默认值）为活体自拍照。`front_image_camera_front` 和 `back_image_camera_front` 是用户拍摄证件正面或背面时前置摄像头拍摄的自拍照：仅在系统人脸黑名单上被接受，且需带有 `reference_session_id` 以及空的 `value`。每张自拍照只能添加一次，且必须显示一张清晰的人脸。" }, "reference_node_id": { "type": "string", "nullable": true, "maxLength": 100, "description": "当 `face_image_source` 为证件采集时：对于具有多个节点的身份证件验证工作流，指定要使用其自拍照的身份证件验证节点。默认使用包含该图像的最新身份证件验证。若为 `liveness` 则会被拒绝。" }, "display_label": { "type": "string", "maxLength": 512, "description": "便于人类阅读的标签。当为空时，Didit 会尽可能从会话中推导出一个（例如持有人姓名和证件号码）。" }, "comment": { "type": "string", "description": "自由文本备注，例如列入名单的原因。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "随条目一同存储并按原样返回的自由格式 JSON。使用 `reference_type` 和 `reference_id` 以便控制台能链接回源头。`reference_image_url` 和 `front_image_url` 仅由 Didit 设置，如果您发送它们将被丢弃。对于从会话中读取的条目，Didit 的键将与您的键合并。", "properties": { "reference_type": { "type": "string", "enum": [ "transaction", "vendor_user", "vendor_business" ], "description": "`reference_object_uuid` 指向的内容。" }, "reference_id": { "type": "string", "description": "源记录的标识符。" } } } } }, "examples": { "By value": { "value": { "value": "+14155552671", "comment": "Reported fraud" } }, "From a session": { "value": { "reference_session_id": "33333333-4444-5555-6666-777777777777" } }, "Face from a document-capture selfie": { "value": { "reference_session_id": "33333333-4444-5555-6666-777777777777", "face_image_source": "front_image_camera_front" } }, "From a transaction": { "value": { "value": "0x52908400098527886E0F7030069857D2E4169EE7", "reference_object_uuid": "55555555-6666-7777-8888-999999999999", "comment": "Linked to a chargeback", "metadata": { "reference_type": "transaction", "reference_id": "55555555-6666-7777-8888-999999999999" } } }, "Country": { "value": { "value": "PRK", "comment": "Sanctioned jurisdiction" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"value\": \"+14155552671\", \"comment\": \"Reported fraud\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.entries.create(\n \"11111111-2222-3333-4444-555555555555\",\n value=\"+14155552671\",\n comment=\"Reported fraud\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.entries.create(\"11111111-2222-3333-4444-555555555555\", {\n value: \"+14155552671\",\n comment: \"Reported fraud\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.Create(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesCreateParams{\n\tValue: didit.String(\"+14155552671\"),\n\tComment: didit.String(\"Reported fraud\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsEntriesCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().entries().create(\"11111111-2222-3333-4444-555555555555\", ListsEntriesCreateParams.builder()\n .value(\"+14155552671\")\n .comment(\"Reported fraud\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->entries->create('11111111-2222-3333-4444-555555555555', [\n 'value' => '+14155552671',\n 'comment' => 'Reported fraud',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.entries.create(\n \"11111111-2222-3333-4444-555555555555\",\n value: \"+14155552671\",\n comment: \"Reported fraud\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.Entries.CreateAsync(\"11111111-2222-3333-4444-555555555555\", new ListsEntriesCreateParams\n{\n Value = \"+14155552671\",\n Comment = \"Reported fraud\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "条目已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceListEntry" }, "examples": { "By value": { "value": { "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "value": "+14155552671", "display_label": "", "comment": "Reported fraud", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": null, "metadata": null, "created_at": "2026-10-12T10:04:51.220391Z" } }, "Document from a session": { "value": { "uuid": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff", "value": "X1234567", "display_label": "Jane Doe - X1234567", "comment": "", "added_by": "api", "reference_session_id": "33333333-4444-5555-6666-777777777777", "reference_session_number": 1042, "reference_session_type": "kyc", "reference_object_uuid": "66666666-7777-8888-9999-000000000000", "metadata": { "full_name": "Jane Doe", "issuing_state": "ESP", "document_type": "ID", "region": "", "document_number": "X1234567" }, "created_at": "2026-10-12T10:06:12.774915Z" } }, "From a transaction": { "value": { "uuid": "dddddddd-eeee-ffff-0000-111111111111", "value": "0x52908400098527886e0f7030069857d2e4169ee7", "display_label": "", "comment": "Linked to a chargeback", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": "55555555-6666-7777-8888-999999999999", "metadata": { "reference_type": "transaction", "reference_id": "55555555-6666-7777-8888-999999999999" }, "created_at": "2026-10-12T10:20:40.117062Z" } } } } } }, "400": { "description": "请求体无效、该值已在列表中，或会话无法提供该值。", "content": { "application/json": { "examples": { "Nothing to list": { "value": { "value": [ "Either 'value' or 'reference_session_id' must be provided." ] } }, "Duplicate value": { "value": { "value": [ "An entry with this value already exists in this list." ] } }, "Invalid phone": { "value": { "value": [ "Invalid phone number. Provide a valid international number (e.g. +1234567890)." ] } }, "Invalid IP": { "value": { "value": [ "Invalid IP address or CIDR range (e.g. 192.168.1.1 or 10.0.0.0/24)." ] } }, "Invalid country": { "value": { "value": [ "Invalid country code: XX. Provide a valid ISO 3166-1 alpha-2 or alpha-3 country code." ] } }, "Device-class fingerprint": { "value": { "value": [ "This value is a device-class fingerprint: several distinct devices have reported it, so blocklisting it would decline unrelated people. Block the user by document, face, email or phone instead." ] } }, "Unknown session": { "value": { "reference_session_id": [ "Session not found or does not belong to this application." ] } }, "No data in session": { "value": { "value": [ "Either provide a 'value' or ensure the session contains data for this entry type." ] } }, "Selfie on another list": { "value": { "face_image_source": [ "A document-capture selfie can only be added to the face blocklist." ] } }, "No clear face in selfie": { "value": { "face_image_source": [ "No clear face was found in this selfie, so it cannot be blocklisted." ] } }, "Selfie already listed": { "value": { "face_image_source": [ "This selfie is already in the blocklist." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "API 密钥所属的应用中不存在具有此 UUID 的列表，或者已被删除。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "List not found." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" }, "503": { "description": "证件拍摄自拍照的人脸分析暂时不可用。未添加任何内容；请稍后重试。", "content": { "application/json": { "examples": { "Unavailable": { "value": { "detail": "Service temporarily unavailable. Please try again later." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/entries/{entry_uuid}/": { "delete": { "summary": "删除名单条目", "description": "从名单中删除一个条目，包括系统名单。该条目将立即停止匹配，且删除操作不可逆：如需再次将该值列入名单，请创建新条目。在系统人脸、证件、电话或邮箱黑名单中，该条目所代表的记录将不再被标记为已列入黑名单；在系统用户或企业黑名单中，应用中 `vendor_data` 等于该条目值（或 `didit_internal_id` 等于其 `reference_object_uuid`）且处于 `BLOCKED` 状态的用户或企业将恢复为 `ACTIVE`。已经结束的会话和交易将保留其状态。限定权限的 API 密钥需要具备 `workflows: write` 权限。", "operationId": "delete_list_entry", "x-didit-sdk": { "resource": "lists.entries", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "包含该条目的列表的 UUID。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "entry_uuid", "in": "path", "required": true, "description": "条目的 UUID，如列出列表条目或创建列表条目所返回。", "schema": { "type": "string", "format": "uuid" }, "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.lists.entries.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.lists.entries.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Lists.Entries.Delete(ctx, \"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.lists().entries().delete(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");" }, { "lang": "php", "label": "PHP", "source": "lists->entries->delete('11111111-2222-3333-4444-555555555555', 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.lists.entries.delete(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Lists.Entries.DeleteAsync(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");" } ], "responses": { "204": { "description": "条目已删除。无响应体。" }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "此列表中不存在具有此 UUID 的条目、列表不在 API 密钥所属的应用中或已被删除，或者该条目已被删除。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No ListEntry matches the given query." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/lists/{list_uuid}/entries/face-upload/": { "post": { "summary": "将人脸上传至名单", "description": "通过 Base64 编码的 JPEG 或 PNG 图像向人脸黑名单或人脸白名单添加人脸，适用于您没有可供引用的验证会话的情况。Didit 会检测图像中的人脸，采用最大的一张，并创建一个条目，其 `value` 和 `reference_object_uuid` 为新人脸的 UUID。列入黑名单的人脸将拒绝与其匹配的新会话；列入白名单的人脸将跳过重复人脸操作，且绝不会覆盖黑名单匹配。在沙盒应用中，图像不会被分析，条目也不会匹配任何内容。有作用域限制的 API 密钥需要具备 `workflows: write` 权限。若要从现有会话中将人脸列入名单，请改用带 `reference_session_id` 的[创建名单条目](https://docs.didit.me/zh/management-api/lists/create-entry)。", "operationId": "upload_list_entry_face", "x-didit-sdk": { "resource": "lists.entries", "method": "upload_face", "auth": "api_key", "server": true }, "tags": [ "Lists" ], "parameters": [ { "name": "list_uuid", "in": "path", "required": true, "description": "`entry_type: face` 且 `list_type: blocklist` 或 `allowlist` 的列表的 UUID。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "image" ], "properties": { "image": { "type": "string", "format": "byte", "description": "Base64 编码的 JPEG 或 PNG，解码后最大 2 MB，展示清晰可见的人脸。请发送纯 Base64 字符串，不要包含 `data:image/...;base64,` 前缀。" }, "comment": { "type": "string", "default": "", "description": "可选的自由文本备注，例如列入名单的原因。" } } }, "examples": { "Face image": { "value": { "image": "/9j/4AAQSkZJRgABAQAAAQABAAD...", "comment": "Known fraud attempt" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/lists/11111111-2222-3333-4444-555555555555/entries/face-upload/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d \"{\\\"image\\\": \\\"$(base64 < face.jpg | tr -d '\\n')\\\", \\\"comment\\\": \\\"Known fraud attempt\\\"}\"" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.lists.entries.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image=\"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n comment=\"Known fraud attempt\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.lists.entries.uploadFace(\"11111111-2222-3333-4444-555555555555\", {\n image: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n comment: \"Known fraud attempt\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Lists.Entries.UploadFace(ctx, \"11111111-2222-3333-4444-555555555555\", didit.ListsEntriesUploadFaceParams{\n\tImage: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n\tComment: didit.String(\"Known fraud attempt\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.ListsEntriesUploadFaceParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.lists().entries().uploadFace(\"11111111-2222-3333-4444-555555555555\", ListsEntriesUploadFaceParams.builder()\n .image(\"/9j/4AAQSkZJRgABAQAAAQABAAD...\")\n .comment(\"Known fraud attempt\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "lists->entries->uploadFace('11111111-2222-3333-4444-555555555555', [\n 'image' => '/9j/4AAQSkZJRgABAQAAAQABAAD...',\n 'comment' => 'Known fraud attempt',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.lists.entries.upload_face(\n \"11111111-2222-3333-4444-555555555555\",\n image: \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n comment: \"Known fraud attempt\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Lists.Entries.UploadFaceAsync(\"11111111-2222-3333-4444-555555555555\", new ListsEntriesUploadFaceParams\n{\n Image = \"/9j/4AAQSkZJRgABAQAAAQABAAD...\",\n Comment = \"Known fraud attempt\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "人脸条目已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ComplianceListEntry" }, "examples": { "Uploaded face": { "value": { "uuid": "cccccccc-dddd-eeee-ffff-000000000000", "value": "44444444-5555-6666-7777-888888888888", "display_label": "Manually uploaded face", "comment": "Known fraud attempt", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": "44444444-5555-6666-7777-888888888888", "metadata": { "reference_image_url": "https://media.example.com/faces/reference.jpg?expires=1760263938&signature=3f9a1c" }, "created_at": "2026-10-12T10:12:18.904467Z" } }, "Sandbox application": { "value": { "uuid": "cccccccc-dddd-eeee-ffff-000000000000", "value": "44444444-5555-6666-7777-888888888888", "display_label": "Sandbox face entry", "comment": "Known fraud attempt", "added_by": "api", "reference_session_id": null, "reference_session_number": null, "reference_session_type": null, "reference_object_uuid": "44444444-5555-6666-7777-888888888888", "metadata": { "sandbox": true }, "created_at": "2026-10-12T10:12:18.904467Z" } } } } } }, "400": { "description": "该名单不接受人脸上传，或者图片缺失、无效、过大或未显示可用的人脸。未创建任何条目。", "content": { "application/json": { "examples": { "Not a face list": { "value": { "detail": "Face upload is only available for face-type lists." } }, "Custom face list": { "value": { "detail": "Face upload is only available for face blocklists and allowlists." } }, "Missing image": { "value": { "image": [ "This field is required." ] } }, "Invalid base64": { "value": { "image": [ "Invalid base64 encoding." ] } }, "Too large": { "value": { "image": [ "Image exceeds maximum size of 2 MB." ] } }, "Unreadable image": { "value": { "image": "Invalid image. Provide a valid base64-encoded JPG or PNG." } }, "No face": { "value": { "image": "No face detected in the image. Please upload a clear photo with a visible face." } }, "No usable face": { "value": { "image": "Could not extract face embedding. Try a different image." } } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "404": { "description": "API 密钥所属的应用中不存在具有此 UUID 的列表，或者已被删除。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "List not found." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" }, "503": { "description": "人脸分析暂时不可用。未创建任何条目；请稍后重试。", "content": { "application/json": { "examples": { "Unavailable": { "value": { "detail": "Service temporarily unavailable. Please try again later." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/blocklist/": { "get": { "summary": "列出黑名单项", "description": "返回当前已列入黑名单的应用验证会话的人脸、身份证件、电话号码和邮箱地址的分页信息流，按 `blocklisted_at` 由新到旧排序；使用 `item_type` 进行过滤。已删除会话的项目不包含在内。该信息流涵盖通过会话列入黑名单的记录（通过[将会话项目添加到黑名单](https://docs.didit.me/zh/management-api/blocklist/add)、从控制台添加，或通过基于会话创建的名单条目）；手动添加到名单的值、上传的人脸、来自证件采集流程中自拍照的人脸以及其他条目类型请使用[列出名单条目](https://docs.didit.me/zh/management-api/lists/list-entries)读取。`face_image` 和 `front_image` 是短期有效的已签名 URL，未拥有 `media: read` 权限的作用域 API 密钥将接收到 `null`。作用域 API 密钥需要 `workflows: read` 权限。", "operationId": "list_blocklist_items", "x-didit-sdk": { "resource": "blocklist", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Blocklist" ], "parameters": [ { "name": "item_type", "in": "query", "required": false, "description": "仅包含此类型的项。省略时，返回所有类型。", "schema": { "type": "string", "enum": [ "face", "document", "phone", "email" ] } }, { "name": "limit", "in": "query", "required": false, "description": "页面大小。默认为 50。大于 1000000 的值返回 `400`；0、负数或非数字值将回退为 50。", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 } }, { "name": "offset", "in": "query", "required": false, "description": "要返回的第一项的从零开始的索引。建议跟随 `next`。大于 1000000 的值将返回 `400`；负数或非数字值将回退为 0。", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/blocklist/?item_type=document' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.blocklist.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.blocklist.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Blocklist.ListAutoPaging(ctx, didit.BlocklistListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.blocklist().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "blocklist->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.blocklist.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Blocklist.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "一页黑名单条目，按最新优先排序。", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "符合过滤条件的黑名单项目总数。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/BlocklistedItem" } } } }, "examples": { "Mixed feed": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "type": "document", "session_id": "33333333-4444-5555-6666-777777777777", "session_number": 1042, "blocklisted_at": "2026-10-12T10:06:12.701553Z", "face_image": null, "document_type": "ID", "document_number": "X1234567", "front_image": "https://media.example.com/documents/front.jpg?expires=1760263938&signature=8b2e47", "phone_number": null, "country_code": null, "email": null }, { "type": "phone", "session_id": "77777777-8888-9999-0000-111111111111", "session_number": 1017, "blocklisted_at": "2026-10-08T15:31:09.400127Z", "face_image": null, "document_type": null, "document_number": null, "front_image": null, "phone_number": "+14155552671", "country_code": "US", "email": null } ] } } } } } }, "400": { "description": "查询参数无效。", "content": { "application/json": { "examples": { "Unknown item type": { "value": { "item_type": [ "\"wallet\" is not a valid choice." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: read`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no read access to workflows." } } } } } }, "429": { "description": "已超出每个 API 密钥每分钟 600 次请求的共享读取限制。在重试之前请遵循 `Retry-After`。", "content": { "application/json": { "examples": { "Rate limited": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/blocklist/add/": { "post": { "summary": "将会话条目添加到黑名单", "description": "将应用的某个人员验证会话的人脸、身份证件、电话号码或邮箱地址加入黑名单。对于所选的每种类型，Didit 会获取该会话的最新记录，将其标记为已加入黑名单，并向匹配的系统黑名单添加一条关联到该会话的条目（`added_by: \"api\"`），因此具有匹配人脸、证件号码、电话号码或邮箱地址的新会话将被拒绝。首先会检查每个选定的项目，因此如果缺少其中任何一项，则不会将任何内容加入黑名单；对已列出的项目重复调用会保留其单条条目并刷新 `blocklisted_at`。会话本身以及已完成的会话不会发生更改。限定作用域的 API 密钥需要 `workflows: write` 权限。", "operationId": "add_to_blocklist", "x-didit-sdk": { "resource": "blocklist", "method": "add", "auth": "api_key", "server": true }, "tags": [ "Blocklist" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "description": "至少一个 `blocklist_*` 标志必须为 `true`。", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "您应用的个人验证会话。已删除的会话会被拒绝。" }, "blocklist_face": { "type": "boolean", "default": false, "description": "将该会话的人脸加入黑名单。" }, "blocklist_document": { "type": "boolean", "default": false, "description": "将该会话的身份证件加入黑名单。证件需要具备签发州、证件类型、证件号码和姓名。" }, "blocklist_phone": { "type": "boolean", "default": false, "description": "将该会话的电话号码加入黑名单。" }, "blocklist_email": { "type": "boolean", "default": false, "description": "将该会话的邮箱地址加入黑名单。" } } }, "examples": { "Face and document": { "value": { "session_id": "33333333-4444-5555-6666-777777777777", "blocklist_face": true, "blocklist_document": true } }, "Phone only": { "value": { "session_id": "33333333-4444-5555-6666-777777777777", "blocklist_phone": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/blocklist/add/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"session_id\": \"33333333-4444-5555-6666-777777777777\",\n \"blocklist_face\": true,\n \"blocklist_document\": true\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.blocklist.add(\n session_id=\"33333333-4444-5555-6666-777777777777\",\n blocklist_face=True,\n blocklist_document=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.blocklist.add({\n session_id: \"33333333-4444-5555-6666-777777777777\",\n blocklist_face: true,\n blocklist_document: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Blocklist.Add(ctx, didit.BlocklistAddParams{\n\tSessionID: \"33333333-4444-5555-6666-777777777777\",\n\tBlocklistFace: didit.Bool(true),\n\tBlocklistDocument: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BlocklistAddParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.blocklist().add(BlocklistAddParams.builder()\n .sessionId(\"33333333-4444-5555-6666-777777777777\")\n .blocklistFace(true)\n .blocklistDocument(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "blocklist->add([\n 'session_id' => '33333333-4444-5555-6666-777777777777',\n 'blocklist_face' => true,\n 'blocklist_document' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.blocklist.add(\n session_id: \"33333333-4444-5555-6666-777777777777\",\n blocklist_face: true,\n blocklist_document: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Blocklist.AddAsync(new BlocklistAddParams\n{\n SessionId = \"33333333-4444-5555-6666-777777777777\",\n BlocklistFace = true,\n BlocklistDocument = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "所选项目已被列入黑名单。", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "始终为 `Successfully updated blocklist.`" } } }, "examples": { "Blocklisted": { "value": { "message": "Successfully updated blocklist." } } } } } }, "400": { "description": "请求体无效、会话不是该应用的验证会话，或者不包含所选类型的记录。没有任何内容被加入黑名单。", "content": { "application/json": { "examples": { "Unknown session": { "value": { "non_field_errors": [ "Session not found" ] } }, "No item selected": { "value": { "non_field_errors": [ "Must specify at least one item to blocklist" ] } }, "No face record": { "value": { "non_field_errors": [ "Session does not have a face record" ] } }, "Incomplete document": { "value": { "non_field_errors": [ "To blocklist a document, the document must have an issuing state, document type, document number and full name" ] } }, "Invalid session id": { "value": { "session_id": [ "Must be a valid UUID." ] } }, "Missing session id": { "value": { "session_id": [ "This field is required." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/blocklist/remove/": { "post": { "summary": "从黑名单中移除会话条目", "description": "解除对应用中某个人员验证会话的人脸、身份证件、电话号码或邮箱地址的阻止。针对每个选定的类型，Didit 会获取该会话的最新记录，清除其黑名单标记，并删除根据该记录创建的系统黑名单条目，使其不再导致新会话被拒绝。按值添加到列表中的条目不会受到影响：可以通过 [List list entries](https://docs.didit.me/zh/management-api/lists/list-entries) 查询它们，并通过 [Delete a list entry](https://docs.didit.me/zh/management-api/lists/delete-entry) 删除它们。取消阻止未列入黑名单的记录会返回成功且不更改任何内容，已经结束的会话不会被修改。限定作用域的 API 密钥需要 `workflows: write` 权限。", "operationId": "remove_from_blocklist", "x-didit-sdk": { "resource": "blocklist", "method": "remove", "auth": "api_key", "server": true }, "tags": [ "Blocklist" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id" ], "description": "至少一个 `unblock_*` 标志必须为 `true`。", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "您应用的个人验证会话。已删除的会话会被拒绝。" }, "unblock_face": { "type": "boolean", "default": false, "description": "解除对该会话人脸的阻止。" }, "unblock_document": { "type": "boolean", "default": false, "description": "解除对该会话身份证件的阻止。" }, "unblock_phone": { "type": "boolean", "default": false, "description": "解除对该会话电话号码的阻止。" }, "unblock_email": { "type": "boolean", "default": false, "description": "解除对该会话邮箱地址的阻止。" } } }, "examples": { "Face and document": { "value": { "session_id": "33333333-4444-5555-6666-777777777777", "unblock_face": true, "unblock_document": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/blocklist/remove/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"session_id\": \"33333333-4444-5555-6666-777777777777\",\n \"unblock_face\": true,\n \"unblock_document\": true\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.blocklist.remove(\n session_id=\"33333333-4444-5555-6666-777777777777\",\n unblock_face=True,\n unblock_document=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.blocklist.remove({\n session_id: \"33333333-4444-5555-6666-777777777777\",\n unblock_face: true,\n unblock_document: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Blocklist.Remove(ctx, didit.BlocklistRemoveParams{\n\tSessionID: \"33333333-4444-5555-6666-777777777777\",\n\tUnblockFace: didit.Bool(true),\n\tUnblockDocument: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.BlocklistRemoveParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.blocklist().remove(BlocklistRemoveParams.builder()\n .sessionId(\"33333333-4444-5555-6666-777777777777\")\n .unblockFace(true)\n .unblockDocument(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "blocklist->remove([\n 'session_id' => '33333333-4444-5555-6666-777777777777',\n 'unblock_face' => true,\n 'unblock_document' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.blocklist.remove(\n session_id: \"33333333-4444-5555-6666-777777777777\",\n unblock_face: true,\n unblock_document: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Blocklist.RemoveAsync(new BlocklistRemoveParams\n{\n SessionId = \"33333333-4444-5555-6666-777777777777\",\n UnblockFace = true,\n UnblockDocument = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "所选项的封禁已被解除。", "content": { "application/json": { "schema": { "type": "object", "required": [ "message" ], "properties": { "message": { "type": "string", "description": "始终为 `Successfully removed from blocklist.`" } } }, "examples": { "Unblocked": { "value": { "message": "Successfully removed from blocklist." } } } } } }, "400": { "description": "请求体无效、会话不是该应用的验证会话，或者不包含所选类型的记录。未更改任何内容。", "content": { "application/json": { "examples": { "Unknown session": { "value": { "non_field_errors": [ "Session not found" ] } }, "No item selected": { "value": { "non_field_errors": [ "Must specify at least one item to unblock" ] } }, "No email record": { "value": { "non_field_errors": [ "Session does not have an email record" ] } }, "Invalid session id": { "value": { "session_id": [ "Must be a valid UUID." ] } }, "Missing session id": { "value": { "session_id": [ "This field is required." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。其他身份验证失败将返回 `403`。", "content": { "application/json": { "examples": { "Expired API key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key` 请求头（错误、已撤销或已过期的密钥会返回 `401`），或者限定权限的 API 密钥缺少 `workflows: write`，抑或是从其允许名单之外的 IP 地址使用。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without workflows access": { "value": { "detail": "This API key has no write access to workflows." } } } } } }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/": { "get": { "summary": "获取 Webhook 配置", "description": "通过一次调用返回应用的 Webhook 设置：每个 [Webhook 目标](https://docs.didit.me/zh/management-api/webhook/list-destinations)及其签名密钥、目标可以订阅的事件类型、应用级别（旧版）Webhook URL、版本和密钥、数据及生物特征模板保留策略，以及数字身份钱包返回主机。Didit 会将 Webhook 投递到各个目标，每个目标都使用其专属的 `secret_shared_key` 进行签名；顶层的 `webhook_url`、`webhook_version` 和 `secret_shared_key` 仅在未启用任何目标时使用，且仅用于 `status.updated` 和 `data.updated`。响应中包含签名密钥，因此请勿将其记录在日志或客户端代码中。限定范围的 API 密钥需要 `webhooks: read` 权限。", "operationId": "get_webhook_config", "x-didit-sdk": { "resource": "webhooks", "method": "retrieve_config", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.retrieve_config()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.retrieveConfig();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.RetrieveConfig(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().retrieveConfig();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->retrieveConfig();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.retrieve_config\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.RetrieveConfigAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "Webhook 配置。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" }, "examples": { "One destination": { "value": { "webhook_url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy10aGUtYXBwLWxldmVsLXNlY3JldC0wMDA", "capture_method": "MOBILE", "data_retention_months": 24, "face_retention_policy": "delete_with_session", "face_retention_days": null, "biometric_consent_mode": "auto", "available_events": [ { "value": "status.updated", "label": "Session status updated" }, { "value": "data.updated", "label": "Session data updated" }, { "value": "user.status.updated", "label": "User status updated" }, { "value": "user.data.updated", "label": "User data updated" }, { "value": "business.status.updated", "label": "Business status updated" }, { "value": "business.data.updated", "label": "Business data updated" }, { "value": "activity.created", "label": "Activity created" }, { "value": "transaction.created", "label": "Transaction created" }, { "value": "transaction.status.updated", "label": "Transaction status updated" }, { "value": "travel_rule.status.updated", "label": "Travel Rule Status Updated" }, { "value": "workflow.compliance_changed", "label": "Workflow Compliance Changed" } ], "allowed_return_hosts": [ "shop.example.com" ], "endpoints": [ { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC0wMDAwMDA", "subscribed_events": [ "status.updated", "data.updated" ], "created_at": "2026-01-04T08:00:00.000000Z", "updated_at": "2026-04-22T14:09:11.523671Z" } ] } } } } } }, "401": { "description": "API 密钥已过期：它在创建时设置的到期日期已过。错误或已撤销的密钥也会收到 `401`；缺失密钥则收到 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。缺失、无效或已撤销的 `x-api-key` 会收到 `You do not have permission to perform this action.`。缺少此 endpoint 所需访问权限的限定作用域密钥会收到指明所缺权限的消息，而在其 IP 白名单之外使用的密钥会收到 `This API key can't be used from this IP address.`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "超出速率限制：当前一分钟窗口内该 API 密钥的 GET 请求超过 600 次。请等待 `Retry-After` 秒后再重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "一分钟时间窗口内允许的请求数（600）。", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间（秒）。", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "发生超支的预算名称。", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "patch": { "summary": "更新 Webhook 配置", "description": "部分更新应用级设置：旧版 Webhook URL、版本与密钥，数据及生物特征模板保留策略，以及 Digital ID 钱包返回主机。仅发送需更改的字段；响应为完整配置，数据结构与 `GET /v3/webhook/` 相同。此处不管理目标：请通过 `/v3/webhook/destinations/` endpoint 进行创建、更新和删除，且不要向此 endpoint 发送 `endpoints` 字段。`data_retention_months` 的更改同样适用于现有会话，且其删除的会话无法恢复；请先阅读[数据保留](https://docs.didit.me/zh/console/data-retention)。限定范围的 API 密钥需要具备 `webhooks: write` 权限。", "operationId": "update_webhook_config", "x-didit-sdk": { "resource": "webhooks", "method": "update_config", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "仅发送要更改的字段。目标不在此处管理。", "properties": { "webhook_url": { "type": "string", "format": "uri", "nullable": true, "maxLength": 2000, "description": "旧版应用级 Webhook URL。Didit 仅在应用未启用任何目标时使用它，且仅用于 `status.updated` 和 `data.updated`。它不会创建目标，并且下次对目标的创建、更新或删除操作都会替换它。若要接收 Webhook，请改用 `POST /v3/webhook/destinations/` 创建目标。" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "传统 `webhook_url` 的 payload 版本。" }, "rotate_secret_key": { "type": "boolean", "default": false, "description": "`true` 会立即将应用层级的 `secret_shared_key` 替换为新的随机值；新值包含在响应中。目标密钥不会更改。每次传入 `true` 的调用都会生成一个新密钥，因此该操作不具备幂等性。" }, "capture_method": { "type": "string", "enum": [ "MOBILE", "MOBILE_AND_DESKTOP" ], "description": "旧版应用设置。验证流程不会读取它。" }, "data_retention_months": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 120, "description": "自动删除期限（以月为单位，一个月计为 30 天），或填 `null` 表示不自动删除。更改同样适用于现有会话：早于新设定月限的所有用户验证会话都将被自动删除，且该删除操作不可逆。" }, "face_retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "当会话被删除时，对该会话的人脸特征向量的处理方式。`retain_until_user_deleted` 要求在同一次请求中提供 `face_retention_days` 或已预先设置该参数。变更仅适用于此后的会话删除；不会创建或清除任何现有的生物特征模板。" }, "face_retention_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 3650, "description": "在 `retain_until_user_deleted` 策略下生物特征模板的保留期（以天为单位）。" }, "biometric_consent_mode": { "type": "string", "enum": [ "auto", "always", "never" ], "description": "托管流程和原生 SDK 何时在人脸采集前向当事人请求明确的生物识别同意。`auto`（默认）仅在适用触发条件时请求：当事人声明的州、当事人的 IP 或身份证件签发地位于伊利诺伊州、德克萨斯州或科罗拉多州，或者当事人看似位于美国境内且所在州未知。`always` 会向工作流中需要采集人脸的每个人请求。`never` 则从不显示该步骤，由您在拍摄自拍照前自行收集同意。每次更改都会记录在审计日志中。请参阅[生物识别同意](https://docs.didit.me/zh/getting-started/biometric-consent)。" }, "allowed_return_hosts": { "type": "array", "maxItems": 20, "description": "替换数字身份钱包返回主机的整个列表。仅支持纯主机名，例如 `shop.example.com`：不支持协议、端口、路径或通配符。值将转换为小写并删除重复项。发送 `[]` 以清空列表。", "items": { "type": "string", "maxLength": 253 } }, "allowed_domains": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 }, "description": "替换允许的源（origins）的整个列表。托管验证流程可以嵌入其中并通过会话回调将用户发送回这些源（例如 `https://app.example.com`；`http` 仅适用于 `localhost`）。服务器到服务器的调用不受影响。空列表表示没有限制。Didit 以小写形式存储每个源，不包含默认端口。无效条目会针对 `allowed_domains` 返回 `400`。发送 `[]` 以移除限制。", "example": [ "https://app.example.com" ] } } }, "examples": { "Enable biometric template retention": { "value": { "face_retention_policy": "retain_until_user_deleted", "face_retention_days": 365, "biometric_consent_mode": "auto" } }, "Rotate the legacy secret": { "value": { "rotate_secret_key": true } }, "Set data retention": { "value": { "data_retention_months": 24 } }, "Register return hosts": { "value": { "allowed_return_hosts": [ "shop.example.com", "app.example.com" ] } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/webhook/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"face_retention_policy\": \"retain_until_user_deleted\", \"face_retention_days\": 365}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.update_config(\n face_retention_policy=\"retain_until_user_deleted\",\n face_retention_days=365,\n biometric_consent_mode=\"auto\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.updateConfig({\n face_retention_policy: \"retain_until_user_deleted\",\n face_retention_days: 365,\n biometric_consent_mode: \"auto\",\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.WebhooksUpdateConfigParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().updateConfig(WebhooksUpdateConfigParams.builder()\n .faceRetentionPolicy(WebhooksUpdateConfigParams.FaceRetentionPolicy.of(\"retain_until_user_deleted\"))\n .faceRetentionDays(365L)\n .biometricConsentMode(WebhooksUpdateConfigParams.BiometricConsentMode.of(\"auto\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->updateConfig([\n 'face_retention_policy' => 'retain_until_user_deleted',\n 'face_retention_days' => 365,\n 'biometric_consent_mode' => 'auto',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.update_config(\n face_retention_policy: \"retain_until_user_deleted\",\n face_retention_days: 365,\n biometric_consent_mode: \"auto\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.UpdateConfigAsync(new WebhooksUpdateConfigParams\n{\n FaceRetentionPolicy = new WebhooksUpdateConfigParamsFaceRetentionPolicy(\"retain_until_user_deleted\"),\n FaceRetentionDays = 365,\n BiometricConsentMode = new WebhooksUpdateConfigParamsBiometricConsentMode(\"auto\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "更新后的完整配置，结构与 `GET /v3/webhook/` 相同。轮换密钥时，请在丢弃响应前存储新的 `secret_shared_key`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookConfig" }, "examples": { "Retention enabled": { "value": { "webhook_url": "https://yourapp.com/webhooks/didit", "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy10aGUtYXBwLWxldmVsLXNlY3JldC0wMDA", "capture_method": "MOBILE", "data_retention_months": 24, "face_retention_policy": "retain_until_user_deleted", "face_retention_days": 365, "biometric_consent_mode": "auto", "available_events": [ { "value": "status.updated", "label": "Session status updated" }, { "value": "data.updated", "label": "Session data updated" }, { "value": "user.status.updated", "label": "User status updated" }, { "value": "user.data.updated", "label": "User data updated" }, { "value": "business.status.updated", "label": "Business status updated" }, { "value": "business.data.updated", "label": "Business data updated" }, { "value": "activity.created", "label": "Activity created" }, { "value": "transaction.created", "label": "Transaction created" }, { "value": "transaction.status.updated", "label": "Transaction status updated" }, { "value": "travel_rule.status.updated", "label": "Travel Rule Status Updated" }, { "value": "workflow.compliance_changed", "label": "Workflow Compliance Changed" } ], "allowed_return_hosts": [ "shop.example.com" ], "endpoints": [ { "uuid": "11111111-2222-3333-4444-555555555555", "label": "Production session webhooks", "url": "https://yourapp.com/webhooks/didit", "enabled": true, "webhook_version": "v3", "secret_shared_key": "dGhpcy1pcy1hbi1leGFtcGxlLXNlY3JldC0wMDAwMDA", "subscribed_events": [ "status.updated", "data.updated" ], "created_at": "2026-01-04T08:00:00.000000Z", "updated_at": "2026-04-22T14:09:11.523671Z" } ] } } } } } }, "400": { "description": "验证失败：每个无效字段都会映射到一个消息列表，且不会更改任何内容。非有效 JSON 的请求主体将返回 `{\"detail\": \"JSON parse error - ...\"}`。", "content": { "application/json": { "schema": { "type": "object", "description": "每个无效字段映射到的消息列表。", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Retention days missing": { "value": { "face_retention_days": [ "A finite retention duration is required when face retention is enabled." ], "biometric_consent_mode": "auto" } }, "Retention window out of range": { "value": { "data_retention_months": [ "Ensure this value is less than or equal to 120." ] } }, "Invalid return host": { "value": { "allowed_return_hosts": [ "'https://shop.example.com' is not a hostname. Register the bare host (e.g. shop.example.com): no scheme, port, path or wildcard." ] } }, "Invalid choice": { "value": { "face_retention_policy": [ "\"forever\" is not a valid choice." ] } } } } } }, "401": { "description": "API 密钥已过期：它在创建时设置的到期日期已过。错误或已撤销的密钥也会收到 `401`；缺失密钥则收到 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。缺失、无效或已撤销的 `x-api-key` 会收到 `You do not have permission to perform this action.`。缺少此 endpoint 所需访问权限的限定作用域密钥会收到指明所缺权限的消息，而在其 IP 白名单之外使用的密钥会收到 `This API key can't be used from this IP address.`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks write": { "value": { "detail": "This API key has no write access to webhooks." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "超出速率限制：当前一分钟窗口内该 API 密钥的写入请求（POST、PATCH、PUT、DELETE）超过 300 次。请等待 `Retry-After` 秒后再重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "一分钟时间窗口内允许的请求数（300）。", "schema": { "type": "integer", "example": 300 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间（秒）。", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "发生超支的预算名称。", "schema": { "type": "string", "example": "generic-write" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/analytics/": { "get": { "summary": "获取 Webhook 目标分析", "description": "单个 Webhook 目标在整个时间范围（`summary`）内以及按 UTC 日（`points`）细分的投递总量、失败率和响应时间。每次尝试均计为一次投递：事件的首次发送、每次自动[重试](https://docs.didit.me/zh/integration/webhooks#重试策略)以及每次重新发送。当记录的 HTTP 状态为 400 或以上时，该投递被视为失败，因此超时（记录为 `504`）和连接失败（`503`）均计为失败；仍在排队中的投递仅计入 `total_deliveries`。投递记录保留约 30 天。限定作用域的 API 密钥需要 `webhooks: read` 权限。", "operationId": "get_webhook_destination_analytics", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "retrieve_analytics", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "目标的 UUID（`GET /v3/webhook/destinations/` 返回的 `uuid`）。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "date_from", "in": "query", "required": false, "description": "包含的首个 UTC 日期，格式为 `YYYY-MM-DD`（含）。省略则从最早可用的投递开始。支持将 `dateFrom` 作为别名。", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "date_to", "in": "query", "required": false, "description": "要包含的最后一个 UTC 日期，格式为 `YYYY-MM-DD`（含）。不得早于 `date_from`。可接受 `dateTo` 作为别名。", "schema": { "type": "string", "format": "date" }, "example": "2026-10-16" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/analytics/?date_from=2026-10-01&date_to=2026-10-16' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.retrieve_analytics(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.retrieveAnalytics(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.RetrieveAnalytics(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsRetrieveAnalyticsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().retrieveAnalytics(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->retrieveAnalytics('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.retrieve_analytics(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.RetrieveAnalyticsAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "目标的投递统计信息。", "content": { "application/json": { "schema": { "type": "object", "required": [ "summary", "points" ], "properties": { "summary": { "type": "object", "description": "所请求范围内的总计。", "required": [ "total_deliveries", "failed_deliveries", "min_response_time_ms", "avg_response_time_ms", "max_response_time_ms", "error_rate_percentage" ], "properties": { "total_deliveries": { "type": "integer", "minimum": 0, "description": "投递尝试，包括排队中的尝试。" }, "failed_deliveries": { "type": "integer", "minimum": 0, "description": "记录的 HTTP 状态码为 400 或更高的尝试次数。" }, "min_response_time_ms": { "type": "integer", "nullable": true, "description": "最快的尝试耗时（毫秒），若没有尝试记录时间则为 `null`。" }, "avg_response_time_ms": { "type": "integer", "nullable": true, "description": "平均尝试时间（毫秒），四舍五入取整；若无尝试记录时间则为 `null`。" }, "max_response_time_ms": { "type": "integer", "nullable": true, "description": "最慢的一次尝试（以毫秒计），当没有尝试记录时间时为 `null`。" }, "error_rate_percentage": { "type": "integer", "minimum": 0, "maximum": 100, "description": "`failed_deliveries` / `total_deliveries` x 100，四舍五入为整数。没有投递时为 `0`。" } } }, "points": { "type": "array", "description": "发生过投递的每个 UTC 天对应一个条目，按时间从早到晚排列。没有投递的日期会被省略，因此在绘制图表时请用零补齐空缺。", "items": { "type": "object", "required": [ "date", "total_deliveries", "failed_deliveries", "min_response_time_ms", "avg_response_time_ms", "max_response_time_ms" ], "properties": { "date": { "type": "string", "format": "date", "description": "UTC 日期，`YYYY-MM-DD`。" }, "total_deliveries": { "type": "integer", "minimum": 0, "description": "投递尝试，包括排队中的尝试。" }, "failed_deliveries": { "type": "integer", "minimum": 0, "description": "记录的 HTTP 状态码为 400 或更高的尝试次数。" }, "min_response_time_ms": { "type": "integer", "nullable": true, "description": "最快的尝试耗时（毫秒），若没有尝试记录时间则为 `null`。" }, "avg_response_time_ms": { "type": "integer", "nullable": true, "description": "平均尝试时间（毫秒），四舍五入取整；若无尝试记录时间则为 `null`。" }, "max_response_time_ms": { "type": "integer", "nullable": true, "description": "最慢的一次尝试（以毫秒计），当没有尝试记录时间时为 `null`。" } } } } } }, "examples": { "Three days of deliveries": { "value": { "summary": { "total_deliveries": 1250, "failed_deliveries": 12, "min_response_time_ms": 38, "avg_response_time_ms": 164, "max_response_time_ms": 5004, "error_rate_percentage": 1 }, "points": [ { "date": "2026-10-14", "total_deliveries": 410, "failed_deliveries": 0, "min_response_time_ms": 38, "avg_response_time_ms": 152, "max_response_time_ms": 911 }, { "date": "2026-10-15", "total_deliveries": 395, "failed_deliveries": 12, "min_response_time_ms": 41, "avg_response_time_ms": 190, "max_response_time_ms": 5004 }, { "date": "2026-10-16", "total_deliveries": 445, "failed_deliveries": 0, "min_response_time_ms": 40, "avg_response_time_ms": 151, "max_response_time_ms": 1220 } ] } }, "No deliveries in range": { "value": { "summary": { "total_deliveries": 0, "failed_deliveries": 0, "min_response_time_ms": null, "avg_response_time_ms": null, "max_response_time_ms": null, "error_rate_percentage": 0 }, "points": [] } } } } } }, "400": { "description": "`date_from` 或 `date_to` 不是 `YYYY-MM-DD` 格式的日期，或者 `date_to` 早于 `date_from`。", "content": { "application/json": { "schema": { "type": "object", "description": "每个无效字段映射到的消息列表。", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Malformed date": { "value": { "date_from": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Reversed range": { "value": { "date_to": [ "date_to must be greater than or equal to date_from." ] } } } } } }, "401": { "description": "API 密钥已过期：它在创建时设置的到期日期已过。错误或已撤销的密钥也会收到 `401`；缺失密钥则收到 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。缺失、无效或已撤销的 `x-api-key` 会收到 `You do not have permission to perform this action.`。缺少此 endpoint 所需访问权限的限定作用域密钥会收到指明所缺权限的消息，而在其 IP 白名单之外使用的密钥会收到 `This API key can't be used from this IP address.`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "应用不存在具有此 UUID 的目标，或者已被删除。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "超出速率限制：当前一分钟窗口内该 API 密钥的 GET 请求超过 600 次。请等待 `Retry-After` 秒后再重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "一分钟时间窗口内允许的请求数（600）。", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间（秒）。", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "发生超支的预算名称。", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/deliveries/": { "get": { "summary": "列出 Webhook 目标投递记录", "description": "分页查看向单个 Webhook 目标发送的每次投递尝试，最新优先。每个事件的首次发送、每次自动[重试](https://docs.didit.me/zh/integration/webhooks#重试策略)和每次重新发送均为独立条目。条目包含 HTTP 状态和响应时间，但不包含 payload：获取单个投递记录以读取其请求头和正文。`count` 在 100 以内是精确的，超过该值则显示为 100，因此请持续追踪 `next` 直至其为 `null`。投递记录保留约 30 天。受权限范围限制的 API 密钥需要 `webhooks: read` 和 `decisions: read` 权限；限定于特定工作流或仅限已通过会话的密钥无法使用此 endpoint。", "operationId": "list_webhook_destination_deliveries", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "list_deliveries", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "目标的 UUID（`GET /v3/webhook/destinations/` 返回的 `uuid`）。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "limit", "in": "query", "required": false, "description": "每页最大投递数。默认值为 50。非正整数值将回退至 50；超过 1000000 的值将返回 `400`。", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "要跳过的投递数量。默认为 0。建议使用响应中的 `next` 和 `previous` URL。", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 0 }, { "name": "date_from", "in": "query", "required": false, "description": "包含的首个 UTC 日期，格式为 `YYYY-MM-DD`（含）。省略则从最早可用的投递开始。支持将 `dateFrom` 作为别名。", "schema": { "type": "string", "format": "date" }, "example": "2026-10-01" }, { "name": "date_to", "in": "query", "required": false, "description": "要包含的最后一个 UTC 日期，格式为 `YYYY-MM-DD`（含）。不得早于 `date_from`。可接受 `dateTo` 作为别名。", "schema": { "type": "string", "format": "date" }, "example": "2026-10-16" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/deliveries/?limit=50&date_from=2026-10-01' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.webhooks.destinations.list_deliveries(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.webhooks.destinations.listDeliveries(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Webhooks.Destinations.ListDeliveriesAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.WebhooksDestinationsListDeliveriesParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.webhooks().destinations().listDeliveries(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->listDeliveries('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.webhooks.destinations.list_deliveries(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Webhooks.Destinations.ListDeliveriesAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "一页投递记录，最新的排在最前。", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "minimum": 0, "description": "匹配的投递，100 条以内为精确值，超过 100 条时上限显示为 100。使用 `next` 了解是否存在更多页面。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDestinationDelivery" } } } }, "examples": { "Failed delivery, its retry and a queued event": { "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "66666666-7777-8888-9999-000000000003", "session_id": null, "request_url": "https://yourapp.com/webhooks/didit", "response_status": null, "response_time_ms": null, "status": "APPROVED", "webhook_type": "transaction.created", "created_at": "2026-10-15T09:23:02.871190Z" }, { "uuid": "66666666-7777-8888-9999-000000000002", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "response_time_ms": 143, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-15T09:22:19.104233Z" }, { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "response_time_ms": 412, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-15T09:21:18.412345Z" } ] } } } } } }, "400": { "description": "`date_from` 或 `date_to` 不是 `YYYY-MM-DD` 格式的日期、`date_to` 早于 `date_from`，或者 `limit` 或 `offset` 大于 1000000（该错误是一个包含多条消息的 JSON 数组）。", "content": { "application/json": { "examples": { "Malformed date": { "value": { "date_from": [ "Date has wrong format. Use one of these formats instead: YYYY-MM-DD." ] } }, "Reversed range": { "value": { "date_to": [ "date_to must be greater than or equal to date_from." ] } }, "Limit too large": { "value": [ "limit must not exceed 1000000." ] } } } } }, "401": { "description": "API 密钥已过期：它在创建时设置的到期日期已过。错误或已撤销的密钥也会收到 `401`；缺失密钥则收到 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。缺失、无效或已撤销的 `x-api-key` 会收到 `You do not have permission to perform this action.`。缺少此 endpoint 所需访问权限的限定作用域密钥会收到指明所缺权限的消息，而在其 IP 白名单之外使用的密钥会收到 `This API key can't be used from this IP address.`。仅限于某些工作流或已通过的会话的密钥会收到 `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "应用不存在具有此 UUID 的目标，或者已被删除。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } } } } } }, "429": { "description": "超出速率限制：当前一分钟窗口内该 API 密钥的 GET 请求超过 600 次。请等待 `Retry-After` 秒后再重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "一分钟时间窗口内允许的请求数（600）。", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间（秒）。", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "发生超支的预算名称。", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/deliveries/{delivery_uuid}/": { "get": { "summary": "获取 Webhook 目标投递记录", "description": "获取向 Webhook 目标发起的一次投递尝试，包括 Didit 发送的准确请求头和 JSON 请求体、您的 endpoint 返回的 HTTP 状态以及响应时间。`request_header` 和 `request_body` 为 JSON 文本：解析它们以读取签名请求头和 payload，例如对照目标的 `secret_shared_key` 检查您的[签名验证](https://docs.didit.me/zh/integration/webhooks#签名验证)。投递记录中绝不会包含签名密钥，且 Didit 不会记录您 endpoint 的响应体。作用域受限的 API 密钥需要 `webhooks: read` 和 `decisions: read` 权限；仅限于某些工作流或仅限于已通过会话的密钥无法使用此 endpoint。", "operationId": "get_webhook_destination_delivery", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "retrieve_delivery", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "投递发送至的 Webhook 目标的 UUID。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "delivery_uuid", "in": "path", "required": true, "description": "投递的 UUID：由 `GET /v3/webhook/destinations/{destination_uuid}/deliveries/` 返回的条目的 `uuid`。", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/deliveries/66666666-7777-8888-9999-000000000001/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.retrieve_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.retrieveDelivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.RetrieveDelivery(ctx, \"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().retrieveDelivery(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->retrieveDelivery('11111111-2222-3333-4444-555555555555', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.retrieve_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.RetrieveDeliveryAsync(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "投递，包含其请求头和请求体。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationDeliveryDetail" }, "examples": { "Connection failure": { "value": { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "response_time_ms": 412, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-15T09:21:18.412345Z", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"a5e02a03404e1337a0198e6be15d34abbd053c658a0e51e5d0e78554213ef29b\", \"X-Signature-V2\": \"927e7cb770c94ce745939bff73f04aa200015f3bc64795ba46c2aaf78a6cedc5\", \"X-Signature-Simple\": \"e37b0d4c716c72bb5ae7127b9cc455d28ab4686e9e22312b4ec2327409a73302\", \"X-Timestamp\": \"1792056078\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056078,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}" } } } } } }, "401": { "description": "API 密钥已过期：它在创建时设置的到期日期已过。错误或已撤销的密钥也会收到 `401`；缺失密钥则收到 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。缺失、无效或已撤销的 `x-api-key` 会收到 `You do not have permission to perform this action.`。缺少此 endpoint 所需访问权限的限定作用域密钥会收到指明所缺权限的消息，而在其 IP 白名单之外使用的密钥会收到 `This API key can't be used from this IP address.`。仅限于某些工作流或已通过的会话的密钥会收到 `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks read": { "value": { "detail": "This API key has no read access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "该目标在应用中不存在或已被删除，或者投递不存在、属于其他目标或不再可用。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } }, "Delivery not found": { "value": { "detail": "Webhook delivery not found." } } } } } }, "429": { "description": "超出速率限制：当前一分钟窗口内该 API 密钥的 GET 请求超过 600 次。请等待 `Retry-After` 秒后再重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "一分钟时间窗口内允许的请求数（600）。", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间（秒）。", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "发生超支的预算名称。", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/webhook/destinations/{destination_uuid}/deliveries/{delivery_uuid}/resend/": { "post": { "summary": "重发 Webhook 目标投递", "description": "重新发送之前的投递，例如在您的 endpoint 宕机之后。Didit 会获取存储的 payload，设置全新的 `timestamp`，使用目标当前的 `secret_shared_key` 重新对其签名（`X-Signature`、`X-Signature-V2`、`X-Signature-Simple` 和 `X-Timestamp`），并将其 POST 到该投递的 `request_url`，即使该目标的 URL 之后发生过更改或该目标已被停用。`event_id` 和 payload 的其余部分保持不变，因此请根据 `event_id` 去重。该调用最多等待您的 endpoint 5 秒，无论您的 endpoint 回复什么都会返回带有 `200` 的新投递：请读取 `response_status`。重新发送不会自动重试，每次调用都会再次发送并创建一次新投递，并且该请求没有请求体。带作用域限制的 API 密钥需要具备 `webhooks: write` 和 `decisions: read` 权限；仅限于特定工作流或仅限于已通过的会话的密钥无法使用此 endpoint。", "operationId": "resend_webhook_destination_delivery", "x-didit-sdk": { "resource": "webhooks.destinations", "method": "resend_delivery", "auth": "api_key", "server": true }, "tags": [ "Webhook" ], "parameters": [ { "name": "destination_uuid", "in": "path", "required": true, "description": "投递发送至的 Webhook 目标的 UUID。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" }, { "name": "delivery_uuid", "in": "path", "required": true, "description": "要重新发送的投递的 UUID：由 `GET /v3/webhook/destinations/{destination_uuid}/deliveries/` 返回的条目的 `uuid`。", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/webhook/destinations/11111111-2222-3333-4444-555555555555/deliveries/66666666-7777-8888-9999-000000000001/resend/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.webhooks.destinations.resend_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.webhooks.destinations.resendDelivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Webhooks.Destinations.ResendDelivery(ctx, \"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.webhooks().destinations().resendDelivery(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "webhooks->destinations->resendDelivery('11111111-2222-3333-4444-555555555555', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.webhooks.destinations.resend_delivery(\n \"11111111-2222-3333-4444-555555555555\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Webhooks.Destinations.ResendDeliveryAsync(\"11111111-2222-3333-4444-555555555555\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已尝试的新投递。`response_status` 为您的 endpoint 此次返回的状态（`504` 超时、`503` 连接失败）。原始投递保持不变。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDestinationDeliveryDetail" }, "examples": { "Accepted on resend": { "value": { "uuid": "66666666-7777-8888-9999-000000000004", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "response_time_ms": 151, "status": "In Progress", "webhook_type": "status.updated", "created_at": "2026-10-16T14:05:42.330981Z", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"b8eb1e376517ee0cad8ba98ff7f8fd35fc72eca231000963a96a335f82328835\", \"X-Signature-V2\": \"9efd2ce9ed1303e1d05273ef9608a59363ed9789a05253db4748b3e8e50cb109\", \"X-Signature-Simple\": \"bf3a9dc04b2c20ab539203b0cd5cca2a10f630bf62d8feb6d68d82af80f64774\", \"X-Timestamp\": \"1792159542\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792159542,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}" } } } } } }, "400": { "description": "存储的投递无法再次签名。未发送任何内容。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" }, "code": { "type": "string", "description": "稳定的机器可读错误代码。请基于此代码进行分支处理，而非 `detail`。" } } }, "examples": { "Unsignable delivery": { "value": { "detail": "Invalid webhook data format", "code": "invalid_webhook_payload" } } } } } }, "401": { "description": "API 密钥已过期：它在创建时设置的到期日期已过。错误或已撤销的密钥也会收到 `401`；缺失密钥则收到 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。缺失、无效或已撤销的 `x-api-key` 会收到 `You do not have permission to perform this action.`。缺少此 endpoint 所需访问权限的限定作用域密钥会收到指明所缺权限的消息，而在其 IP 白名单之外使用的密钥会收到 `This API key can't be used from this IP address.`。仅限于某些工作流或已通过的会话的密钥会收到 `This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks write": { "value": { "detail": "This API key has no write access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "该目标在应用中不存在或已被删除，或者投递不存在、属于其他目标或不再可用。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Destination not found": { "value": { "detail": "Webhook destination not found." } }, "Delivery not found": { "value": { "detail": "Webhook delivery not found." } } } } } }, "429": { "description": "超出速率限制：当前一分钟窗口内该 API 密钥的写入请求（POST、PATCH、PUT、DELETE）超过 300 次。请等待 `Retry-After` 秒后再重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "一分钟时间窗口内允许的请求数（300）。", "schema": { "type": "integer", "example": 300 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间（秒）。", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "发生超支的预算名称。", "schema": { "type": "string", "example": "generic-write" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/": { "get": { "summary": "列出监控事件", "description": "列出为您的应用存储的监控事件，按 `occurred_at` 最新优先排序，支持使用 AND 组合的可选过滤器。多值过滤器（`event_category`、`action_type`、`status`、`retention_class`）通过重复参数来匹配其中任一值；其他过滤器则为精确匹配，未知值将直接返回空事件列表。每个结果均为摘要：调用 `GET /v3/events/{event_uuid}/` 可获取 payload、设备上下文、IP 增强信息以及规则证据；查询单个主体的历史记录时，建议优先使用 `GET /v3/events/subjects/{vendor_data}/`。无论事件摄取功能是否开启，读取均可正常工作。限定作用域的 API 密钥需要具备 `transactions: read` 权限。请参阅[事件摄取](https://docs.didit.me/zh/transaction-monitoring/events)。", "operationId": "list_monitoring_events", "x-didit-sdk": { "resource": "monitoring_events", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "每页最大事件数。默认值为 50。超过 1000000 的值将返回 `400`；非数值、零或负值将回退至 50。", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "要跳过的事件数量。默认为 0。建议使用响应中的 `next` URL。", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 0 }, { "name": "event_category", "in": "query", "required": false, "description": "仅包含这些类别中的事件。对多个值重复该参数（`?event_category=payment&event_category=dispute`）；匹配其中任一类别的事件都会被返回。", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] } }, "example": [ "payment", "dispute" ] }, { "name": "action_type", "in": "query", "required": false, "description": "仅包含具有这些操作类型的事件（精确匹配，区分大小写）。对多个值重复使用。", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "deposit_completed", "chargeback_opened" ] }, { "name": "status", "in": "query", "required": false, "description": "仅包含具有这些状态的事件。对多个值重复使用。", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ] } }, "example": [ "IN_REVIEW", "DECLINED" ] }, { "name": "retention_class", "in": "query", "required": false, "description": "仅包含这些保留类别中的事件。对多个值重复使用。", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ] } }, "example": [ "risk_relevant" ] }, { "name": "subject_vendor_data", "in": "query", "required": false, "description": "对主体的 `vendor_data` 进行精确匹配。相同的 ID 可以指代个人也可以指代公司；添加 `subject_entity_type` 以指定其一，或使用 `GET /v3/events/subjects/{vendor_data}/`。", "schema": { "type": "string" }, "example": "user-42" }, { "name": "subject_entity_type", "in": "query", "required": false, "description": "`company` 仅返回企业主体的事件；任何其他非空值（例如 `individual`）仅返回个人的事件。省略此项则返回两者。", "schema": { "type": "string", "enum": [ "individual", "company" ] }, "example": "individual" }, { "name": "business_vendor_data", "in": "query", "required": false, "description": "对随事件发送的 `business.vendor_data` 的精确匹配。", "schema": { "type": "string" }, "example": "merchant-7" }, { "name": "session_id", "in": "query", "required": false, "description": "对 `session.session_id` 的精确匹配。", "schema": { "type": "string" }, "example": "web-session-abc" }, { "name": "device_fingerprint", "in": "query", "required": false, "description": "对 `device_context.fingerprint` 的精确匹配。", "schema": { "type": "string" }, "example": "fp-a8c1" }, { "name": "ip_address", "in": "query", "required": false, "description": "对事件的 IP 地址进行精确匹配。", "schema": { "type": "string" }, "example": "203.0.113.42" }, { "name": "game_id", "in": "query", "required": false, "description": "对已提升的 `game_id` 的精确匹配。", "schema": { "type": "string" }, "example": "poker-holdem-01" }, { "name": "round_id", "in": "query", "required": false, "description": "对已提升的 `round_id` 的精确匹配。", "schema": { "type": "string" }, "example": "round-88231" }, { "name": "affiliate_code", "in": "query", "required": false, "description": "对已提升的 `affiliate_code` 的精确匹配。", "schema": { "type": "string" }, "example": "aff-summer" }, { "name": "payment_reference_id", "in": "query", "required": false, "description": "对支付参考信息的精确匹配（来自 `transaction_context.payment_reference_id` 或 `payload.payment_reference_id`）。", "schema": { "type": "string" }, "example": "dep_735" }, { "name": "counterparty_vendor_data", "in": "query", "required": false, "description": "对已提升的 `counterparty_vendor_data` 的精确匹配。", "schema": { "type": "string" }, "example": "user-77" }, { "name": "matched_only", "in": "query", "required": false, "description": "`true`（亦可为 `1` 或 `yes`，不区分大小写）仅返回匹配至少一条规则的事件（`rules_matched_count` 大于 0）。任何其他值将被忽略。", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "occurred_from", "in": "query", "required": false, "description": "仅包含 `occurred_at` 在此时间点或之后（包含）的事件。发送 ISO 8601 格式的值：`2026-10-01T00:00:00Z`、带有百分号编码 `+` 的显式偏移量（`2026-10-01T02:00:00%2B02:00`；未编码的 `+` 会被解码为空格导致该值无法解析），或仅日期（`2026-10-01`），表示当天的 00:00:00 UTC。无偏移量的值按 UTC 读取。不接受任何其他格式的值。", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "occurred_to", "in": "query", "required": false, "description": "仅包含 `occurred_at` 在此时间点或之前（包含）的事件。仅日期表示当天的开始，因此 `occurred_to=2026-10-15` 会排除 10 月 15 日的其余时间；发送 `2026-10-15T23:59:59Z` 以包含全天。发送 ISO 8601 格式的值：`2026-10-01T00:00:00Z`、带有百分号编码 `+` 的显式偏移量（`2026-10-01T02:00:00%2B02:00`；未编码的 `+` 会被解码为空格导致该值无法解析），或仅日期（`2026-10-01`），表示当天的 00:00:00 UTC。无偏移量的值按 UTC 读取。不接受任何其他格式的值。", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-17T23:59:59Z" }, { "name": "search", "in": "query", "required": false, "description": "对 `event_id`、`action_type`、`subject_vendor_data` 或 `counterparty_vendor_data` 进行不区分大小写的子字符串匹配。", "schema": { "type": "string" }, "example": "chargeback" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true&occurred_from=2026-10-01T00:00:00Z&limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.monitoring_events.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.monitoringEvents.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.MonitoringEvents.ListAutoPaging(ctx, didit.MonitoringEventsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.monitoringEvents().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.monitoring_events.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.MonitoringEvents.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "一页事件摘要。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventPage" }, "examples": { "Payment and dispute events": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "event_uuid": "11111111-2222-3333-4444-555555555555", "event_id": "chargeback-2026-10-16-000318", "event_category": "dispute", "action_type": "chargeback_opened", "occurred_at": "2026-10-16T14:02:11Z", "received_at": "2026-10-16T14:02:12.418230Z", "status": "IN_REVIEW", "score": 60, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": null, "device_fingerprint": null, "ip_address": null, "ip_country": null, "amount": "250.000000000000000000", "currency": "EUR", "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": "dep_735", "retention_class": "monetary_or_compliance", "rules_matched_count": 1, "correlation_pending": false, "is_droppable": false }, { "event_uuid": "22222222-3333-4444-5555-666666666666", "event_id": "login-2026-10-15-000912", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-15T08:30:00.120000Z", "received_at": "2026-10-15T08:30:00.734512Z", "status": "ACCEPTED", "score": 0, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": "web-session-abc", "device_fingerprint": "fp-a8c1", "ip_address": "203.0.113.42", "ip_country": "ES", "amount": null, "currency": null, "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": null, "retention_class": "standard", "rules_matched_count": 0, "correlation_pending": false, "is_droppable": true } ] } } } } } }, "400": { "description": "`limit` 或 `offset` 大于 1000000。响应体是包含一条消息的 JSON 数组。非数字或非正数的 `limit` 会回退到默认值 50，而不是失败。", "content": { "application/json": { "examples": { "limit too large": { "summary": "limit 超过 1000000", "value": [ "limit must not exceed 1000000." ] }, "offset too large": { "summary": "offset 超过 1000000", "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: read` 权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP 白名单之外的请求。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥的 `GET` 请求共享每分钟 600 次的配额。请等待 `Retry-After` 秒，然后重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建监控事件", "description": "从您的后端发送一个非货币事件（登录、会话、游戏活动、奖金、联盟、支付、争议、安全、负责任博彩或自定义）。在返回响应之前，系统会根据其类别约定对该事件进行验证、存储、针对每个唯一的公网 IP 地址进行一次 IP 信息补充，并由您的实时事件规则进行评估；跨主体和长窗口规则以异步方式运行（`correlation_pending: true`），而在沙盒应用中不运行任何规则。`event_id` 为幂等性密钥：相同的 `event_id` 搭配相同的 `event_category`、`action_type`、`occurred_at`、`subject.vendor_data` 和 `payload` 将返回 `200`，且包含 `idempotent_replay: true` 以及已存储的结果（不会比较其他外层字段），而不同的值将返回 `409`。事件摄取按应用选择开启：在开启之前，此 endpoint 将返回 `403` 及 `code: event_monitoring_disabled` 且不存储任何内容。带作用域的 API 密钥需要 `transactions: write` 权限。请参阅[事件摄取](https://docs.didit.me/zh/transaction-monitoring/events)和[事件规则](https://docs.didit.me/zh/transaction-monitoring/event-rules)；如需从浏览器或应用发送事件，请使用[SDK 事件提交](https://docs.didit.me/zh/transaction-monitoring/sdk-event-submission)。", "operationId": "create_monitoring_event", "x-didit-sdk": { "resource": "monitoring_events", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventCreateRequest" }, "examples": { "Login": { "value": { "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481Z", "time_zone": "Europe/Madrid", "subject": { "vendor_data": "user-42", "entity_type": "individual" }, "session": { "session_id": "web-session-abc", "sequence": 142 }, "device_context": { "fingerprint": "fp-a8c1", "network_context": { "ip_address": "203.0.113.42" } }, "payload": { "method": "password" }, "custom_values": { "vip_tier": "gold" } } }, "Deposit completed": { "value": { "event_id": "deposit-2026-10-17-000002", "event_category": "payment", "action_type": "deposit_completed", "occurred_at": "2026-10-17T09:16:40Z", "subject": { "vendor_data": "user-42" }, "transaction_context": { "amount": "100.00", "currency": "EUR", "direction": "inbound", "payment_reference_id": "dep_736" }, "payload": { "payment_method": "card", "status": "completed" } } }, "Chargeback opened": { "value": { "event_id": "chargeback-2026-10-16-000318", "event_category": "dispute", "action_type": "chargeback_opened", "occurred_at": "2026-10-16T14:02:11Z", "subject": { "vendor_data": "user-42" }, "payload": { "payment_reference_id": "dep_735", "chargeback_id": "cb_5521", "amount": "250.00", "currency": "EUR", "reason_code": "fraud" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/events/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"event_id\": \"login-2026-10-17-000001\",\n \"event_category\": \"auth\",\n \"action_type\": \"login\",\n \"occurred_at\": \"2026-10-17T09:15:02.481Z\",\n \"subject\": {\"vendor_data\": \"user-42\", \"entity_type\": \"individual\"},\n \"session\": {\"session_id\": \"web-session-abc\", \"sequence\": 142},\n \"device_context\": {\n \"fingerprint\": \"fp-a8c1\",\n \"network_context\": {\"ip_address\": \"203.0.113.42\"}\n },\n \"payload\": {\"method\": \"password\"}\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.create(\n event_id=\"login-2026-10-17-000001\",\n event_category=\"auth\",\n action_type=\"login\",\n occurred_at=\"2026-10-17T09:15:02.481Z\",\n time_zone=\"Europe/Madrid\",\n subject={\n \"vendor_data\": \"user-42\",\n \"entity_type\": \"individual\",\n },\n session={\n \"session_id\": \"web-session-abc\",\n \"sequence\": 142,\n },\n device_context={\n \"fingerprint\": \"fp-a8c1\",\n \"network_context\": {\n \"ip_address\": \"203.0.113.42\",\n },\n },\n payload={\"method\": \"password\"},\n custom_values={\"vip_tier\": \"gold\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.create({\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n time_zone: \"Europe/Madrid\",\n subject: {\n vendor_data: \"user-42\",\n entity_type: \"individual\",\n },\n session: {\n session_id: \"web-session-abc\",\n sequence: 142,\n },\n device_context: {\n fingerprint: \"fp-a8c1\",\n network_context: {\n ip_address: \"203.0.113.42\",\n },\n },\n payload: { method: \"password\" },\n custom_values: { vip_tier: \"gold\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Create(ctx, didit.MonitoringEventCreateRequest{\n\tEventID: \"login-2026-10-17-000001\",\n\tEventCategory: \"auth\",\n\tActionType: \"login\",\n\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\tTimeZone: didit.String(\"Europe/Madrid\"),\n\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\tVendorData: \"user-42\",\n\t\tEntityType: didit.String(\"individual\"),\n\t},\n\tSession: didit.Some(didit.MonitoringEventCreateRequestSession{\n\t\tSessionID: didit.String(\"web-session-abc\"),\n\t\tSequence: didit.Int(142),\n\t}),\n\tDeviceContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContext{\n\t\tFingerprint: didit.String(\"fp-a8c1\"),\n\t\tNetworkContext: didit.Some(didit.MonitoringEventCreateRequestDeviceContextNetworkContext{\n\t\t\tIPAddress: didit.String(\"203.0.113.42\"),\n\t\t}),\n\t}),\n\tPayload: didit.Some(map[string]any{\"method\": \"password\"}),\n\tCustomValues: didit.Some(map[string]any{\"vip_tier\": \"gold\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.MonitoringEventCreateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().create(MonitoringEventCreateRequest.builder()\n .eventId(\"login-2026-10-17-000001\")\n .eventCategory(MonitoringEventCreateRequest.EventCategory.of(\"auth\"))\n .actionType(\"login\")\n .occurredAt(OffsetDateTime.parse(\"2026-10-17T09:15:02.481Z\"))\n .timeZone(\"Europe/Madrid\")\n .subject(MonitoringEventCreateRequest.Subject.builder()\n .vendorData(\"user-42\")\n .entityType(\"individual\")\n .build())\n .session(MonitoringEventCreateRequest.Session.builder()\n .sessionId(\"web-session-abc\")\n .sequence(142L)\n .build())\n .deviceContext(MonitoringEventCreateRequest.DeviceContext.builder()\n .fingerprint(\"fp-a8c1\")\n .networkContext(MonitoringEventCreateRequest.DeviceContext.NetworkContext.builder()\n .ipAddress(\"203.0.113.42\")\n .build())\n .build())\n .payload(Map.of(\"method\", \"password\"))\n .customValues(Map.of(\"vip_tier\", MonitoringEventCreateRequest.CustomValuesValue.ofString(\"gold\")))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->create([\n 'event_id' => 'login-2026-10-17-000001',\n 'event_category' => 'auth',\n 'action_type' => 'login',\n 'occurred_at' => '2026-10-17T09:15:02.481Z',\n 'time_zone' => 'Europe/Madrid',\n 'subject' => [\n 'vendor_data' => 'user-42',\n 'entity_type' => 'individual',\n ],\n 'session' => [\n 'session_id' => 'web-session-abc',\n 'sequence' => 142,\n ],\n 'device_context' => [\n 'fingerprint' => 'fp-a8c1',\n 'network_context' => [\n 'ip_address' => '203.0.113.42',\n ],\n ],\n 'payload' => ['method' => 'password'],\n 'custom_values' => ['vip_tier' => 'gold'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.create(\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n time_zone: \"Europe/Madrid\",\n subject: {\n vendor_data: \"user-42\",\n entity_type: \"individual\",\n },\n session: {\n session_id: \"web-session-abc\",\n sequence: 142,\n },\n device_context: {\n fingerprint: \"fp-a8c1\",\n network_context: {\n ip_address: \"203.0.113.42\",\n },\n },\n payload: { method: \"password\" },\n custom_values: { vip_tier: \"gold\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.CreateAsync(new MonitoringEventCreateRequest\n{\n EventId = \"login-2026-10-17-000001\",\n EventCategory = \"auth\",\n ActionType = \"login\",\n OccurredAt = DateTimeOffset.Parse(\"2026-10-17T09:15:02.481Z\"),\n TimeZone = \"Europe/Madrid\",\n Subject = new()\n {\n VendorData = \"user-42\",\n EntityType = \"individual\",\n },\n Session = new MonitoringEventCreateRequestSession\n {\n SessionId = \"web-session-abc\",\n Sequence = 142,\n },\n DeviceContext = new MonitoringEventCreateRequestDeviceContext\n {\n Fingerprint = \"fp-a8c1\",\n NetworkContext = new MonitoringEventCreateRequestDeviceContextNetworkContext\n {\n IpAddress = \"203.0.113.42\",\n },\n },\n Payload = new Dictionary { [\"method\"] = \"password\" },\n CustomValues = new Dictionary { [\"vip_tier\"] = \"gold\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "事件已存储并完成评估。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventIngestResult" }, "examples": { "Stored, no rule matched": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [] } }, "Rule matched, async rule pending": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "IN_REVIEW", "score": 40, "rules_evaluated_count": 6, "rules_matched_count": 1, "correlation_pending": true, "retention_class": "risk_relevant", "expires_at": "2027-01-15T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [ { "rule_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "library_key": null, "mode": "ACTIVE", "is_async": false } ] } } } } } }, "200": { "description": "幂等重放：具有此 `event_id` 且内容相同的事件已被存储。未重新存储或评估任何内容；响应体描述已存储的事件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventIngestResult" }, "examples": { "Replay": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": true, "rule_matches": [] } } } } } }, "400": { "description": "验证失败。响应体以字段为键；嵌套字段为嵌套对象。未存储任何内容。", "content": { "application/json": { "examples": { "Missing fields": { "value": { "event_id": [ "This field is required." ], "subject": [ "This field is required." ] } }, "Unknown category": { "value": { "event_category": [ "\"login\" is not a valid choice." ] } }, "occurred_at too old": { "value": { "occurred_at": [ "occurred_at is more than 7 days in the past. Use the batch import lane for backfills." ] } }, "occurred_at in the future": { "value": { "occurred_at": [ "occurred_at is more than 5 minutes in the future." ] } }, "Missing subject vendor_data": { "value": { "subject": { "vendor_data": [ "This field is required." ] } } }, "Missing required payload keys": { "value": { "payload": [ "payment.deposit_completed requires: payment_method, status." ] } }, "Missing one-of payload key": { "value": { "payload": [ "dispute.chargeback_opened requires one of: dispute_id, chargeback_id." ] } }, "Security change without changed_field": { "value": { "payload": [ "security.*_changed requires 'changed_field'." ] } }, "Payload too large": { "value": { "payload": [ "payload exceeds 16384 bytes. Summarise telemetry client-side." ] } }, "Too many custom_values": { "value": { "custom_values": [ "custom_values accepts at most 100 keys." ] } }, "Nested custom value": { "value": { "custom_values": [ "custom_values['limits'] must be a scalar - rule conditions cannot address nested values." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: write` 权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP 白名单之外的请求。在应用关闭事件摄取时也会返回 `code: event_monitoring_disabled`；在此情况下不会存储任何内容，且该检查在验证请求体之前运行。", "content": { "application/json": { "examples": { "Event monitoring disabled": { "value": { "detail": "Event monitoring is not enabled for this application. Turn on event ingestion in the transaction monitoring settings before submitting events.", "code": "event_monitoring_disabled" } }, "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "409": { "description": "`event_id` 已用于具有不同内容的事件（类别、操作类型、`occurred_at`、主体 `vendor_data` 或 payload）。请使用新的 `event_id` 发送该事件。", "content": { "application/json": { "examples": { "event_id reused": { "value": { "event_id": "event_id 'login-2026-10-17-000001' already exists with a different payload." } } } } } }, "429": { "description": "超出速率限制：交易创建和事件摄入（`POST /v3/transactions/`、`POST /v3/events/`、`POST /v3/events/batch/`）共享每个 API 密钥每分钟 600 次请求的配额，独立于所有其他写入请求共享的 300 次配额。请等待 `Retry-After` 秒，然后重试。", "headers": { "Retry-After": { "description": "重试前需等待的秒数，向上取整以确保重试落在下一个时间窗口内。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Ingestion rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/batch/": { "post": { "summary": "批量创建监控事件", "description": "在单个请求中提交 1 到 500 个事件，每个事件使用与 `POST /v3/events/` 相同的外层结构。每个项目均单独进行验证、存储和评估，并获得各自的处理结果（`accepted`、`replayed` 或 `rejected`），因此某个格式错误的事件绝不会导致其他事件回滚：当没有项目被拒绝时响应为 `201`，当至少有一个项目被拒绝时响应为 `207`，两者均表示请求已处理。发送 `{\"events\": [...]}`；纯 JSON 事件数组也可接受。必须为该应用开启事件摄取，否则整个请求将返回 `403` 及 `code: event_monitoring_disabled`，且不会存储任何内容。具有限定作用域的 API 密钥需要具备 `transactions: write` 权限。请参见 [Batches](https://docs.didit.me/zh/transaction-monitoring/events#批量)。", "operationId": "create_monitoring_events_batch", "x-didit-sdk": { "resource": "monitoring_events", "method": "create_batch", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "events" ], "properties": { "events": { "type": "array", "minItems": 1, "maxItems": 500, "description": "1 到 500 个事件。每项均遵循 `MonitoringEventCreateRequest`，包括 `occurred_at` 的过去 7 天和未来 5 分钟时间窗口。", "items": { "$ref": "#/components/schemas/MonitoringEventCreateRequest" } } } }, "example": { "events": [ { "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481Z", "subject": { "vendor_data": "user-42" } }, { "event_id": "deposit-2026-10-17-000002", "event_category": "payment", "action_type": "deposit_completed", "occurred_at": "2026-10-17T09:16:40Z", "subject": { "vendor_data": "user-42" }, "transaction_context": { "amount": "100.00", "currency": "EUR", "payment_reference_id": "dep_736" }, "payload": { "payment_method": "card", "status": "completed" } } ] } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/events/batch/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"events\": [\n {\"event_id\": \"login-2026-10-17-000001\", \"event_category\": \"auth\", \"action_type\": \"login\",\n \"occurred_at\": \"2026-10-17T09:15:02.481Z\", \"subject\": {\"vendor_data\": \"user-42\"}},\n {\"event_id\": \"deposit-2026-10-17-000002\", \"event_category\": \"payment\", \"action_type\": \"deposit_completed\",\n \"occurred_at\": \"2026-10-17T09:16:40.000Z\", \"subject\": {\"vendor_data\": \"user-42\"},\n \"transaction_context\": {\"amount\": \"100.00\", \"currency\": \"EUR\", \"payment_reference_id\": \"dep_736\"},\n \"payload\": {\"payment_method\": \"card\", \"status\": \"completed\"}}\n ]\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.create_batch(\n events=[{\n \"event_id\": \"login-2026-10-17-000001\",\n \"event_category\": \"auth\",\n \"action_type\": \"login\",\n \"occurred_at\": \"2026-10-17T09:15:02.481Z\",\n \"subject\": {\n \"vendor_data\": \"user-42\",\n },\n }, {\n \"event_id\": \"deposit-2026-10-17-000002\",\n \"event_category\": \"payment\",\n \"action_type\": \"deposit_completed\",\n \"occurred_at\": \"2026-10-17T09:16:40Z\",\n \"subject\": {\n \"vendor_data\": \"user-42\",\n },\n \"transaction_context\": {\n \"amount\": \"100.00\",\n \"currency\": \"EUR\",\n \"payment_reference_id\": \"dep_736\",\n },\n \"payload\": {\"payment_method\": \"card\", \"status\": \"completed\"},\n }],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.createBatch({\n events: [{\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n }, {\n event_id: \"deposit-2026-10-17-000002\",\n event_category: \"payment\",\n action_type: \"deposit_completed\",\n occurred_at: \"2026-10-17T09:16:40Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n transaction_context: {\n amount: \"100.00\",\n currency: \"EUR\",\n payment_reference_id: \"dep_736\",\n },\n payload: { payment_method: \"card\", status: \"completed\" },\n }],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.CreateBatch(ctx, didit.MonitoringEventsCreateBatchParams{\n\tEvents: []didit.MonitoringEventCreateRequest{{\n\t\tEventID: \"login-2026-10-17-000001\",\n\t\tEventCategory: \"auth\",\n\t\tActionType: \"login\",\n\t\tOccurredAt: time.Date(2026, 10, 17, 9, 15, 2, 0, time.UTC),\n\t\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\t\tVendorData: \"user-42\",\n\t\t},\n\t}, {\n\t\tEventID: \"deposit-2026-10-17-000002\",\n\t\tEventCategory: \"payment\",\n\t\tActionType: \"deposit_completed\",\n\t\tOccurredAt: time.Date(2026, 10, 17, 9, 16, 40, 0, time.UTC),\n\t\tSubject: didit.MonitoringEventCreateRequestSubject{\n\t\t\tVendorData: \"user-42\",\n\t\t},\n\t\tTransactionContext: didit.Some(didit.MonitoringEventCreateRequestTransactionContext{\n\t\t\tAmount: didit.String(\"100.00\"),\n\t\t\tCurrency: didit.String(\"EUR\"),\n\t\t\tPaymentReferenceID: didit.String(\"dep_736\"),\n\t\t}),\n\t\tPayload: didit.Some(map[string]any{\"payment_method\": \"card\", \"status\": \"completed\"}),\n\t}},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.OffsetDateTime;\nimport java.util.List;\nimport java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.MonitoringEventCreateRequest;\nimport me.didit.types.MonitoringEventsCreateBatchParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().createBatch(MonitoringEventsCreateBatchParams.builder()\n .events(List.of(\n MonitoringEventCreateRequest.builder()\n .eventId(\"login-2026-10-17-000001\")\n .eventCategory(MonitoringEventCreateRequest.EventCategory.of(\"auth\"))\n .actionType(\"login\")\n .occurredAt(OffsetDateTime.parse(\"2026-10-17T09:15:02.481Z\"))\n .subject(MonitoringEventCreateRequest.Subject.builder()\n .vendorData(\"user-42\")\n .build())\n .build(),\n MonitoringEventCreateRequest.builder()\n .eventId(\"deposit-2026-10-17-000002\")\n .eventCategory(MonitoringEventCreateRequest.EventCategory.of(\"payment\"))\n .actionType(\"deposit_completed\")\n .occurredAt(OffsetDateTime.parse(\"2026-10-17T09:16:40Z\"))\n .subject(MonitoringEventCreateRequest.Subject.builder()\n .vendorData(\"user-42\")\n .build())\n .transactionContext(MonitoringEventCreateRequest.TransactionContext.builder()\n .amount(\"100.00\")\n .currency(\"EUR\")\n .paymentReferenceId(\"dep_736\")\n .build())\n .payload(Map.of(\"payment_method\", \"card\", \"status\", \"completed\"))\n .build()))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->createBatch([\n 'events' => [[\n 'event_id' => 'login-2026-10-17-000001',\n 'event_category' => 'auth',\n 'action_type' => 'login',\n 'occurred_at' => '2026-10-17T09:15:02.481Z',\n 'subject' => [\n 'vendor_data' => 'user-42',\n ],\n ], [\n 'event_id' => 'deposit-2026-10-17-000002',\n 'event_category' => 'payment',\n 'action_type' => 'deposit_completed',\n 'occurred_at' => '2026-10-17T09:16:40Z',\n 'subject' => [\n 'vendor_data' => 'user-42',\n ],\n 'transaction_context' => [\n 'amount' => '100.00',\n 'currency' => 'EUR',\n 'payment_reference_id' => 'dep_736',\n ],\n 'payload' => ['payment_method' => 'card', 'status' => 'completed'],\n ]],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.create_batch(\n events: [{\n event_id: \"login-2026-10-17-000001\",\n event_category: \"auth\",\n action_type: \"login\",\n occurred_at: \"2026-10-17T09:15:02.481Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n }, {\n event_id: \"deposit-2026-10-17-000002\",\n event_category: \"payment\",\n action_type: \"deposit_completed\",\n occurred_at: \"2026-10-17T09:16:40Z\",\n subject: {\n vendor_data: \"user-42\",\n },\n transaction_context: {\n amount: \"100.00\",\n currency: \"EUR\",\n payment_reference_id: \"dep_736\",\n },\n payload: { payment_method: \"card\", status: \"completed\" },\n }]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.CreateBatchAsync(new MonitoringEventsCreateBatchParams\n{\n Events = new MonitoringEventCreateRequest[]\n {\n new()\n {\n EventId = \"login-2026-10-17-000001\",\n EventCategory = \"auth\",\n ActionType = \"login\",\n OccurredAt = DateTimeOffset.Parse(\"2026-10-17T09:15:02.481Z\"),\n Subject = new()\n {\n VendorData = \"user-42\",\n },\n },\n new()\n {\n EventId = \"deposit-2026-10-17-000002\",\n EventCategory = \"payment\",\n ActionType = \"deposit_completed\",\n OccurredAt = DateTimeOffset.Parse(\"2026-10-17T09:16:40Z\"),\n Subject = new()\n {\n VendorData = \"user-42\",\n },\n TransactionContext = new MonitoringEventCreateRequestTransactionContext\n {\n Amount = \"100.00\",\n Currency = \"EUR\",\n PaymentReferenceId = \"dep_736\",\n },\n Payload = new Dictionary { [\"payment_method\"] = \"card\", [\"status\"] = \"completed\" },\n },\n },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "没有任何项目被拒绝：每个项目均为 `accepted` 或 `replayed`。", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted_count", "replayed_count", "rejected_count", "results" ], "properties": { "accepted_count": { "type": "integer", "minimum": 0, "description": "已存储并已评估的项目。" }, "replayed_count": { "type": "integer", "minimum": 0, "description": "已存储且内容相同的项目。" }, "rejected_count": { "type": "integer", "minimum": 0, "description": "未存储的项目。" }, "results": { "type": "array", "description": "每个项目对应一个条目，按请求顺序排列。", "items": { "type": "object", "description": "单个条目的处理结果。已接受和重放的条目还会包含 `MonitoringEventIngestResult` 的每个字段；被拒绝的条目则包含 `event_id` 和 `errors`。", "required": [ "index", "outcome" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "项目在 `events` 数组中的位置。" }, "outcome": { "type": "string", "enum": [ "accepted", "replayed", "rejected" ], "description": "`accepted`：已存储并评估。`replayed`：已存储相同内容。`rejected`：未存储；请参见 `errors`。" }, "event_id": { "type": "string", "nullable": true, "description": "您的 `event_id`。对于因验证被拒绝的项，系统会从该项的 snake_case 命名 `event_id` 键中读取；因此当该项省略该键或发送了 `eventId` 别名时，此值为 null。" }, "errors": { "type": "object", "additionalProperties": true, "description": "仅限已拒绝的项。以字段为键的验证错误，格式与 `POST /v3/events/` 的 `400` 相同；具有不同内容的重复使用的 `event_id` 会在 `errors.event_id` 下报告为字符串。" }, "event_uuid": { "type": "string", "format": "uuid", "description": "仅限已接受和重放的项目。" }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "仅限已接受和重放的项目。" }, "score": { "type": "integer", "description": "仅限已接受和重放的项目。" }, "rules_evaluated_count": { "type": "integer", "description": "仅限已接受和重放的项目。" }, "rules_matched_count": { "type": "integer", "description": "仅限已接受和重放的项目。" }, "correlation_pending": { "type": "boolean", "description": "仅限已接受和重放的项目。" }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "仅限已接受和重放的项目。" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "仅限已接受和重放的项目。" }, "idempotent_replay": { "type": "boolean", "description": "仅限已接受和重放的项目。" }, "rule_matches": { "type": "array", "description": "仅限已接受和重放的项目。", "items": { "type": "object", "required": [ "rule_id", "library_key", "mode", "is_async" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "description": "规则的 UUID。" }, "library_key": { "type": "string", "nullable": true, "description": "规则从规则库安装时的库密钥，否则为 null。" }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "`TEST` 规则会记录匹配，但不应用任何操作。" }, "is_async": { "type": "boolean", "description": "当比对结果来自异步轮次时为 `true`。" } } } } } } } } }, "examples": { "All landed": { "value": { "accepted_count": 1, "replayed_count": 1, "rejected_count": 0, "results": [ { "index": 0, "outcome": "accepted", "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [] }, { "index": 1, "outcome": "replayed", "event_uuid": "11111111-2222-3333-4444-555555555555", "event_id": "deposit-2026-10-17-000002", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "monetary_or_compliance", "expires_at": null, "idempotent_replay": true, "rule_matches": [] } ] } } } } } }, "207": { "description": "至少有一个项目被拒绝。其他项目已存储；请仅修复并重新发送被拒绝的项目（重新发送已接受的项目是安全的，会返回 `replayed`）。", "content": { "application/json": { "schema": { "type": "object", "required": [ "accepted_count", "replayed_count", "rejected_count", "results" ], "properties": { "accepted_count": { "type": "integer", "minimum": 0, "description": "已存储并已评估的项目。" }, "replayed_count": { "type": "integer", "minimum": 0, "description": "已存储且内容相同的项目。" }, "rejected_count": { "type": "integer", "minimum": 0, "description": "未存储的项目。" }, "results": { "type": "array", "description": "每个项目对应一个条目，按请求顺序排列。", "items": { "type": "object", "description": "单个条目的处理结果。已接受和重放的条目还会包含 `MonitoringEventIngestResult` 的每个字段；被拒绝的条目则包含 `event_id` 和 `errors`。", "required": [ "index", "outcome" ], "properties": { "index": { "type": "integer", "minimum": 0, "description": "项目在 `events` 数组中的位置。" }, "outcome": { "type": "string", "enum": [ "accepted", "replayed", "rejected" ], "description": "`accepted`：已存储并评估。`replayed`：已存储相同内容。`rejected`：未存储；请参见 `errors`。" }, "event_id": { "type": "string", "nullable": true, "description": "您的 `event_id`。对于因验证被拒绝的项，系统会从该项的 snake_case 命名 `event_id` 键中读取；因此当该项省略该键或发送了 `eventId` 别名时，此值为 null。" }, "errors": { "type": "object", "additionalProperties": true, "description": "仅限已拒绝的项。以字段为键的验证错误，格式与 `POST /v3/events/` 的 `400` 相同；具有不同内容的重复使用的 `event_id` 会在 `errors.event_id` 下报告为字符串。" }, "event_uuid": { "type": "string", "format": "uuid", "description": "仅限已接受和重放的项目。" }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "仅限已接受和重放的项目。" }, "score": { "type": "integer", "description": "仅限已接受和重放的项目。" }, "rules_evaluated_count": { "type": "integer", "description": "仅限已接受和重放的项目。" }, "rules_matched_count": { "type": "integer", "description": "仅限已接受和重放的项目。" }, "correlation_pending": { "type": "boolean", "description": "仅限已接受和重放的项目。" }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "仅限已接受和重放的项目。" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "仅限已接受和重放的项目。" }, "idempotent_replay": { "type": "boolean", "description": "仅限已接受和重放的项目。" }, "rule_matches": { "type": "array", "description": "仅限已接受和重放的项目。", "items": { "type": "object", "required": [ "rule_id", "library_key", "mode", "is_async" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "description": "规则的 UUID。" }, "library_key": { "type": "string", "nullable": true, "description": "规则从规则库安装时的库密钥，否则为 null。" }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "`TEST` 规则会记录匹配，但不应用任何操作。" }, "is_async": { "type": "boolean", "description": "当比对结果来自异步轮次时为 `true`。" } } } } } } } } }, "examples": { "Partial success": { "value": { "accepted_count": 1, "replayed_count": 0, "rejected_count": 2, "results": [ { "index": 0, "outcome": "accepted", "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "status": "ACCEPTED", "score": 0, "rules_evaluated_count": 6, "rules_matched_count": 0, "correlation_pending": false, "retention_class": "standard", "expires_at": "2026-11-16T09:15:02.481000Z", "idempotent_replay": false, "rule_matches": [] }, { "index": 1, "event_id": "deposit-2026-10-17-000002", "outcome": "rejected", "errors": { "payload": [ "payment.deposit_completed requires: payment_method, status." ] } }, { "index": 2, "event_id": "login-2026-10-16-000777", "outcome": "rejected", "errors": { "event_id": "event_id 'login-2026-10-16-000777' already exists with a different payload." } } ] } } } } } }, "400": { "description": "批次本身格式错误：`events` 缺失、非数组、为空或包含超过 500 项。未存储任何内容；请拆分大批次。", "content": { "application/json": { "examples": { "Not a list": { "value": { "events": "Expected a list of events." } }, "Empty": { "value": { "events": "At least one event is required." } }, "Too many": { "value": { "events": "A batch accepts at most 500 events; received 612." } } } } } }, "401": { "description": "作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: write` 权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP 白名单之外的请求。在应用关闭事件摄取时也会返回 `code: event_monitoring_disabled`；在此情况下不会存储任何内容，且该检查在验证请求体之前运行。", "content": { "application/json": { "examples": { "Event monitoring disabled": { "value": { "detail": "Event monitoring is not enabled for this application. Turn on event ingestion in the transaction monitoring settings before submitting events.", "code": "event_monitoring_disabled" } }, "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "超出速率限制：交易创建和事件摄入（`POST /v3/transactions/`、`POST /v3/events/`、`POST /v3/events/batch/`）共享每个 API 密钥每分钟 600 次请求的配额，独立于所有其他写入请求共享的 300 次配额。请等待 `Retry-After` 秒，然后重试。", "headers": { "Retry-After": { "description": "重试前需等待的秒数，向上取整以确保重试落在下一个时间窗口内。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Ingestion rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/sdk-token/": { "post": { "summary": "生成监控 SDK token", "description": "生成绑定至单个主体的短期设备凭据，以便您的 Web 或移动应用可以直接将该用户的事件发送至 Didit，而无需 API 密钥。应用在发送到设备通道（`POST /v1/events/` 和 `POST /v1/events/batch/`）的请求中，需通过 `X-Monitoring-Token` 请求头携带返回的 `monitoring_token`；在此通道中，主体始终会被此 `vendor_data` 覆盖，超出 `allowed_event_categories` 的事件会被拒绝，每次提交事件消耗一次使用额度，且 `Origin` 不等于 `bind_to_origin` 的请求会被拒绝。请仅从您的后端调用此接口；生成操作仅创建凭据，不执行其他操作（不会创建用户）。应用必须开启事件接收功能，否则此 endpoint 将返回带有 `code: event_monitoring_disabled` 的 `403`，而不是生成一个永远无法写入的凭据。限定范围的 API 密钥需要具备 `transactions: write` 权限。请参阅[SDK 事件提交](https://docs.didit.me/zh/transaction-monitoring/sdk-event-submission)。", "operationId": "create_monitoring_event_sdk_token", "x-didit-sdk": { "resource": "monitoring_events", "method": "create_sdk_token", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "支持驼峰命名（camelCase）别名：`vendorData`、`entityType`、`allowedEventCategories`、`ttlSeconds`、`maxUses`、`bindToOrigin`。", "required": [ "vendor_data" ], "properties": { "vendor_data": { "type": "string", "minLength": 1, "maxLength": 255, "description": "您对使用此凭据提交的每个事件所属主体的 ID。" }, "entity_type": { "type": "string", "maxLength": 32, "default": "individual", "description": "`company` 绑定企业主体；任何其他值（默认 `individual`）绑定个人。" }, "allowed_event_categories": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] }, "description": "该凭证可以提交的类别。省略或发送 `[]` 以允许所有类别。" }, "ttl_seconds": { "type": "integer", "minimum": 60, "maximum": 86400, "default": 900, "description": "凭据的生命周期（秒）。" }, "max_uses": { "type": "integer", "minimum": 1, "nullable": true, "default": 1000, "description": "该凭据可提交的事件数量（批处理中的每个事件消耗一次使用次数）。传入 `null` 表示有效期内不设上限。" }, "bind_to_origin": { "type": "string", "maxLength": 255, "nullable": true, "description": "设置后，每个设备请求的浏览器 `Origin` 请求头必须完全等于此值；没有 `Origin` 的请求将被拒绝。" } } }, "example": { "vendor_data": "user-42", "allowed_event_categories": [ "auth", "session", "gameplay" ], "ttl_seconds": 900, "max_uses": 1000, "bind_to_origin": "https://app.example.com" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/events/sdk-token/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"vendor_data\": \"user-42\",\n \"allowed_event_categories\": [\"auth\", \"session\", \"gameplay\"],\n \"ttl_seconds\": 900,\n \"max_uses\": 1000,\n \"bind_to_origin\": \"https://app.example.com\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.create_sdk_token(\n vendor_data=\"user-42\",\n allowed_event_categories=[\"auth\", \"session\", \"gameplay\"],\n ttl_seconds=900,\n max_uses=1000,\n bind_to_origin=\"https://app.example.com\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.createSdkToken({\n vendor_data: \"user-42\",\n allowed_event_categories: [\"auth\", \"session\", \"gameplay\"],\n ttl_seconds: 900,\n max_uses: 1000,\n bind_to_origin: \"https://app.example.com\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.CreateSDKToken(ctx, didit.MonitoringEventsCreateSDKTokenParams{\n\tVendorData: \"user-42\",\n\tAllowedEventCategories: didit.Some([]didit.MonitoringEventsCreateSDKTokenParamsAllowedEventCategories{\"auth\", \"session\", \"gameplay\"}),\n\tTTLSeconds: didit.Int(900),\n\tMaxUses: didit.Int(1000),\n\tBindToOrigin: didit.String(\"https://app.example.com\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.MonitoringEventsCreateSdkTokenParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().createSdkToken(MonitoringEventsCreateSdkTokenParams.builder()\n .vendorData(\"user-42\")\n .allowedEventCategories(List.of(MonitoringEventsCreateSdkTokenParams.AllowedEventCategories.of(\"auth\"), MonitoringEventsCreateSdkTokenParams.AllowedEventCategories.of(\"session\"), MonitoringEventsCreateSdkTokenParams.AllowedEventCategories.of(\"gameplay\")))\n .ttlSeconds(900L)\n .maxUses(1000L)\n .bindToOrigin(\"https://app.example.com\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->createSdkToken([\n 'vendor_data' => 'user-42',\n 'allowed_event_categories' => ['auth', 'session', 'gameplay'],\n 'ttl_seconds' => 900,\n 'max_uses' => 1000,\n 'bind_to_origin' => 'https://app.example.com',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.create_sdk_token(\n vendor_data: \"user-42\",\n allowed_event_categories: [\"auth\", \"session\", \"gameplay\"],\n ttl_seconds: 900,\n max_uses: 1000,\n bind_to_origin: \"https://app.example.com\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.CreateSdkTokenAsync(new MonitoringEventsCreateSdkTokenParams\n{\n VendorData = \"user-42\",\n AllowedEventCategories = new MonitoringEventsCreateSdkTokenParamsAllowedEventCategories[] { \"auth\", \"session\", \"gameplay\" },\n TtlSeconds = 900,\n MaxUses = 1000,\n BindToOrigin = \"https://app.example.com\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "凭证已生成。请将 `monitoring_token` 传递给应用，并在 `expires_at` 之前将其视为秘密。", "content": { "application/json": { "schema": { "type": "object", "required": [ "monitoring_token", "expires_at", "allowed_event_categories", "max_uses", "bind_to_origin" ], "properties": { "monitoring_token": { "type": "string", "description": "设备凭证（43 个字符的 URL 安全 token）。请在 `X-Monitoring-Token` 请求头中发送。" }, "expires_at": { "type": "string", "format": "date-time", "description": "凭据停止被接受的时间。" }, "allowed_event_categories": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] }, "description": "该凭证可以提交的类别；`[]` 表示所有类别。" }, "max_uses": { "type": "integer", "nullable": true, "description": "凭据的事件预算；null 表示无上限。" }, "bind_to_origin": { "type": "string", "nullable": true, "description": "凭据绑定的来源（Origin），或 null。" } } }, "example": { "monitoring_token": "q7ZtR2xKp9VbN4mWc8LdH1sYfJ3gT6uEaQ0oPiXzBkC", "expires_at": "2026-10-17T09:30:02.481000Z", "allowed_event_categories": [ "auth", "session", "gameplay" ], "max_uses": 1000, "bind_to_origin": "https://app.example.com" } } } }, "400": { "description": "验证失败：缺少 `vendor_data`、`ttl_seconds` 不在 60 到 86400 之间、`max_uses` 小于 1，或存在未知类别（按其在数组中的位置作为键）。", "content": { "application/json": { "examples": { "Missing vendor_data": { "value": { "vendor_data": [ "This field is required." ] } }, "ttl_seconds too short": { "value": { "ttl_seconds": [ "Ensure this value is greater than or equal to 60." ] } }, "Unknown category": { "value": { "allowed_event_categories": { "1": [ "\"login\" is not a valid choice." ] } } } } } } }, "401": { "description": "作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: write` 权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP 白名单之外的请求。在应用关闭事件摄取时也会返回 `code: event_monitoring_disabled`；在此情况下不会存储任何内容，且该检查在验证请求体之前运行。", "content": { "application/json": { "examples": { "Event monitoring disabled": { "value": { "detail": "Event monitoring is not enabled for this application. Turn on event ingestion in the transaction monitoring settings before submitting events.", "code": "event_monitoring_disabled" } }, "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥的写入请求（`POST`、`PATCH`、`DELETE`）共享每分钟 300 次的配额。请等待 `Retry-After` 秒，然后重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/{event_uuid}/": { "get": { "summary": "获取监控事件", "description": "获取单个监控事件，包含列表返回的所有内容，以及 payload、自定义值、设备上下文、字段来源（`field_sources`）、提升后的域字段、`expires_at`、每个匹配的规则运行及其证据、IP 富化信息以及规则附加的标签。当 `correlation_pending` 为 `true` 时，表示仍有异步规则需要运行；请在几分钟后重新读取该事件以获取最终的 `status`、`score` 和 `rule_runs`。无论是否开启事件摄取，读取操作均可正常工作。作用域受限的 API 密钥需要 `transactions: read` 权限。请参阅[证据](https://docs.didit.me/zh/transaction-monitoring/event-rules#证据)和[IP 富化](https://docs.didit.me/zh/transaction-monitoring/ip-enrichment)。", "operationId": "get_monitoring_event", "x-didit-sdk": { "resource": "monitoring_events", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "event_uuid", "in": "path", "required": true, "description": "事件的 Didit 标识符（创建、批量、列表或时间线响应中的 `event_uuid`），而非您自己的 `event_id`。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/11111111-2222-3333-4444-555555555555/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.retrieve(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.retrieve(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.Retrieve(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().retrieve(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->retrieve('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.retrieve(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.RetrieveAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "包含佐证材料的事件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventDetail" }, "examples": { "Login from a VPN, in review": { "value": { "event_uuid": "33333333-4444-5555-6666-777777777777", "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481000Z", "received_at": "2026-10-17T09:15:02.903114Z", "status": "IN_REVIEW", "score": 40, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": "web-session-abc", "device_fingerprint": "fp-a8c1", "ip_address": "203.0.113.42", "ip_country": "ES", "amount": null, "currency": null, "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": null, "retention_class": "risk_relevant", "rules_matched_count": 1, "correlation_pending": false, "is_droppable": true, "payload": { "method": "password" }, "custom_values": { "vip_tier": "gold", "vpn_or_proxy_detected": true }, "device_context": { "fingerprint": "fp-a8c1", "network_context": { "ip_address": "203.0.113.42", "ip_country": "Spain", "ip_country_code": "ES", "ip_city": "Madrid", "asn_number": 64500, "asn_organization": "Example Networks", "is_vpn_or_tor": true, "is_data_center": false } }, "field_sources": { "subject.vendor_data": "customer", "event_category": "customer", "action_type": "customer", "occurred_at": "customer", "received_at": "server", "payload.method": "customer", "session.session_id": "customer", "session.sequence": "customer", "device_context.fingerprint": "customer", "device_context.network_context.ip_address": "customer", "device_context.network_context.ip_country": "server", "device_context.network_context.ip_country_code": "server", "device_context.network_context.ip_city": "server", "device_context.network_context.asn_number": "server", "device_context.network_context.asn_organization": "server", "device_context.network_context.is_vpn_or_tor": "server", "device_context.network_context.is_data_center": "server" }, "session_sequence": 142, "table_id": null, "hand_id": null, "match_id": null, "market_id": null, "side": null, "role": null, "net_result_amount": null, "payment_fingerprint": null, "instrument_reference_hash": null, "withdrawal_address_hash": null, "dispute_id": null, "chargeback_id": null, "changed_field": null, "identity_match_ref": null, "schema_version": 1, "expires_at": "2027-01-15T09:15:02.481000Z", "rules_evaluated_count": 6, "rule_runs": [ { "rule_uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "rule_title": "Login from VPN or Tor", "library_key": null, "matched": true, "mode": "ACTIVE", "is_async": false, "severity": "MEDIUM", "score_delta": 40, "action_summary": "score +40; add_tag:VPN_LOGIN", "matched_payload": [ { "field": "event.ip.is_vpn_or_tor", "operator": "eq", "expected_value": true, "current_value": true, "matched": true, "group_index": null, "group_logic": "AND", "field_source": "server" } ], "created_at": "2026-10-17T09:15:02.951207Z" } ], "ip_enrichment": { "ip_country_code": "ES", "ip_city": "Madrid", "asn_number": 64500, "asn_organization": "Example Networks", "is_vpn_or_tor": true, "is_data_center": false, "proxy_type": null, "last_enriched_at": "2026-10-17T09:15:02.910442Z" }, "subject_profile": null, "tags": [ "VPN_LOGIN" ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: read` 权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP 白名单之外的请求。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "应用中不存在具有此 `event_uuid` 的事件：从未存储、已被删除，或属于另一个应用。非 UUID 的路径段与路由不匹配，也会返回 `404`。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No MonitoringEvent matches the given query." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥的 `GET` 请求共享每分钟 600 次的配额。请等待 `Retry-After` 秒，然后重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/subjects/{vendor_data}/": { "get": { "summary": "获取主体事件时间线", "description": "列出单个主体的所有监控事件，按 `occurred_at` 最新的优先。`vendor_data` 仅在实体类型内部具有唯一性，因此相同的 ID 可同时命名个人和公司：`entity_type` 用于选取您获取的时间线，其默认为 `individual`，因此公司事件需要指定 `entity_type=company`。`GET /v3/events/` 的过滤器在其之上同样适用，且没有任何事件的 `vendor_data` 会返回空页面而非 `404`。限定范围的 API 密钥需要 `transactions: read` 权限。参见[回读事件](https://docs.didit.me/zh/transaction-monitoring/events#读取事件)。", "operationId": "get_monitoring_event_subject_timeline", "x-didit-sdk": { "resource": "monitoring_events", "method": "retrieve_subject_timeline", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "vendor_data", "in": "path", "required": true, "description": "您对主体的 ID（对应其事件的 `subject.vendor_data`）。请对其进行 URL 编码；包含 `/` 的值无法被该 endpoint 寻址。", "schema": { "type": "string", "minLength": 1, "maxLength": 255 }, "example": "user-42" }, { "name": "entity_type", "in": "query", "required": false, "description": "`company` 返回具有此 `vendor_data` 的企业；任何其他值或无值则返回个人。当 `entity_type` 不存在时，接受 `subject_entity_type` 作为别名。", "schema": { "type": "string", "enum": [ "individual", "company" ], "default": "individual" }, "example": "individual" }, { "name": "limit", "in": "query", "required": false, "description": "每页最大事件数。默认值为 50。超过 1000000 的值将返回 `400`；非数值、零或负值将回退至 50。", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "example": 50 }, { "name": "offset", "in": "query", "required": false, "description": "要跳过的事件数量。默认为 0。建议使用响应中的 `next` URL。", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "example": 0 }, { "name": "event_category", "in": "query", "required": false, "description": "仅包含这些类别中的事件。对多个值重复该参数（`?event_category=payment&event_category=dispute`）；匹配其中任一类别的事件都会被返回。", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ] } }, "example": [ "payment", "dispute" ] }, { "name": "action_type", "in": "query", "required": false, "description": "仅包含具有这些操作类型的事件（精确匹配，区分大小写）。对多个值重复使用。", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "deposit_completed", "chargeback_opened" ] }, { "name": "status", "in": "query", "required": false, "description": "仅包含具有这些状态的事件。对多个值重复使用。", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ] } }, "example": [ "IN_REVIEW", "DECLINED" ] }, { "name": "retention_class", "in": "query", "required": false, "description": "仅包含这些保留类别中的事件。对多个值重复使用。", "style": "form", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ] } }, "example": [ "risk_relevant" ] }, { "name": "business_vendor_data", "in": "query", "required": false, "description": "对随事件发送的 `business.vendor_data` 的精确匹配。", "schema": { "type": "string" }, "example": "merchant-7" }, { "name": "session_id", "in": "query", "required": false, "description": "对 `session.session_id` 的精确匹配。", "schema": { "type": "string" }, "example": "web-session-abc" }, { "name": "device_fingerprint", "in": "query", "required": false, "description": "对 `device_context.fingerprint` 的精确匹配。", "schema": { "type": "string" }, "example": "fp-a8c1" }, { "name": "ip_address", "in": "query", "required": false, "description": "对事件的 IP 地址进行精确匹配。", "schema": { "type": "string" }, "example": "203.0.113.42" }, { "name": "game_id", "in": "query", "required": false, "description": "对已提升的 `game_id` 的精确匹配。", "schema": { "type": "string" }, "example": "poker-holdem-01" }, { "name": "round_id", "in": "query", "required": false, "description": "对已提升的 `round_id` 的精确匹配。", "schema": { "type": "string" }, "example": "round-88231" }, { "name": "affiliate_code", "in": "query", "required": false, "description": "对已提升的 `affiliate_code` 的精确匹配。", "schema": { "type": "string" }, "example": "aff-summer" }, { "name": "payment_reference_id", "in": "query", "required": false, "description": "对支付参考信息的精确匹配（来自 `transaction_context.payment_reference_id` 或 `payload.payment_reference_id`）。", "schema": { "type": "string" }, "example": "dep_735" }, { "name": "counterparty_vendor_data", "in": "query", "required": false, "description": "对已提升的 `counterparty_vendor_data` 的精确匹配。", "schema": { "type": "string" }, "example": "user-77" }, { "name": "matched_only", "in": "query", "required": false, "description": "`true`（亦可为 `1` 或 `yes`，不区分大小写）仅返回匹配至少一条规则的事件（`rules_matched_count` 大于 0）。任何其他值将被忽略。", "schema": { "type": "boolean", "default": false }, "example": true }, { "name": "occurred_from", "in": "query", "required": false, "description": "仅包含 `occurred_at` 在此时间点或之后（包含）的事件。发送 ISO 8601 格式的值：`2026-10-01T00:00:00Z`、带有百分号编码 `+` 的显式偏移量（`2026-10-01T02:00:00%2B02:00`；未编码的 `+` 会被解码为空格导致该值无法解析），或仅日期（`2026-10-01`），表示当天的 00:00:00 UTC。无偏移量的值按 UTC 读取。不接受任何其他格式的值。", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "occurred_to", "in": "query", "required": false, "description": "仅包含 `occurred_at` 在此时间点或之前（包含）的事件。仅日期表示当天的开始，因此 `occurred_to=2026-10-15` 会排除 10 月 15 日的其余时间；发送 `2026-10-15T23:59:59Z` 以包含全天。发送 ISO 8601 格式的值：`2026-10-01T00:00:00Z`、带有百分号编码 `+` 的显式偏移量（`2026-10-01T02:00:00%2B02:00`；未编码的 `+` 会被解码为空格导致该值无法解析），或仅日期（`2026-10-01`），表示当天的 00:00:00 UTC。无偏移量的值按 UTC 读取。不接受任何其他格式的值。", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-17T23:59:59Z" }, { "name": "search", "in": "query", "required": false, "description": "对 `event_id`、`action_type`、`subject_vendor_data` 或 `counterparty_vendor_data` 进行不区分大小写的子字符串匹配。", "schema": { "type": "string" }, "example": "chargeback" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/subjects/user-42/?entity_type=individual&limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.monitoring_events.retrieve_subject_timeline(\n \"user-42\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.monitoringEvents.retrieveSubjectTimeline(\"user-42\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.MonitoringEvents.RetrieveSubjectTimelineAutoPaging(ctx, \"user-42\", didit.MonitoringEventsRetrieveSubjectTimelineParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.monitoringEvents().retrieveSubjectTimeline(\"user-42\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->retrieveSubjectTimeline('user-42') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.monitoring_events.retrieve_subject_timeline(\"user-42\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.MonitoringEvents.RetrieveSubjectTimelineAsync(\"user-42\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "该主体的一页事件。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitoringEventPage" }, "examples": { "Individual timeline": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "event_uuid": "11111111-2222-3333-4444-555555555555", "event_id": "chargeback-2026-10-16-000318", "event_category": "dispute", "action_type": "chargeback_opened", "occurred_at": "2026-10-16T14:02:11Z", "received_at": "2026-10-16T14:02:12.418230Z", "status": "IN_REVIEW", "score": 60, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": null, "device_fingerprint": null, "ip_address": null, "ip_country": null, "amount": "250.000000000000000000", "currency": "EUR", "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": "dep_735", "retention_class": "monetary_or_compliance", "rules_matched_count": 1, "correlation_pending": false, "is_droppable": false }, { "event_uuid": "22222222-3333-4444-5555-666666666666", "event_id": "login-2026-10-15-000912", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-15T08:30:00.120000Z", "received_at": "2026-10-15T08:30:00.734512Z", "status": "ACCEPTED", "score": 0, "subject_vendor_data": "user-42", "subject_entity_type": "individual", "subject_uuid": "66666666-7777-8888-9999-000000000000", "counterparty_vendor_data": null, "session_id": "web-session-abc", "device_fingerprint": "fp-a8c1", "ip_address": "203.0.113.42", "ip_country": "ES", "amount": null, "currency": null, "game_id": null, "round_id": null, "bonus_id": null, "affiliate_code": null, "payment_reference_id": null, "retention_class": "standard", "rules_matched_count": 0, "correlation_pending": false, "is_droppable": true } ] } }, "No events": { "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "400": { "description": "`limit` 或 `offset` 大于 1000000。响应体是包含一条消息的 JSON 数组。非数字或非正数的 `limit` 会回退到默认值 50，而不是失败。", "content": { "application/json": { "examples": { "limit too large": { "summary": "limit 超过 1000000", "value": [ "limit must not exceed 1000000." ] }, "offset too large": { "summary": "offset 超过 1000000", "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: read` 权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP 白名单之外的请求。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥的 `GET` 请求共享每分钟 600 次的配额。请等待 `Retry-After` 秒，然后重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/enrichment-metrics/": { "get": { "summary": "获取事件丰富化指标", "description": "返回您的应用在指定时间段内的事件摄入和 IP 信息丰富计数器，汇总所有通道（服务器、批处理和设备），以便您可以监控事件量并确认每个唯一地址的信息丰富操作仅解析一次，而不是针对每个事件解析一次。该时间段涵盖今天加上之前的 `days` 天，按 UTC 日历日期计算。当分母为零时，这三个比率为 null。限定作用域的 API 密钥需要 `transactions: read`。请参阅 [IP 信息丰富](https://docs.didit.me/zh/transaction-monitoring/events#ip-丰富信息)。", "operationId": "get_monitoring_event_enrichment_metrics", "x-didit-sdk": { "resource": "monitoring_events", "method": "retrieve_enrichment_metrics", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "days", "in": "query", "required": false, "description": "周期长度（天）。默认值为 30；值会被限制在 1 到 365 之间，非整数值将回退到 30。实际应用的值作为 `period_days` 返回。", "schema": { "type": "integer", "default": 30, "minimum": 1, "maximum": 365 }, "example": 30 } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/events/enrichment-metrics/?days=30' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.monitoring_events.retrieve_enrichment_metrics()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.monitoringEvents.retrieveEnrichmentMetrics();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.MonitoringEvents.RetrieveEnrichmentMetrics(ctx, didit.MonitoringEventsRetrieveEnrichmentMetricsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.monitoringEvents().retrieveEnrichmentMetrics();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->retrieveEnrichmentMetrics();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.monitoring_events.retrieve_enrichment_metrics\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.MonitoringEvents.RetrieveEnrichmentMetricsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "该时间段内的计数器和比率。", "content": { "application/json": { "schema": { "type": "object", "required": [ "events_ingested", "events_rejected", "enrichment_lookups", "enrichment_cache_hits", "enrichment_provider_calls", "enrichment_skipped_low_value", "unique_ips_seen", "period_days", "cache_hit_rate", "unique_ip_ratio", "provider_calls_per_1k_events" ], "properties": { "events_ingested": { "type": "integer", "description": "已存储新事件。幂等重放不计数。" }, "events_rejected": { "type": "integer", "description": "批量请求（服务端通道和设备通道）中被拒绝的项目。被拒绝的单事件请求不计入在内。" }, "enrichment_lookups": { "type": "integer", "description": "已解析公网 IP 地址的事件，数据来自缓存或最新获取。" }, "enrichment_cache_hits": { "type": "integer", "description": "从缓存中直接返回的查询。" }, "enrichment_provider_calls": { "type": "integer", "description": "需要对地址进行全新解析的查询。" }, "enrichment_skipped_low_value": { "type": "integer", "description": "其地址尚属未知的低价值遥测事件。它们本身绝不会触发全新解析。" }, "unique_ips_seen": { "type": "integer", "description": "需要重新解析的地址。" }, "period_days": { "type": "integer", "description": "限制范围后应用的 `days` 值。" }, "cache_hit_rate": { "type": "number", "nullable": true, "description": "`enrichment_cache_hits / enrichment_lookups`，四舍五入保留 4 位小数。没有查询时为 Null。" }, "unique_ip_ratio": { "type": "number", "nullable": true, "description": "`unique_ips_seen / events_ingested`，保留 4 位小数。未摄取任何事件时为 null。" }, "provider_calls_per_1k_events": { "type": "number", "nullable": true, "description": "每 1000 个摄入事件的新增解析数，四舍五入保留 2 位小数。未摄入事件时为 null。" } } }, "examples": { "Last 30 days": { "value": { "events_ingested": 128450, "events_rejected": 214, "enrichment_lookups": 41230, "enrichment_cache_hits": 40118, "enrichment_provider_calls": 1112, "enrichment_skipped_low_value": 74320, "unique_ips_seen": 1112, "period_days": 30, "cache_hit_rate": 0.973, "unique_ip_ratio": 0.0087, "provider_calls_per_1k_events": 8.66 } }, "No events yet": { "value": { "events_ingested": 0, "events_rejected": 0, "enrichment_lookups": 0, "enrichment_cache_hits": 0, "enrichment_provider_calls": 0, "enrichment_skipped_low_value": 0, "unique_ips_seen": 0, "period_days": 30, "cache_hit_rate": null, "unique_ip_ratio": null, "provider_calls_per_1k_events": null } } } } } }, "401": { "description": "作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: read` 权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP 白名单之外的请求。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥的 `GET` 请求共享每分钟 600 次的配额。请等待 `Retry-After` 秒，然后重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/events/{event_uuid}/delete/": { "delete": { "summary": "删除监控事件", "description": "永久删除单个监控事件及其规则运行记录、备注和标签关联，例如错误发送的事件。返回 `204` 后，该事件将从所有读取操作中消失（检索返回 `404`，且不再出现在列表或主体时间线中），此删除操作不可逆，并且其 `event_id` 可重新用于新事件。不受影响的内容包括：事件解析到的用户或企业、规则开启的案件、规则添加的名单条目，以及已应用于其他事件的评分和状态。要抹除关于个人或企业的所有内容，请改为删除该用户或企业，这也会一并删除其事件。限定作用域的 API 密钥需要 `transactions: write`。", "operationId": "delete_monitoring_event", "x-didit-sdk": { "resource": "monitoring_events", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Monitoring Events" ], "parameters": [ { "name": "event_uuid", "in": "path", "required": true, "description": "事件的 Didit 标识符（创建、批量、列表或时间线响应中的 `event_uuid`），而非您自己的 `event_id`。", "schema": { "type": "string", "format": "uuid" }, "example": "11111111-2222-3333-4444-555555555555" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE 'https://verification.didit.me/v3/events/11111111-2222-3333-4444-555555555555/delete/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.monitoring_events.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.monitoringEvents.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.MonitoringEvents.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.monitoringEvents().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "monitoringEvents->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.monitoring_events.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.MonitoringEvents.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "事件已删除。无响应体。" }, "401": { "description": "作用域 API 密钥已过期。仅过期的密钥会收到 `401`；缺失或无效的密钥会收到 `403`。", "content": { "application/json": { "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少 `x-api-key`（错误、已撤销或已过期的密钥会返回 `401`）、无 `transactions: write` 权限的作用域密钥、仅限于某些工作流或已通过会话的密钥（此类密钥绝无法访问交易监控数据），或来自密钥 IP 白名单之外的请求。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without access": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "IP not allowed": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "应用中不存在具有此 `event_uuid` 的事件：从未存储、已被删除，或属于另一个应用。非 UUID 的路径段与路由不匹配，也会返回 `404`。", "content": { "application/json": { "examples": { "Not found": { "value": { "detail": "No MonitoringEvent matches the given query." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥的写入请求（`POST`、`PATCH`、`DELETE`）共享每分钟 300 次的配额。请等待 `Retry-After` 秒，然后重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } }, "content": { "application/json": { "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/kyb/parties/{partyUuid}/regenerate/": { "post": { "summary": "重新生成关键人员方的 KYC 会话", "description": "在企业验证（KYB）会话的关键人员关联方先前的个人 KYC 会话被删除或在该人员开始之前已过期后，为其赋予一个新的个人 KYC 会话，以便重新完成关键人员检查；无需发送请求体。当该关联方的 KYC 会话已被删除（`kyc_session_deleted: true`）或在该人员开始之前已过期（`Expired`，从未开始）时有效。仍在进行中或以任何其他状态结束（`Approved`、`Declined`、`In Review`、`Abandoned` 等）的会话将返回 `409`，除非它已被删除。从未拥有过会话的关联方或企业关联方始终返回 `409`。Didit 会使用验证该关联方时所用的工作流（其最新发布版本）创建新的托管 KYC 会话，若该工作流不再可知，则使用您的关键人员设置分配给该关联方角色的工作流，因此其链接的有效时长即为该 KYC 工作流的会话过期时间；如果有电子邮箱记录，Didit 会通过电子邮件将链接发送给该关联方，清除 `is_skipped`，并重新计算关键人员检查及企业会话状态。随后，Didit 会针对企业会话发送触发器为 `console_key_people_regenerate` 的 `data.updated` [Webhook](https://docs.didit.me/zh/integration/webhooks)；若要豁免该关联方，请改用 `PATCH /v3/session/{sessionId}/kyb/parties/{partyUuid}/`。作用域限制的 API 密钥需要 `decisions: write` 权限，若缺少 `sessions: write` 权限，其接收到的 `kyc_session_url` 将为 `null`。即使该人员已经开始或完成了验证，已被删除的会话仍符合条件。导入的会话不会因过期而符合条件；它们必须已被删除。", "operationId": "post_v3_session_kyb_party_regenerate", "x-didit-sdk": { "resource": "sessions", "method": "regenerate_kyb_party", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "父企业验证（KYB）会话的 UUID。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "partyUuid", "in": "path", "required": true, "description": "关键人员主体的 UUID（企业会话决策上的 `key_people_checks[].submitted.parties[].uuid`）。必须属于 `sessionId` 所引用的会话。", "schema": { "type": "string", "format": "uuid", "example": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/session/33333333-4444-5555-6666-777777777777/kyb/parties/0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41/regenerate/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.regenerate_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.regenerateKybParty(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.RegenerateKYBParty(ctx, \"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().regenerateKybParty(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->regenerateKybParty('33333333-4444-5555-6666-777777777777', '0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.regenerate_kyb_party(\n \"33333333-4444-5555-6666-777777777777\",\n \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.RegenerateKybPartyAsync(\"33333333-4444-5555-6666-777777777777\", \"0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已创建新的 KYC 会话。返回包含新子会话的更新后当事方，该子会话将在其 KYC 工作流的会话过期时间后过期。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBKeyPeopleParty" }, "example": { "uuid": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41", "entity_type": "person", "source": "USER", "name": "Jane Smith", "first_name": "Jane", "last_name": "Smith", "company_name": null, "registration_number": null, "email": "user@example.com", "nationality": "GB", "phone_number": null, "date_of_birth": "1980-05-04", "position": "Director", "custom_fields": {}, "is_active": true, "is_skipped": false, "requires_verification": true, "roles": [ { "role": "director", "ownership_percent": null, "voting_percent": null } ], "kyc_session_id": "55555555-6666-7777-8888-999999999999", "kyc_session_status": "Not Started", "kyc_session_url": "https://verify.didit.me/session/abc123def456", "kyc_session_deleted": false, "kyb_sub_session_id": null, "kyb_sub_session_status": null, "kyb_sub_session_url": null, "kyb_sub_session_deleted": false, "verification_workflow_type": "kyc", "verification_workflow_id": "12121212-3434-5656-7878-909090909090", "verification_workflow_label": "Key People KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Not Finished" }, { "feature": "LIVENESS", "status": "Not Finished" }, { "feature": "AML", "status": "Not Finished" } ], "didit_internal_id": null } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除或超出了限定作用域密钥的限制；您的应用中不存在具有此 UUID 的主体；或者该主体属于另一个会话。每种情况都有其独立的 `detail`。会话查找在凭证检查之前执行，因此即使没有有效密钥，未知的 `sessionId` 也会返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "summary": "不存在具有此 ID 的会话，或该会话已被删除", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "会话超出了限定作用域密钥的工作流或仅限已通过状态的限制", "value": { "detail": "Session not found." } }, "Unknown party": { "summary": "您的应用中没有具有此 UUID 的主体", "value": { "detail": "No BusinessParty matches the given query." } }, "Party of another session": { "summary": "partyUuid 存在，但属于其他会话", "value": { "detail": "Party does not belong to the given session." } } } } } }, "409": { "description": "该主体没有可供替换的有效 KYC 会话。除非已被删除，否则仍在进行中或以其他状态（`Approved`、`Declined`、`In Review`、`Abandoned`……）结束的会话均无法重新生成。从未有过会话的主体或企业主体同样会返回 `409`。有效会话是指在该人员启动前已被删除或已过期的会话。即使该人员已经开始或完成验证，已删除的会话仍然符合条件。导入的会话不能仅通过过期来获得资格；它们必须已被删除。根据 `code` 进行分支处理。", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" }, "code": { "type": "string", "enum": [ "kyb_party_kyc_session_not_deleted" ], "description": "稳定的机器可读错误代码。" } } }, "example": { "detail": "This party's KYC session is still live (it has neither been deleted nor expired without starting), so it cannot be regenerated.", "code": "kyb_party_kyc_session_not_deleted" } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟 300 次写入（POST、PATCH、DELETE）请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 响应头显示了额度。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/{transaction_id}/notes/": { "get": { "summary": "列出交易备注", "description": "列出单笔受监控交易的备注，按最新优先排序（`created_at` 降序排列）：包括您通过 API 添加的备注、审核员在控制台中添加的备注和状态变更，以及 Didit 自动添加的备注（规则的 `add_note` 操作，或创建用户操作验证会话时出现的问题），这些备注带有 `actor_name` 为 `Rule Engine`。`metadata` 可用于区分不同类型的备注。\n\n通过 `limit` 和 `offset` 进行分页。`count` 在 100 以内是精确的，超过 100 则上限显示为 100，因此请持续追踪 `next` 直至其为 `null`，而不要根据 `count` 计算页数。这是一个无副作用的读取操作。\n\n限定作用域的 API 密钥需要具备 `transactions: read` 权限；限制于某些工作流或已通过会话的密钥无法调用此 endpoint。审核员可在[交易详情](https://docs.didit.me/zh/transaction-monitoring/console#交易详情)页面的 **Notes** 下查看相同的列表。", "operationId": "list_transaction_notes", "x-didit-sdk": { "resource": "transactions.notes", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Didit 交易 UUID：由 `POST /v3/transactions/` 和 `GET /v3/transactions/` 返回的 `uuid`。不接受您自己的 `txn_id`。", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "每页备注数量。默认为 50。非正整数值将回退为 50；大于 1000000 的值将返回 `400`。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "要返回的第一条备注的从零开始的位置。建议跟随 `next`。非整数值将回退为 0；大于 1000000 的值将返回 `400`。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.notes.list(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.notes.list(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.Notes.ListAutoPaging(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsNotesListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().notes().list(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->notes->list('abcdef12-3456-7890-abcd-ef1234567890') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.notes.list(\"abcdef12-3456-7890-abcd-ef1234567890\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.Notes.ListAsync(\"abcdef12-3456-7890-abcd-ef1234567890\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "一页备注，按最新优先排序。", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "该交易的备注数量：100 以内为准确数值，超过 100 时封顶显示为 100。请依据 `next` 进行翻页，而不是据此计算总页数。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionNote" } } } }, "examples": { "API, Console and rule notes": { "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "c1111111-2222-4333-8444-555555555555", "note": "Customer confirmed the withdrawal by phone.", "actor_email": null, "actor_name": null, "metadata": { "mentioned_emails": [ "analyst@example.com" ] }, "created_at": "2026-10-16T10:05:12.481203Z" }, { "uuid": "c2222222-3333-4444-8555-666666666666", "note": "Status changed from IN_REVIEW to APPROVED. Reason: Source of funds verified", "actor_email": "reviewer@example.com", "actor_name": "Alex Reviewer", "metadata": { "type": "status_change", "previous_status": "IN_REVIEW", "new_status": "APPROVED", "reason_code": "SOF_VERIFIED", "reason_label": "Source of funds verified" }, "created_at": "2026-10-15T17:22:40.103911Z" }, { "uuid": "c3333333-4444-4555-8666-777777777777", "note": "Large withdrawal to a new wallet: check the source of funds.", "actor_email": null, "actor_name": "Rule Engine", "metadata": { "rule_uuid": "d1111111-2222-4333-8444-555555555555", "source": "rule_action" }, "created_at": "2026-10-15T08:42:12.004518Z" } ] } }, "No notes yet": { "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "400": { "description": "`limit` 或 `offset` 超过 1000000。响应体是包含消息的 JSON 数组，而非对象。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "Limit too large": { "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "API 密钥已过期。仅创建时设置了到期日期的密钥才会过期；超过该日期后，使用它的每次请求都会返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "请求不被允许。缺失密钥将返回常规错误信息；错误、已撤销或已过期的密钥将收到 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without transactions read": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "应用中不存在具有此 UUID 的交易（从未创建、已删除或属于另一个应用）。非 UUID 格式的 `transaction_id` 不会到达 API：它将返回 `404` HTML 页面，而不是此 JSON 正文。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "使用此 API 密钥的 GET 请求每分钟超过 600 次。请等待 `Retry-After` 中指定的秒数，然后再重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "距离当前一分钟窗口重置的秒数。", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "在此预算中每分钟允许的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "窗口重置的 Unix 时间。", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] }, "post": { "summary": "创建交易备注", "description": "向受监控交易的审核时间线添加纯文本备注，控制台审核员可以在此处查看。备注属于上下文信息，而非决策：交易的 `status`、`score` 和警报均不会改变，不会发送 Webhook，也不会产生任何计费。该交易的 `activities` 将新增一条 `TRANSACTION_NOTE_ADDED` 记录。\n\n使用 API 密钥创建的备注没有作者：`actor_email` 和 `actor_name` 为 `null`，因此如果需要，请在文本中注明作者。`mentioned_emails` 中的每个地址必须属于您组织的成员，否则整个请求将失败并返回 `400`；提及的邮箱将以小写形式去重存储，且此 endpoint 不会向被提及的成员发送通知。\n\n每次调用都会创建一条新备注，因此重试超时的请求可能会导致添加两次：在重试前请先列出备注。没有用于编辑或删除备注的 API endpoint。具有作用域限定的 API 密钥需要具备 `transactions: write` 权限；仅限于某些工作流或已通过审核的会话的密钥无法调用此 endpoint。", "operationId": "create_transaction_note", "x-didit-sdk": { "resource": "transactions.notes", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Didit 交易 UUID：由 `POST /v3/transactions/` 和 `GET /v3/transactions/` 返回的 `uuid`。不接受您自己的 `txn_id`。", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "note" ], "properties": { "note": { "type": "string", "minLength": 1, "description": "纯文本备注。首尾空白字符会被修剪，空白备注会被拒绝。无长度限制。" }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "default": [], "description": "要提及的组织成员的邮箱。每个邮箱必须是有效的组织成员邮箱。" } } }, "examples": { "Note with a mention": { "value": { "note": "Customer confirmed the withdrawal by phone.", "mentioned_emails": [ "analyst@example.com" ] } }, "Plain note": { "value": { "note": "Source of funds document requested by email." } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/notes/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"note\": \"Customer confirmed the withdrawal by phone.\", \"mentioned_emails\": [\"analyst@example.com\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.transactions.notes.create(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n note=\"Customer confirmed the withdrawal by phone.\",\n mentioned_emails=[\"analyst@example.com\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.transactions.notes.create(\"abcdef12-3456-7890-abcd-ef1234567890\", {\n note: \"Customer confirmed the withdrawal by phone.\",\n mentioned_emails: [\"analyst@example.com\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Transactions.Notes.Create(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsNotesCreateParams{\n\tNote: \"Customer confirmed the withdrawal by phone.\",\n\tMentionedEmails: didit.Some([]string{\"analyst@example.com\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TransactionsNotesCreateParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.transactions().notes().create(\"abcdef12-3456-7890-abcd-ef1234567890\", TransactionsNotesCreateParams.builder()\n .note(\"Customer confirmed the withdrawal by phone.\")\n .mentionedEmails(List.of(\"analyst@example.com\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "transactions->notes->create('abcdef12-3456-7890-abcd-ef1234567890', [\n 'note' => 'Customer confirmed the withdrawal by phone.',\n 'mentioned_emails' => ['analyst@example.com'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.transactions.notes.create(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n note: \"Customer confirmed the withdrawal by phone.\",\n mentioned_emails: [\"analyst@example.com\"]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Transactions.Notes.CreateAsync(\"abcdef12-3456-7890-abcd-ef1234567890\", new TransactionsNotesCreateParams\n{\n Note = \"Customer confirmed the withdrawal by phone.\",\n MentionedEmails = new string[] { \"analyst@example.com\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "备注已创建。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionNote" }, "examples": { "Created": { "value": { "uuid": "c1111111-2222-4333-8444-555555555555", "note": "Customer confirmed the withdrawal by phone.", "actor_email": null, "actor_name": null, "metadata": { "mentioned_emails": [ "analyst@example.com" ] }, "created_at": "2026-10-16T10:05:12.481203Z" } } } } } }, "400": { "description": "请求体无效：`note` 缺失、为 null 或为空白；`mentioned_emails` 中存在无效地址（按列表位置索引错误）；或提及的地址不是您组织的成员。未创建任何内容。", "content": { "application/json": { "schema": { "type": "object", "description": "以字段名作为键的字段错误。", "additionalProperties": {} }, "examples": { "Missing note": { "value": { "note": [ "This field is required." ] } }, "Blank note": { "value": { "note": [ "This field may not be blank." ] } }, "Invalid email": { "value": { "mentioned_emails": { "0": [ "Enter a valid email address." ] } } }, "Not an organization member": { "value": { "mentioned_emails": [ "Mentioned users must belong to this organization and have access to this application." ] } } } } } }, "401": { "description": "API 密钥已过期。仅创建时设置了到期日期的密钥才会过期；超过该日期后，使用它的每次请求都会返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "请求不被允许。缺失密钥将返回常规错误信息；错误、已撤销或已过期的密钥将收到 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without transactions write": { "value": { "detail": "This API key has no write access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "应用中不存在具有此 UUID 的交易（从未创建、已删除或属于另一个应用）。非 UUID 格式的 `transaction_id` 不会到达 API：它将返回 `404` HTML 页面，而不是此 JSON 正文。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "使用此 API 密钥的写入请求每分钟超过 300 次。请等待 `Retry-After` 中指定的秒数，然后再重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "距离当前一分钟窗口重置的秒数。", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "在此预算中每分钟允许的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "窗口重置的 Unix 时间。", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/transactions/{transaction_id}/related/": { "get": { "summary": "列出关联交易", "description": "列出您应用中涉及与此交易相同人员或公司的其他交易。当某笔交易的任何参与方（无论担任任何角色）与当前交易的某个参与方具有相同的 `vendor_data` 时，即视为关联交易。该交易本身绝不会被返回，且没有 `vendor_data` 的参与方会被忽略：如果当前交易的参与方均无此字段，结果始终为空。\n\n结果采用 `GET /v3/transactions/` 的摘要格式，最新的排在最前（先按 `txn_date` 排序，再按 `created_at` 排序）。使用 `limit` 和 `offset` 进行分页；`count` 在 100 以内是精确的，超过 100 则上限显示为 100，因此请持续请求 `next`，直到其为 `null`。\n\n限定作用域的 API 密钥需要具备 `transactions: read` 权限；受限于某些工作流或已通过会话的密钥无法调用此 endpoint。请在每笔[交易](https://docs.didit.me/zh/transaction-monitoring/transactions#主体与交易对手)中为同一个人或公司发送相同的 `vendor_data`，以确保此列表完整。", "operationId": "list_related_transactions", "x-didit-sdk": { "resource": "transactions", "method": "list_related", "auth": "api_key", "server": true }, "tags": [ "Transactions" ], "parameters": [ { "name": "transaction_id", "in": "path", "required": true, "description": "Didit 交易 UUID：由 `POST /v3/transactions/` 和 `GET /v3/transactions/` 返回的 `uuid`。不接受您自己的 `txn_id`。", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000 }, "description": "每页交易数量。默认为 50。非正整数值将回退为 50；大于 1000000 的值将返回 `400`。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000 }, "description": "要返回的第一笔交易的从零开始的位置。建议跟随 `next`。非整数值将回退为 0；大于 1000000 的值将返回 `400`。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/transactions/abcdef12-3456-7890-abcd-ef1234567890/related/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.transactions.list_related(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.transactions.listRelated(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Transactions.ListRelatedAutoPaging(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\", didit.TransactionsListRelatedParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.transactions().listRelated(\"abcdef12-3456-7890-abcd-ef1234567890\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "transactions->listRelated('abcdef12-3456-7890-abcd-ef1234567890') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.transactions.list_related(\"abcdef12-3456-7890-abcd-ef1234567890\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Transactions.ListRelatedAsync(\"abcdef12-3456-7890-abcd-ef1234567890\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "一页关联交易，按最新优先排序。", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "关联交易的数量：100 以内为准确数值，超过 100 时封顶显示为 100。请依据 `next` 进行翻页，而不是据此计算总页数。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的绝对 URL，最后一页则为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的绝对 URL，第一页则为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionSummary" } } } }, "examples": { "One related transaction": { "value": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "abcdef99-3456-4890-abcd-ef1234567890", "transaction_number": 4087, "txn_id": "your-txn-2026-10-02-017", "transaction_type": "finance", "action_type": "deposit", "status": "APPROVED", "source": "LIVE", "direction": "INBOUND", "amount": "250", "currency": "EUR", "currency_type": "fiat", "preferred_currency_amount": "270.08", "preferred_currency_code": "USD", "payment_details": "Card top-up", "txn_date": "2026-10-02T14:10:00Z", "created_at": "2026-10-02T14:10:03.512244Z", "score": 12, "severity": "LOW", "decision_reason_code": null, "decision_reason_label": null, "tags": [], "subject_name": "Maria Garcia", "subject_vendor_data": "user-12345", "subject_type": "user", "subject_uuid": "e1111111-2222-4333-8444-555555555555", "counterparty_name": null, "counterparty_vendor_data": null, "counterparty_country": null, "subject_country": "ESP", "assigned_to_name": null, "travel_rule_status": null, "application_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "application_name": "Production app", "organization_id": "11111111-2222-3333-4444-555555555555", "organization_name": "Example Org" } ] } }, "No party has vendor_data": { "value": { "count": 0, "next": null, "previous": null, "results": [] } } } } } }, "400": { "description": "`limit` 或 `offset` 超过 1000000。响应体是包含消息的 JSON 数组，而非对象。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "examples": { "Limit too large": { "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "value": [ "offset must not exceed 1000000." ] } } } } }, "401": { "description": "API 密钥已过期。仅创建时设置了到期日期的密钥才会过期；超过该日期后，使用它的每次请求都会返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "请求不被允许。缺失密钥将返回常规错误信息；错误、已撤销或已过期的密钥将收到 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without transactions read": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "应用中不存在具有此 UUID 的交易（从未创建、已删除或属于另一个应用）。非 UUID 格式的 `transaction_id` 不会到达 API：它将返回 `404` HTML 页面，而不是此 JSON 正文。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "使用此 API 密钥的 GET 请求每分钟超过 600 次。请等待 `Retry-After` 中指定的秒数，然后再重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "距离当前一分钟窗口重置的秒数。", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "在此预算中每分钟允许的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "窗口重置的 Unix 时间。", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/businesses/{business_session_id}/pdf/": { "get": { "summary": "下载企业会话 PDF 报告", "description": "生成单个企业验证（KYB）会话的 PDF 报告：包含公司登记数据、关键人员和实际受益人、证件、AML 结果及其他工作流功能，以及该会话的标签和审核活动。开启白标自定义后，报告将包含您的徽标和隐私政策 URL。响应体为 PDF 本身（`application/pdf`），而非 JSON。\n\n会话状态必须为 `Approved`、`Declined` 或 `In Review`；任何其他状态都会返回 `403`，因此请先等待 `status.updated` [Webhook](https://docs.didit.me/zh/integration/webhooks)。每次调用都会渲染报告且不计费，因此请存储该文件，避免重复获取。`GET /v3/session/{sessionId}/generate-pdf/` 仅凭会话 ID 即可渲染同类报告。\n\nPDF 报告属于媒体资源：受限范围的 API 密钥需要 `businesses: read` 和 `media: read` 权限，而限制于某些工作流或仅限已通过会话的密钥无法调用该接口。", "operationId": "get_business_session_pdf", "x-didit-sdk": { "resource": "businesses", "method": "generate_session_pdf", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Businesses" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。必须是该 API 密钥所属的应用：在任何其他应用上使用该密钥都会返回 `403`。", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "business_session_id", "in": "path", "required": true, "description": "企业验证（KYB）会话的 `session_id`，与创建会话时返回的一致。属于其他应用的会话将返回 `404`。", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl --fail -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/businesses/22222222-3333-4444-5555-666666666666/pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output business_report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\ncontent = client.businesses.generate_session_pdf(\n \"22222222-3333-4444-5555-666666666666\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst content = await didit.businesses.generateSessionPdf(\"22222222-3333-4444-5555-666666666666\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresp, err := client.Businesses.GenerateSessionPDF(ctx, \"22222222-3333-4444-5555-666666666666\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.businesses().generateSessionPdf(\"22222222-3333-4444-5555-666666666666\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "businesses->generateSessionPdf('22222222-3333-4444-5555-666666666666');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ncontent = didit.businesses.generate_session_pdf(\"22222222-3333-4444-5555-666666666666\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar content = await client.Businesses.GenerateSessionPdfAsync(\"22222222-3333-4444-5555-666666666666\");\nawait content.SaveToAsync(\"download.pdf\");" } ], "responses": { "200": { "description": "渲染生成的 PDF，直接以二进制 `application/pdf` 形式返回。", "headers": { "Content-Disposition": { "description": "始终为 `attachment; filename=business_{business_session_id}.pdf`。", "schema": { "type": "string", "example": "attachment; filename=business_22222222-3333-4444-5555-666666666666.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "API 密钥已过期。仅创建时设置了到期日期的密钥才会过期；超过该日期后，使用它的每次请求都会返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "请求不被允许或会话未完成。请查看 `detail`：会话状态不是 `Approved`、`Declined` 或 `In Review`；缺失 API 密钥（错误、已撤销或已过期的密钥将收到 `401`）；`application_id` 不属于该密钥对应的应用；权限受限的密钥未包含 `media: read` 或 `businesses: read` 权限；密钥受限于工作流或已通过的会话；或者请求来自该密钥 IP 名单之外。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Session not finished": { "value": { "detail": "You can only generate a PDF for sessions in review, declined or approved." } }, "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without media read": { "value": { "detail": "This API key has no read access to media." } }, "Scoped key without businesses read": { "value": { "detail": "This API key has no read access to companies." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "应用中不存在具有此 ID 的企业会话（从未创建、已删除，或归另一个应用所有）。非 UUID 值将返回 `404` HTML 页面，而不是此 JSON 响应正文。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "Business session not found." } } } } } }, "429": { "description": "使用此 API 密钥的 GET 请求每分钟超过 600 次。请等待 `Retry-After` 中指定的秒数，然后再重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "距离当前一分钟窗口重置的秒数。", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "在此预算中每分钟允许的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "窗口重置的 Unix 时间。", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/{transaction_uuid}/pdf/": { "get": { "summary": "下载交易 PDF 报告", "description": "将一笔被监控的交易渲染为 PDF 报告：概览与结论、当事方与支付方式、自定义属性、警报与规则运行情况、筛查与 Travel Rule 结果、网络摘要、费用明细、最多 50 笔相关交易以及最近 20 条活动条目。响应体为 PDF 本身（`application/pdf`），而非 JSON。\n\n报告在每次调用时均根据交易的当前数据进行渲染，因此在状态更改后请重新请求。不会存储任何内容，也不会计费。渲染可能需要几秒钟，因此请设置宽松的客户端超时时间。\n\n该 endpoint 位于应用作用域路径下：在 URL 中填入您的组织 ID 以及您的 API 密钥所属的应用 ID（[查找您的组织 ID](https://docs.didit.me/zh/getting-started/api-authentication#获取您的组织-id)）。PDF 报告算作媒体资源：有作用域限制的 API 密钥需要 `media: read` 和 `transactions: read` 权限，且仅限于某些工作流或已通过会话的密钥无法调用该接口。", "operationId": "get_transaction_pdf", "x-didit-sdk": { "resource": "transactions", "method": "generate_pdf", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Transactions" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。必须是该 API 密钥所属的应用：在任何其他应用上使用该密钥都会返回 `403`。", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "transaction_uuid", "in": "path", "required": true, "description": "Didit 交易 UUID：由 `POST /v3/transactions/` 和 `GET /v3/transactions/` 返回的 `uuid`。不接受您自己的 `txn_id`。", "schema": { "type": "string", "format": "uuid" }, "example": "abcdef12-3456-7890-abcd-ef1234567890" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl --fail -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/abcdef12-3456-7890-abcd-ef1234567890/pdf/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n --output transaction_report.pdf" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\ncontent = client.transactions.generate_pdf(\n \"abcdef12-3456-7890-abcd-ef1234567890\",\n)\nwith open(\"download.pdf\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst content = await didit.transactions.generatePdf(\"abcdef12-3456-7890-abcd-ef1234567890\");\nawait writeFile(\"download.pdf\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresp, err := client.Transactions.GeneratePDF(ctx, \"abcdef12-3456-7890-abcd-ef1234567890\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.pdf\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.transactions().generatePdf(\"abcdef12-3456-7890-abcd-ef1234567890\")\n .writeTo(Path.of(\"download.pdf\"));" }, { "lang": "php", "label": "PHP", "source": "transactions->generatePdf('abcdef12-3456-7890-abcd-ef1234567890');\n$content->saveTo('download.pdf');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ncontent = didit.transactions.generate_pdf(\"abcdef12-3456-7890-abcd-ef1234567890\")\nFile.binwrite(\"download.pdf\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar content = await client.Transactions.GeneratePdfAsync(\"abcdef12-3456-7890-abcd-ef1234567890\");\nawait content.SaveToAsync(\"download.pdf\");" } ], "responses": { "200": { "description": "渲染生成的 PDF，直接以二进制 `application/pdf` 形式返回。", "headers": { "Content-Disposition": { "description": "始终为 `attachment; filename=transaction_{transaction_uuid}.pdf`。", "schema": { "type": "string", "example": "attachment; filename=transaction_abcdef12-3456-7890-abcd-ef1234567890.pdf" } } }, "content": { "application/pdf": { "schema": { "type": "string", "format": "binary" } } } }, "401": { "description": "API 密钥已过期。仅创建时设置了到期日期的密钥才会过期；超过该日期后，使用它的每次请求都会返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。请查看 `detail`：缺失 API 密钥（错误、已撤销或已过期的密钥会收到 `401`）、非该密钥所属应用的 `application_id`、缺少 `media: read` 或 `transactions: read` 的限定作用域密钥、受限于工作流或已通过的会话的密钥，或来自密钥 IP 列表之外的请求。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without media read": { "value": { "detail": "This API key has no read access to media." } }, "Scoped key without transactions read": { "value": { "detail": "This API key has no read access to transactions." } }, "Key limited to workflows or approved sessions": { "value": { "detail": "This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "应用中不存在具有此 UUID 的交易（从未创建、已删除或属于另一个应用）。非 UUID 格式的 `transaction_uuid` 不会到达 API：它将返回 `404` HTML 页面，而不是此 JSON 正文。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Not found": { "value": { "detail": "No Transaction matches the given query." } } } } } }, "429": { "description": "使用此 API 密钥的 GET 请求每分钟超过 600 次。请等待 `Retry-After` 中指定的秒数，然后再重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "距离当前一分钟窗口重置的秒数。", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "在此预算中每分钟允许的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "窗口重置的 Unix 时间。", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/analytics/": { "get": { "summary": "获取应用分析数据", "description": "读取指定日期范围内 Business Console [分析仪表板](https://docs.didit.me/zh/console/analytics)背后的数据。如果不带 `scope` 和 `widget_keys`，响应将是用户验证（KYC）摘要（`ApplicationAnalyticsSummary`）：每日会话数、状态总计、转化率、等长前一时期的相同数据、位置、人口统计学数据、设备、工作流漏斗、活跃验证时间、重新提交、警告以及时间序列。如果带 `scope` 或 `widget_keys`，响应将是单个仪表板标签页的小组件数据（`ApplicationAnalyticsWidgetResponse`）：`kyc`、`kyb`、`transactions` 或 `home`。\n\n会话计数按会话创建日期（UTC）统计，并反映每个会话的当前状态。这些数据来自在后台刷新的每日汇总，因此最新活动可能需要稍等片刻才会显示。无效的工作流 ID 和版本将被忽略而非拒绝。不产生任何计费费用。\n\n只有拥有完全访问权限的 API 密钥才能调用此 endpoint：任何限定作用域的密钥无论拥有何种访问权限都会收到 `403`，其他应用的密钥同样如此。请参阅 [API 密钥](https://docs.didit.me/zh/console/api-keys)。", "operationId": "get_application_analytics", "x-didit-sdk": { "resource": "analytics", "method": "retrieve", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Analytics" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。必须是该 API 密钥所属的应用：在任何其他应用上使用该密钥都会返回 `403`。", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-10-01" }, "description": "范围的起始日期，格式为 `YYYY-MM-DD`，含当日（UTC）。须与 `end_date` 一同发送：若缺少任意一项，两者都将被忽略，且范围默认为今天之前的 30 天至今天。" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date", "example": "2026-10-15" }, "description": "范围的最后一天，`YYYY-MM-DD`，含（UTC）。未来日期按今天计。范围不得超过 730 天。" }, { "name": "scope", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "home", "kyc", "kyb", "transactions" ] }, "description": "要返回微件的仪表板标签页（不区分大小写）。与 `widget_keys` 一同省略时，返回 KYC 摘要。仅发送 `widget_keys` 默认为 `kyc`。`home` 接受任何 KYC、KYB 或交易微件，并默认采用应用已保存的主页布局。" }, { "name": "widget_keys", "in": "query", "required": false, "schema": { "type": "string", "example": "tx_count_total,tx_count_daily" }, "description": "以逗号分隔的小组件键，按此顺序返回。该范围不接受的键将被丢弃；若未剩下任何有效键，则使用该范围的默认值。KYC：`kyc_sessions_volume`、`kyc_warning_insights`、`kyc_id_locations`、`kyc_ip_locations`、`kyc_workflow_funnel`、`kyc_average_verification_time`、`kyc_conversion_rate`、`kyc_conversion_by_country`、`kyc_resubmission_insights`、`kyc_original_status_distribution`、`kyc_database_validation_coverage`、`kyc_database_validation_latency`、`kyc_demographics`、`kyc_device_details`。KYB：`kyb_sessions_volume`、`kyb_workflow_funnel`、`kyb_average_verification_time`、`kyb_ip_locations`、`kyb_business_country_distribution`、`kyb_warning_insights`、`kyb_conversion_rate`、`kyb_conversion_by_country`、`kyb_industry_breakdown`、`kyb_resubmission_insights`、`kyb_original_status_distribution`、`kyb_registry_coverage`、`kyb_registry_data_completeness`、`kyb_device_details`。交易：`tx_count_total`、`tx_count_daily`、`tx_volume_total_preferred_currency`、`tx_volume_daily_preferred_currency`、`tx_average_amount`、`tx_average_amount_daily`、`tx_transaction_category_breakdown`、`tx_action_type_breakdown`、`tx_status_volume_trend`、`tx_user_ip_or_country_distribution`、`tx_tag_breakdown`、`tx_top_rules_triggered`、`tx_team_member_performance`、`tx_score_histogram`。" }, { "name": "workflow_ids", "in": "query", "required": false, "schema": { "type": "string", "example": "33333333-4444-5555-6666-777777777777" }, "description": "以逗号分隔的工作流 ID 列表。将 KYC 摘要以及 KYC 和 KYB 小组件限制为这些工作流。非 UUID 的值将被忽略；若无有效值，则丢弃该过滤器。摘要还接受 `workflow_id`。" }, { "name": "versions", "in": "query", "required": false, "schema": { "type": "string", "example": "3,4" }, "description": "以逗号分隔的工作流版本号列表。仅与 `workflow_ids` 配合使用；非整数的值将被忽略。也接受 `version` 作为别名。" }, { "name": "branch_path_ids", "in": "query", "required": false, "schema": { "type": "string", "example": "default" }, "description": "以逗号分隔的分支路径 ID。仅与 `workflow_ids` 配合使用，且仅适用于 KYC 数据。目前仅记录 `default`（合并所有路径）的数据，因此任何其他值都会返回空数据。`branch_path_id` 可作为别名接受。" }, { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" }, "description": "仅限交易小部件：以逗号分隔的标签 UUID 或标签名称。" }, { "name": "transaction_type", "in": "query", "required": false, "schema": { "type": "string", "example": "finance" }, "description": "仅限交易小部件：以逗号分隔的交易类别。" }, { "name": "action_type", "in": "query", "required": false, "schema": { "type": "string", "example": "withdrawal" }, "description": "仅限交易小部件：以逗号分隔的操作类型（不区分大小写）。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/analytics/?start_date=2026-10-01&end_date=2026-10-15' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.analytics.retrieve()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.analytics.retrieve();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Analytics.Retrieve(ctx, didit.AnalyticsRetrieveParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.analytics().retrieve();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "analytics->retrieve();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.analytics.retrieve\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Analytics.RetrieveAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "KYC 摘要，或者当发送了 `scope` 或 `widget_keys` 时请求的微件。", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ApplicationAnalyticsSummary" }, { "$ref": "#/components/schemas/ApplicationAnalyticsWidgetResponse" } ] }, "examples": { "KYC summary": { "value": { "grouping_mode": "day", "data_points": [ { "rounded_date": "2026-10-14", "total": 12, "approved": 8, "declined": 1, "canceled": 1, "pending": 2, "in_review": 1, "expired": 1, "abandoned": 0, "in_progress": 1, "not_started": 0, "manually_approved": 1, "manually_declined": 0 }, { "rounded_date": "2026-10-15", "total": 10, "approved": 6, "declined": 2, "canceled": 0, "pending": 2, "in_review": 2, "expired": 0, "abandoned": 0, "in_progress": 0, "not_started": 0, "manually_approved": 0, "manually_declined": 1 } ], "request_breakdown": { "total_approved": 14, "total_in_review": 3, "total_declined": 3, "total_canceled": 1, "total_pending": 4, "total_expired": 1, "total_abandoned": 0, "total_in_progress": 1, "total_not_started": 0, "total_manually_approved": 1, "total_manually_declined": 1 }, "conversion_rate": 70.0, "location_stats": { "countries": [ { "session_count": 15, "country": "Spain", "country_code": "ES" }, { "session_count": 7, "country": "Portugal", "country_code": "PT" } ], "ip_countries": [ { "session_count": 15, "country": "Spain", "country_code": "ES" }, { "session_count": 7, "country": "Portugal", "country_code": "PT" } ], "id_countries": [ { "country": "Spain", "country_code": "ES", "session_count": 14 }, { "country": "Portugal", "country_code": "PT", "session_count": 6 } ], "conversion_by_country": [ { "country": "Spain", "country_code": "ES", "finished": 13, "approved": 10 }, { "country": "Portugal", "country_code": "PT", "finished": 6, "approved": 4 } ], "cities": [ { "session_count": 9, "location": "Madrid, Spain", "latitude": 40.4168, "longitude": -3.7038 } ] }, "demographic_stats": { "age_distribution": { "under_18": 0, "18_24": 5, "25_34": 8, "35_44": 4, "45_64": 2, "65_plus": 1 }, "gender_distribution": { "M": 11, "F": 9 } }, "device_details": { "device_models": [ { "device": "Apple", "count": 12 }, { "device": "Android", "count": 10 } ], "browsers": [ { "browser": "Safari", "count": 12 }, { "browser": "Chrome", "count": 10 } ], "operating_systems": [ { "os": "iOS", "count": 12 }, { "os": "Android", "count": 10 } ] }, "workflow_funnel_stats": { "33333333-4444-5555-6666-777777777777": { "total": 22, "steps": { "OCR": { "reached": 21 }, "LIVENESS": { "reached": 19 }, "FACE_MATCH": { "reached": 19 }, "AML": { "reached": 18 } } } }, "verification_time_stats": { "overall_avg_seconds": 64.0, "overall_count": 18, "per_feature": { "OCR": { "avg_seconds": 41.2, "total_seconds": 741.6, "count": 18 }, "LIVENESS": { "avg_seconds": 22.8, "total_seconds": 410.4, "count": 18 } }, "per_sub_step": { "OCR": { "front_id_photo": { "avg_seconds": 18.3, "total_seconds": 329.4, "count": 18 } } } }, "resubmission_stats": { "first_pass": 17, "second": 2, "third_plus": 1, "abandoned": 0 }, "warning_stats": { "ID_VERIFICATION": { "total": 21, "risks": { "DOCUMENT_EXPIRED": { "error": 1, "warning": 0, "information": 0 } } }, "LIVENESS": { "total": 19, "risks": { "LOW_LIVENESS_SCORE": { "error": 0, "warning": 2, "information": 0 } } } }, "original_status_stats": { "approved": 13, "in_review": 5, "declined": 2 }, "demographic_time_series": [ { "date": "2026-10-14", "age_distribution": { "under_18": 0, "18_24": 3, "25_34": 4, "35_44": 2, "45_64": 1, "65_plus": 0 }, "gender_distribution": { "M": 6, "F": 4 } }, { "date": "2026-10-15", "age_distribution": { "under_18": 0, "18_24": 2, "25_34": 4, "35_44": 2, "45_64": 1, "65_plus": 1 }, "gender_distribution": { "M": 5, "F": 5 } } ], "device_time_series": [ { "date": "2026-10-14", "devices": { "Apple": 7, "Android": 5 }, "browsers": { "Safari": 7, "Chrome": 5 }, "operating_systems": { "iOS": 7, "Android": 5 } }, { "date": "2026-10-15", "devices": { "Apple": 5, "Android": 5 }, "browsers": { "Safari": 5, "Chrome": 5 }, "operating_systems": { "iOS": 5, "Android": 5 } } ], "verification_time_time_series": [ { "date": "2026-10-14", "overall_avg": 66.1, "per_feature": { "OCR": 42.0, "LIVENESS": 24.1 } }, { "date": "2026-10-15", "overall_avg": 61.5, "per_feature": { "OCR": 40.2, "LIVENESS": 21.3 } } ], "resubmission_time_series": [ { "date": "2026-10-14", "first_pass": 9, "second": 1, "third_plus": 0, "abandoned": 0 }, { "date": "2026-10-15", "first_pass": 8, "second": 1, "third_plus": 1, "abandoned": 0 } ], "original_status_time_series": [ { "date": "2026-10-14", "approved": 7, "in_review": 3, "declined": 1 }, { "date": "2026-10-15", "approved": 6, "in_review": 2, "declined": 1 } ], "previous_data_points": [ { "rounded_date": "2026-10-12", "total": 9, "approved": 6, "declined": 1, "canceled": 1, "pending": 1 }, { "rounded_date": "2026-10-13", "total": 11, "approved": 7, "declined": 2, "canceled": 0, "pending": 2 } ], "previous_request_breakdown": { "total_approved": 13, "total_in_review": 2, "total_declined": 3, "total_canceled": 1, "total_pending": 3 } } }, "Transaction widgets": { "value": { "scope": "transactions", "available_widget_keys": [ "tx_count_total", "tx_count_daily", "tx_volume_total_preferred_currency", "tx_volume_daily_preferred_currency", "tx_average_amount", "tx_average_amount_daily", "tx_transaction_category_breakdown", "tx_action_type_breakdown", "tx_status_volume_trend", "tx_user_ip_or_country_distribution", "tx_tag_breakdown", "tx_top_rules_triggered", "tx_team_member_performance", "tx_score_histogram" ], "requested_widget_keys": [ "tx_count_total", "tx_count_daily" ], "widgets": { "tx_count_total": { "kind": "metric", "title": "Transaction count", "value": 42 }, "tx_count_daily": { "kind": "time_series", "title": "Transaction count", "items": [ { "date": "2026-10-14", "value": 20 }, { "date": "2026-10-15", "value": 22 } ], "previous_items": [ { "date": "2026-10-12", "value": 18 }, { "date": "2026-10-13", "value": 15 } ] } } } } } } } }, "400": { "description": "无效的日期范围或作用域。响应体是一个以出错参数为键、包含字符串消息的对象。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "string" } }, "examples": { "Bad date format": { "value": { "start_date": "Invalid date format. Use YYYY-MM-DD (e.g., 2024-01-15)." } }, "Start after end": { "value": { "start_date": "Start date must be before or equal to end date." } }, "Range too long": { "value": { "date_range": "Date range cannot exceed 730 days (2 years)." } }, "Unknown scope": { "value": { "scope": "Unsupported analytics scope." } } } } } }, "401": { "description": "API 密钥已过期。仅创建时设置了到期日期的密钥才会过期；超过该日期后，使用它的每次请求都会返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。请查看 `detail`：缺失 API 密钥（错误、已撤销或已过期的密钥会收到 `401`）、属于其他应用的密钥、任何限定作用域的密钥，或来自密钥 IP 列表之外的请求。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key": { "value": { "detail": "This API key has no access to this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "使用此 API 密钥的 GET 请求每分钟超过 600 次。请等待 `Retry-After` 中指定的秒数，然后再重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "距离当前一分钟窗口重置的秒数。", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "在此预算中每分钟允许的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "窗口重置的 Unix 时间。", "schema": { "type": "integer" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/organization/{organization_id}/application/{application_id}/analytics/today/": { "get": { "summary": "获取今日按小时统计的验证量", "operationId": "get_application_analytics_today", "x-didit-sdk": { "resource": "analytics", "method": "retrieve_today", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Analytics" ], "description": "今天的用户验证（KYC）会话，从 `tz` 中的本地午夜开始，按创建的本地小时计数，与一周前同一工作日的相同小时并列展示，并按每个会话当前的结果进行划分：已通过、审核中或已拒绝。这是 Business Console 首页的业务量卡片。\n\n`total` 为今天截至目前的总量。`previous_total_so_far` 仅统计对比日截至相同本地时间的数据，因此两者之间的变化对比了两个日期的相同时间段。今天尚未到来的小时为 `0`。发生夏令时时钟调整的日子有 23 或 25 个小时：缺失的小时保持为 `0`，重复的小时则包含这两个小时的数据。", "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。", "example": "11111111-2222-3333-4444-555555555555" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。必须是该 API 密钥所属的应用：在任何其他应用上使用该密钥都会返回 `403`。", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" }, { "name": "tz", "in": "query", "required": false, "schema": { "type": "string", "default": "UTC", "example": "Europe/Madrid" }, "description": "午夜即代表今天开始的 IANA 时区，例如 `Europe/Madrid` 或 `America/Mexico_City`。省略则默认为 UTC。" } ], "responses": { "200": { "description": "今天按本地小时划分的验证量、对比日的数据以及今天的结果。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplicationAnalyticsToday" }, "examples": { "Madrid, 14:00": { "value": { "time_zone": "Europe/Madrid", "date": "2026-10-30", "current_hour": 14, "previous_date": "2026-10-23", "hours": [ 3, 1, 0, 0, 1, 2, 4, 9, 14, 18, 21, 19, 22, 24, 27, 0, 0, 0, 0, 0, 0, 0, 0, 0 ], "previous_hours": [ 2, 1, 1, 0, 1, 3, 5, 8, 12, 16, 19, 18, 20, 22, 24, 26, 23, 19, 15, 12, 9, 7, 5, 3 ], "total": 165, "previous_total_so_far": 151, "outcomes": { "approved": 139, "in_review": 6, "declined": 18 } } } } } } }, "400": { "description": "未知的时区。响应体以参数为键，包含消息列表。", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "examples": { "Unknown time zone": { "value": { "tz": [ "Unknown time zone: Europe/Atlantis." ] } } } } } }, "401": { "description": "API 密钥已过期。仅创建时设置了到期日期的密钥才会过期；超过该日期后，使用它的每次请求都会返回 `401`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。请查看 `detail`：缺失或无效的 API 密钥（绝不会返回 `401`）、属于其他应用的密钥、任何限定作用域的密钥，或来自密钥 IP 列表之外的请求。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key": { "value": { "detail": "This API key has no access to this endpoint." } }, "Outside the key's IP list": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "429": { "description": "使用此 API 密钥的 GET 请求每分钟超过 600 次。请等待 `Retry-After` 中指定的秒数，然后再重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "距离当前一分钟窗口重置的秒数。", "schema": { "type": "integer", "example": 23 } }, "X-RateLimit-Limit": { "description": "在此预算中每分钟允许的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "窗口重置的 Unix 时间。", "schema": { "type": "integer" } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/analytics/today/?tz=Europe%2FMadrid' \\\n -H 'x-api-key: YOUR_API_KEY'" } ], "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/webhooks/": { "get": { "summary": "列出会话 Webhook 投递记录", "description": "列出 Didit 为单个验证会话、用户 (KYC) 或企业 (KYB) 记录的每一次 Webhook 投递，最新的优先，格式为纯 JSON 数组（未分页）。每个条目代表向一个目标发起的一次尝试：首次发送、每次自动[重试](https://docs.didit.me/zh/integration/webhooks#重试策略)和每次重新发送都是拥有各自 `uuid` 的独立条目，且重试和重新发送会保留 payload 的 `event_id`。`request_header` 和 `request_body` 为 JSON 文本；解析它们以读取签名和 payload。投递记录保留约 30 天，因此空数组表示尚未为此会话发送过 Webhook，或者所有投递记录均已超过该期限。限定范围的 API 密钥需要 `sessions: read` 和 `decisions: read` 权限。", "operationId": "get_v3_session_webhooks", "x-didit-sdk": { "resource": "sessions.webhooks", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "用户（KYC）或企业（KYB）验证会话的 UUID：由 `POST /v3/session/` 返回的 `session_id`。服务器会针对两种会话类型进行解析。\n\n**必须是有效的 UUID。** 该路由仅匹配格式正确的 UUID，因此格式错误的值在任何应用代码运行之前就会被 URL 路由器拒绝，并且响应将是 `404` **HTML** 页面，而不是如下所示的 JSON `{\"detail\": ...}` 封装。", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/22222222-3333-4444-5555-666666666666/webhooks/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.webhooks.list(\n \"22222222-3333-4444-5555-666666666666\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.webhooks.list(\"22222222-3333-4444-5555-666666666666\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Webhooks.List(ctx, \"22222222-3333-4444-5555-666666666666\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().webhooks().list(\"22222222-3333-4444-5555-666666666666\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->webhooks->list('22222222-3333-4444-5555-666666666666');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.webhooks.list(\"22222222-3333-4444-5555-666666666666\").each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Webhooks.ListAsync(\"22222222-3333-4444-5555-666666666666\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "为该会话记录的每次投递，最新的排在最前。", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SessionWebhookDelivery" } }, "examples": { "Failed delivery and its successful retry": { "value": [ { "uuid": "66666666-7777-8888-9999-000000000002", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"9188851d160b5b3aacfc946e4dde1f061b7e568662518942c927ddaf507f533d\", \"X-Signature-V2\": \"381236af514d3fb538579365ac5a24f2464ce1b8224c6e770c60d8201c43ecc5\", \"X-Signature-Simple\": \"4740131dc38f29e78a8508371979be74967d5307464494bd3148a03b4d6c8716\", \"X-Timestamp\": \"1792056139\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056139,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-15T09:22:19.104233Z" }, { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"a5e02a03404e1337a0198e6be15d34abbd053c658a0e51e5d0e78554213ef29b\", \"X-Signature-V2\": \"927e7cb770c94ce745939bff73f04aa200015f3bc64795ba46c2aaf78a6cedc5\", \"X-Signature-Simple\": \"e37b0d4c716c72bb5ae7127b9cc455d28ab4686e9e22312b4ec2327409a73302\", \"X-Timestamp\": \"1792056078\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056078,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-15T09:21:18.412345Z" } ] }, "No webhook sent yet": { "value": [] } } } } }, "401": { "description": "API 密钥已过期：它在创建时设置的到期日期已过。错误或已撤销的密钥也会收到 `401`；缺失密钥则收到 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。未提供 `x-api-key`、密钥无效或已撤销会收到 `Authentication credentials were not provided or are invalid.`。属于其他应用的密钥会收到 `You do not have permission to perform this action.`。缺少此 endpoint 所需访问权限的限定作用域密钥会收到指明所缺权限的消息，而在其 IP 白名单之外使用的密钥会收到 `This API key can't be used from this IP address.`。未知的 `sessionId` 会在检查凭据之前返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Key of another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "value": { "detail": "This API key has no read access to sessions." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在或已被删除（在检查凭证之前返回 `Not found.`），或者超出了限定作用域密钥的工作流或状态限制（`Session not found.`）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "value": { "detail": "Not found." } }, "Outside the key's limits": { "value": { "detail": "Session not found." } } } } } }, "429": { "description": "超出速率限制：当前一分钟窗口内该 API 密钥的 GET 请求超过 600 次。请等待 `Retry-After` 秒后再重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "一分钟时间窗口内允许的请求数（600）。", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间（秒）。", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "发生超支的预算名称。", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/webhook/{webhook_uuid}": { "get": { "summary": "获取会话 Webhook 投递记录", "description": "获取验证会话的一次 Webhook 投递：投递的目标 URL、您的 endpoint 返回的 HTTP 状态，以及 Didit 发送的准确请求头和 JSON 请求体。`request_header` 和 `request_body` 为 JSON 文本；若要检查您的[签名验证](https://docs.didit.me/zh/integration/webhooks#签名验证)，请使用其发送目标所对应的密钥（如果投递到旧版 Webhook URL，则使用应用级密钥）根据解析后的请求体重新计算 `X-Signature-V2`。路径末尾不能带斜杠：若带斜杠将返回 `404`。作用域受限的 API 密钥需要 `sessions: read` 和 `decisions: read` 权限。", "operationId": "get_v3_session_webhook", "x-didit-sdk": { "resource": "sessions.webhooks", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "用户（KYC）或企业（KYB）验证会话的 UUID：由 `POST /v3/session/` 返回的 `session_id`。服务器会针对两种会话类型进行解析。\n\n**必须是有效的 UUID。** 该路由仅匹配格式正确的 UUID，因此格式错误的值在任何应用代码运行之前就会被 URL 路由器拒绝，并且响应将是 `404` **HTML** 页面，而不是如下所示的 JSON `{\"detail\": ...}` 封装。", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" }, { "name": "webhook_uuid", "in": "path", "required": true, "description": "投递的 UUID：由 `GET /v3/session/{sessionId}/webhooks/` 返回的条目的 `uuid`。它必须属于路径中的会话。", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/22222222-3333-4444-5555-666666666666/webhook/66666666-7777-8888-9999-000000000001' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.webhooks.retrieve(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.webhooks.retrieve(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Webhooks.Retrieve(ctx, \"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().webhooks().retrieve(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->webhooks->retrieve('22222222-3333-4444-5555-666666666666', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.webhooks.retrieve(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Webhooks.RetrieveAsync(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "投递，包含其请求头和请求体。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionWebhookDelivery" }, "examples": { "Connection failure": { "value": { "uuid": "66666666-7777-8888-9999-000000000001", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 503, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"a5e02a03404e1337a0198e6be15d34abbd053c658a0e51e5d0e78554213ef29b\", \"X-Signature-V2\": \"927e7cb770c94ce745939bff73f04aa200015f3bc64795ba46c2aaf78a6cedc5\", \"X-Signature-Simple\": \"e37b0d4c716c72bb5ae7127b9cc455d28ab4686e9e22312b4ec2327409a73302\", \"X-Timestamp\": \"1792056078\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792056078,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-15T09:21:18.412345Z" } } } } } }, "401": { "description": "API 密钥已过期：它在创建时设置的到期日期已过。错误或已撤销的密钥也会收到 `401`；缺失密钥则收到 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。未提供 `x-api-key`、密钥无效或已撤销会收到 `Authentication credentials were not provided or are invalid.`。属于其他应用的密钥会收到 `You do not have permission to perform this action.`。缺少此 endpoint 所需访问权限的限定作用域密钥会收到指明所缺权限的消息，而在其 IP 白名单之外使用的密钥会收到 `This API key can't be used from this IP address.`。未知的 `sessionId` 会在检查凭据之前返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Key of another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "value": { "detail": "This API key has no read access to sessions." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在或已被删除（在检查凭证之前返回 `Not found.`），或者超出了限定作用域密钥的工作流或状态限制（`Session not found.`）。投递记录不存在、属于其他会话或已不可用时返回 `No WebhookLog matches the given query.`", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "value": { "detail": "Not found." } }, "Outside the key's limits": { "value": { "detail": "Session not found." } }, "Delivery not in this session": { "value": { "detail": "No WebhookLog matches the given query." } } } } } }, "429": { "description": "超出速率限制：当前一分钟窗口内该 API 密钥的 GET 请求超过 600 次。请等待 `Retry-After` 秒后再重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "一分钟时间窗口内允许的请求数（600）。", "schema": { "type": "integer", "example": 600 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间（秒）。", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "发生超支的预算名称。", "schema": { "type": "string", "example": "generic-get" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Throttled": { "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/webhook/{webhook_uuid}/resend": { "post": { "summary": "重发会话 Webhook 投递", "description": "将已记录的会话 Webhook 再次发送到最初发送的 URL，使用相同的 payload 和 `event_id`，以及全新的 `timestamp`、`X-Timestamp` 请求头和签名。Didit 会使用该投递所属目标的当前密钥（对于投递到旧版 Webhook URL 的情况，则使用应用级密钥）对其进行签名，等待您的 endpoint 响应最多 5 秒，将该尝试记录为一次新投递，无论您的 endpoint 响应为何均返回 `200`：请查看 `response_status`。重新发送不会自动重试，并且每次调用都会再次发送，因此请确保您的 endpoint 基于 `event_id` 具备幂等性。该路径没有尾随斜杠，请求也没有请求体。带作用域的 API 密钥需要 `webhooks: write` 和 `decisions: read` 权限。", "operationId": "post_v3_session_webhook_resend", "x-didit-sdk": { "resource": "sessions.webhooks", "method": "resend", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "用户（KYC）或企业（KYB）验证会话的 UUID：由 `POST /v3/session/` 返回的 `session_id`。服务器会针对两种会话类型进行解析。\n\n**必须是有效的 UUID。** 该路由仅匹配格式正确的 UUID，因此格式错误的值在任何应用代码运行之前就会被 URL 路由器拒绝，并且响应将是 `404` **HTML** 页面，而不是如下所示的 JSON `{\"detail\": ...}` 封装。", "schema": { "type": "string", "format": "uuid" }, "example": "22222222-3333-4444-5555-666666666666" }, { "name": "webhook_uuid", "in": "path", "required": true, "description": "要重新发送的投递的 UUID：由 `GET /v3/session/{sessionId}/webhooks/` 返回的条目的 `uuid`。它必须属于路径中的会话。", "schema": { "type": "string", "format": "uuid" }, "example": "66666666-7777-8888-9999-000000000001" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/session/22222222-3333-4444-5555-666666666666/webhook/66666666-7777-8888-9999-000000000001/resend' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.webhooks.resend(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.webhooks.resend(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Webhooks.Resend(ctx, \"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().webhooks().resend(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->webhooks->resend('22222222-3333-4444-5555-666666666666', '66666666-7777-8888-9999-000000000001');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.webhooks.resend(\n \"22222222-3333-4444-5555-666666666666\",\n \"66666666-7777-8888-9999-000000000001\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Webhooks.ResendAsync(\"22222222-3333-4444-5555-666666666666\", \"66666666-7777-8888-9999-000000000001\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已尝试的新投递。`response_status` 为您的 endpoint 此次返回的状态。原始投递保持不变。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionWebhookDelivery" }, "examples": { "Accepted on resend": { "value": { "uuid": "66666666-7777-8888-9999-000000000004", "session_id": "22222222-3333-4444-5555-666666666666", "request_url": "https://yourapp.com/webhooks/didit", "response_status": 200, "status": "In Progress", "webhook_type": "status.updated", "request_header": "{\"Content-Type\": \"application/json\", \"X-Signature\": \"b8eb1e376517ee0cad8ba98ff7f8fd35fc72eca231000963a96a335f82328835\", \"X-Signature-V2\": \"9efd2ce9ed1303e1d05273ef9608a59363ed9789a05253db4748b3e8e50cb109\", \"X-Signature-Simple\": \"bf3a9dc04b2c20ab539203b0cd5cca2a10f630bf62d8feb6d68d82af80f64774\", \"X-Timestamp\": \"1792159542\", \"User-Agent\": \"DiditWebhook/2.0 +https://didit.me\"}", "request_body": "{\"application_id\":\"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\"created_at\":1792056057,\"environment\":\"live\",\"event_id\":\"33333333-4444-5555-6666-777777777777\",\"sandbox_scenario\":null,\"session_id\":\"22222222-3333-4444-5555-666666666666\",\"status\":\"In Progress\",\"timestamp\":1792159542,\"vendor_data\":\"user-123\",\"webhook_type\":\"status.updated\",\"workflow_id\":\"44444444-5555-6666-7777-888888888888\",\"workflow_version\":3}", "created_at": "2026-10-16T14:05:42.330981Z" } } } } } }, "400": { "description": "投递无法重新发送。根据 `code` 进行分支判断：`webhook_url_missing` 表示该投递没有记录的 URL，不会发送任何内容；`webhook_resend_error` 表示存储的投递无法再次签名或尝试无法完成。在 `webhook_resend_error` 之后，`detail` 以 `Error processing webhook resend:` 开头，后跟可能发生变化的诊断文本。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" }, "code": { "type": "string", "description": "稳定的机器可读错误代码。请基于此代码进行分支处理，而非 `detail`。" } } }, "examples": { "No recorded URL": { "value": { "detail": "The webhook delivery does not have a request URL configured", "code": "webhook_url_missing" } }, "Resend failed": { "value": { "detail": "Error processing webhook resend: Invalid webhook data format", "code": "webhook_resend_error" } } } } } }, "401": { "description": "API 密钥已过期：它在创建时设置的到期日期已过。错误或已撤销的密钥也会收到 `401`；缺失密钥则收到 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "该请求不被允许。未提供 `x-api-key`、密钥无效或已撤销会收到 `Authentication credentials were not provided or are invalid.`。属于其他应用的密钥会收到 `You do not have permission to perform this action.`。缺少此 endpoint 所需访问权限的限定作用域密钥会收到指明所缺权限的消息，而在其 IP 白名单之外使用的密钥会收到 `This API key can't be used from this IP address.`。未知的 `sessionId` 会在检查凭据之前返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid key": { "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Key of another application": { "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without webhooks write": { "value": { "detail": "This API key has no write access to webhooks." } }, "Scoped key without decisions read": { "value": { "detail": "This API key has no read access to decisions." } }, "Outside the IP allowlist": { "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在或已被删除（在检查凭证之前返回 `Not found.`），或者超出了限定作用域密钥的工作流或状态限制（`Session not found.`）。投递记录不存在、属于其他会话或已不可用时返回 `Webhook log not found`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "value": { "detail": "Not found." } }, "Outside the key's limits": { "value": { "detail": "Session not found." } }, "Delivery not in this session": { "value": { "detail": "Webhook log not found" } } } } } }, "429": { "description": "超出速率限制：当前一分钟窗口内该 API 密钥的写入请求（POST、PATCH、PUT、DELETE）超过 300 次。请等待 `Retry-After` 秒后再重试。", "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } }, "X-RateLimit-Limit": { "description": "一分钟时间窗口内允许的请求数（300）。", "schema": { "type": "integer", "example": 300 } }, "X-RateLimit-Remaining": { "description": "当前时间窗口内剩余的请求数。", "schema": { "type": "integer", "example": 0 } }, "X-RateLimit-Reset": { "description": "当前窗口重置的 Unix 时间（秒）。", "schema": { "type": "integer", "example": 1792056120 } }, "X-RateLimit-Scope": { "description": "发生超支的预算名称。", "schema": { "type": "string", "example": "generic-write" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Throttled": { "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/events/": { "get": { "summary": "列出会话事件", "description": "读取单个验证会话的事件时间线，按 `sent_at` 倒序排列（最新的排在最前）：用户看到的页面、按钮点击和上传、失败的尝试、状态和功能步骤变更，以及工作流路由追踪。适用于用户验证（KYC）和企业验证（KYB）会话 ID。事件采用异步存储，因此新事件可能需要几秒钟才会显示。结果通过 `limit` 和 `offset` 进行分页；跟随 `next` 直至其为 `null`。限定作用域的 API 密钥需要 `sessions: read` 和 `decisions: read` 权限，若缺少 `media: read` 权限，接收到的 `file_url` 将为 `null`。路由事件在[检索会话](https://docs.didit.me/zh/sessions-api/retrieve-session)中进行了说明。", "operationId": "get_v3_session_events", "x-didit-sdk": { "resource": "sessions", "method": "list_events", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "验证会话的 UUID（由 `POST /v3/session/` 返回的 `session_id`）。支持用户验证（KYC）和企业验证（KYB）会话 ID：服务器会跨两种会话类型解析该 ID。必须是格式正确的 UUID；格式不正确的值无法匹配路由并返回 HTML `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "limit", "in": "query", "required": false, "description": "每页最大事件数。默认值为 50。小于 1 的值或非数值将回退至 50；超过 1,000,000 的值将返回 `400`。", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000, "example": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "返回第一条结果前跳过的结果数量。默认为 0；负数或非数字值将回退为 0，大于 1,000,000 的值将返回 `400`。建议优先使用 `next` 和 `previous` URL。", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000, "example": 0 } }, { "name": "ordering", "in": "query", "required": false, "description": "可选的排序覆盖设置。默认顺序为 `-sent_at`。传入结果字段名称（例如 `sent_at`、`created_at`、`event_type`、`feature_step` 或 `step`）进行升序排序，添加 `-` 前缀进行降序排序，多个字段之间用逗号分隔。未知字段将被忽略。", "schema": { "type": "string", "example": "sent_at" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/events/?limit=50' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.list_events(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.listEvents(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListEventsAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsListEventsParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().listEvents(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->listEvents('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.list_events(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.ListEventsAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "该会话的一页事件，最新的排在最前。", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "会话的事件总数。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的 URL，最后一页为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的 URL，第一页为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/SessionEvent" } } } }, "examples": { "Completed session": { "value": { "count": 3, "next": null, "previous": null, "results": [ { "uuid": "aaaaaaaa-1111-2222-3333-444444444444", "event_type": "SESSION_STATUS_CHANGED", "created_at": "2026-09-14T10:02:13.904512Z", "component": null, "feature_step": null, "step": null, "details": { "old_status": "In Progress", "current_status": "Approved" }, "ip_address": null, "user_agent": null, "device_info": null, "file_url": null, "sent_at": 1789380131482 }, { "uuid": "bbbbbbbb-1111-2222-3333-444444444444", "event_type": "FEATURE_STEP_CHANGED", "created_at": "2026-09-14T10:01:49.210377Z", "component": null, "feature_step": null, "step": null, "details": { "old_feature_step": "OCR", "current_feature_step": "LIVENESS" }, "ip_address": null, "user_agent": null, "device_info": null, "file_url": null, "sent_at": 1789380107103 }, { "uuid": "cccccccc-1111-2222-3333-444444444444", "event_type": "STEP_RENDERED", "created_at": "2026-09-14T10:01:00.581930Z", "component": "DocumentCapture", "feature_step": "OCR", "step": "DOCUMENT_CAPTURE_FRONT", "details": {}, "ip_address": "203.0.113.24", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_5 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.5 Mobile/15E148 Safari/604.1", "device_info": { "device_model": "iPhone" }, "file_url": null, "sent_at": 1789380058776 } ] } } } } } }, "400": { "description": "`limit` 或 `offset` 超过 1,000,000。响应体是包含一条消息的 JSON 数组。", "content": { "application/json": { "examples": { "Limit too large": { "summary": "limit=2000000", "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "summary": "offset=2000000", "value": [ "offset must not exceed 1000000." ] } }, "schema": { "type": "array", "items": { "type": "string" } } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions read": { "summary": "作用域密钥缺少 sessions: read 权限", "value": { "detail": "This API key has no read access to sessions." } }, "Scoped key without decisions read": { "summary": "作用域密钥缺少 decisions: read 权限", "value": { "detail": "This API key has no read access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除，或超出了限定作用域密钥的工作流或仅限已通过状态的限制。会话查找在凭证检查之前执行，因此即使没有有效密钥，未知的 `sessionId` 也会返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "summary": "不存在具有此 ID 的会话，或该会话已被删除", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "会话超出了限定作用域密钥的工作流或仅限已通过状态的限制", "value": { "detail": "Session not found." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟最多 600 次 GET 请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 请求头显示了配额状态。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/aml-screening-history/": { "get": { "summary": "列出 AML 筛查历史记录", "description": "列出会话 AML 检查中每一次已完成的持续监控重新筛查，按 `completed_at` 最新的优先，包括未发生任何变更的运行记录：仅当结果发生变化时才会触发警报、活动条目和 Webhook，因此该历史记录是未发现问题的主体仍在接受筛查的凭据。适用于 KYC 和 KYB 会话 ID；当会话运行了多个 AML 步骤时，请传入 `node_id`。仅列出持续监控重新筛查（首次筛查是会话决策的一部分），且不会重建此历史记录存在之前的运行记录，因此没有持续监控的会话将返回空列表。`count` 在不超过 100 时是精确的，超过 100 时上限为 100，因此请持续追踪 `next` 直至其为 `null`。传入 `month` 可一次读取一个日历月的数据。限定范围的 API 密钥需要 `decisions: read` 权限；参见[持续 AML 监控](https://docs.didit.me/zh/core-technology/aml-screening/continuous-monitoring-aml-screening)。", "operationId": "get_v3_session_aml_screening_history", "x-didit-sdk": { "resource": "sessions", "method": "list_aml_screening_history", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "验证会话的 UUID（由 `POST /v3/session/` 返回的 `session_id`）。支持用户验证（KYC）和企业验证（KYB）会话 ID：服务器会跨两种会话类型解析该 ID。必须是格式正确的 UUID；格式不正确的值无法匹配路由并返回 HTML `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "AML 检查的工作流图谱节点 ID。仅在会话运行了多个 AML 步骤时需要；若不提供，则使用最新的 AML 检查。未知的节点将返回 `404`。", "schema": { "type": "string", "example": "feature_aml_1" } }, { "name": "month", "in": "query", "required": false, "description": "格式为 `YYYY-MM` 的 UTC 日历月份。仅返回在该月份完成的筛查；若不指定则返回所有月份。格式错误的月份将返回 `400`。", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } }, { "name": "limit", "in": "query", "required": false, "description": "每页最大筛查运行次数。默认值为 50。小于 1 的值或非数值将回退至 50；超过 1,000,000 的值将返回 `400`。", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 1000000, "example": 50 } }, { "name": "offset", "in": "query", "required": false, "description": "返回第一条结果前跳过的结果数量。默认为 0；负数或非数字值将回退为 0，大于 1,000,000 的值将返回 `400`。建议优先使用 `next` 和 `previous` URL。", "schema": { "type": "integer", "default": 0, "minimum": 0, "maximum": 1000000, "example": 0 } }, { "name": "ordering", "in": "query", "required": false, "description": "可选的排序覆盖设置。默认顺序为 `-completed_at`。传入结果字段名称（例如 `completed_at`、`started_at`、`outcome` 或 `score`）进行升序排序，添加 `-` 前缀进行降序排序，多个字段之间用逗号分隔。未知字段将被忽略。", "schema": { "type": "string", "example": "completed_at" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/aml-screening-history/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.sessions.list_aml_screening_history(\n \"11111111-2222-3333-4444-555555555555\",\n):\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.sessions.listAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\")) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Sessions.ListAMLScreeningHistoryAutoPaging(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsListAMLScreeningHistoryParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.sessions().listAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\")) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "sessions->listAmlScreeningHistory('11111111-2222-3333-4444-555555555555') as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.list_aml_screening_history(\"11111111-2222-3333-4444-555555555555\").auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Sessions.ListAmlScreeningHistoryAsync(\"11111111-2222-3333-4444-555555555555\"))\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "一页筛查运行记录，最新的排在最前。", "content": { "application/json": { "schema": { "type": "object", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "maximum": 100, "description": "运行次数，100 以内为准确数值，超过 100 时封顶显示为 100。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的 URL，最后一页为 `null`。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的 URL，第一页为 `null`。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/AMLScreeningRun" } } } }, "examples": { "Monitored subject": { "value": { "count": 2, "next": null, "previous": null, "results": [ { "uuid": "dddddddd-1111-2222-3333-444444444444", "run_id": "aaaaaaaa-1111-2222-3333-444444444444", "completed_at": "2026-09-14T04:12:33.481207Z", "started_at": "2026-09-14T04:00:01.002311Z", "outcome": "NO_CHANGE", "trigger": "ONGOING_MONITORING", "provider": "aml_data_source", "status": "Approved", "score": 0.0, "total_hits": 0, "new_hits": 0, "entities_screened": 1, "dataset_freshness": { "captured_at": "2026-09-14T03:58:02.114820+00:00", "provider": "aml_data_source", "catalog_version": "2026-09-13", "sources": { "sanctions": { "last_updated_at": "2026-09-13T21:10:00+00:00", "oldest_updated_at": "2026-09-11T06:00:00+00:00", "dataset_count": 120, "dated_dataset_count": 120 }, "pep": { "last_updated_at": "2026-09-13T08:00:00+00:00", "oldest_updated_at": null, "dataset_count": 45, "dated_dataset_count": 44 }, "warnings": { "last_updated_at": "2026-09-12T18:45:00+00:00", "oldest_updated_at": "2026-09-01T00:00:00+00:00", "dataset_count": 30, "dated_dataset_count": 30 } } } }, { "uuid": "eeeeeeee-1111-2222-3333-444444444444", "run_id": "bbbbbbbb-1111-2222-3333-444444444444", "completed_at": "2026-09-13T04:11:58.020914Z", "started_at": "2026-09-13T04:00:00.871022Z", "outcome": "FAILED", "trigger": "ONGOING_MONITORING", "provider": "aml_data_source", "status": "Approved", "score": 0.0, "total_hits": 0, "new_hits": null, "entities_screened": 0, "dataset_freshness": null } ] } } } } } }, "400": { "description": "`limit` 或 `offset` 超过 1,000,000（包含一条消息的 JSON 数组），或 `month` 不是 `YYYY-MM` 日历月份（以 `month` 为键的对象）。", "content": { "application/json": { "examples": { "Limit too large": { "summary": "limit=2000000", "value": [ "limit must not exceed 1000000." ] }, "Offset too large": { "summary": "offset=2000000", "value": [ "offset must not exceed 1000000." ] }, "Malformed month": { "summary": "month=2026-13", "value": { "month": [ "Not a calendar month. Use YYYY-MM." ] } } }, "schema": { "oneOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "object", "properties": { "month": { "type": "array", "items": { "type": "string" } } } } ] } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions read": { "summary": "作用域密钥缺少 decisions: read 权限", "value": { "detail": "This API key has no read access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除或超出了限定作用域密钥的限制，或者该会话没有 AML 检查（针对给定的 `node_id`）。会话查找在凭证检查之前执行，因此即使没有有效密钥，未知的 `sessionId` 也会返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "summary": "不存在具有此 ID 的会话，或该会话已被删除", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "会话超出了限定作用域密钥的限制（对于刚刚删除的会话也会返回此错误）", "value": { "detail": "Session not found." } }, "No AML check": { "summary": "该会话从未运行过 AML 步骤", "value": { "detail": "The session does not have an AML check." } }, "No AML check for node": { "summary": "node_id 与该会话的 AML 检查不匹配", "value": { "detail": "The session does not have an AML check for node 'feature_aml_2'." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟最多 600 次 GET 请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 请求头显示了配额状态。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/aml-screening-history/export/": { "get": { "summary": "将 AML 筛查历史记录导出为 CSV", "description": "以 CSV 文件形式下载与 `GET /v3/session/{sessionId}/aml-screening-history/` 相同的持续监控历史记录，每次完成的重新筛查占一行，最新的排在最前，可直接提交给审计员。文件以完整数据流传输（无分页）并以表头行开始；空单元格表示未知，数据集日期从不预估，可能触发电子表格公式的值会带有单引号前缀。适用于 KYC 和 KYB 会话 ID；当会话运行了多个 AML 步骤时，请传递 `node_id`。传递 `month` 可导出单个日历月份。错误以 JSON 格式返回，而非 CSV。限定作用域的 API 密钥需要 `decisions: read` 和 `media: read` 权限：由于响应是一个文件，没有 `media: read` 权限的密钥将收到 `403`。", "operationId": "get_v3_session_aml_screening_history_export", "x-didit-sdk": { "resource": "sessions", "method": "export_aml_screening_history", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "验证会话的 UUID（由 `POST /v3/session/` 返回的 `session_id`）。支持用户验证（KYC）和企业验证（KYB）会话 ID：服务器会跨两种会话类型解析该 ID。必须是格式正确的 UUID；格式不正确的值无法匹配路由并返回 HTML `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "AML 检查的工作流图谱节点 ID。仅在会话运行了多个 AML 步骤时需要；若不提供，则使用最新的 AML 检查。未知的节点将返回 `404`。", "schema": { "type": "string", "example": "feature_aml_1" } }, { "name": "month", "in": "query", "required": false, "description": "格式为 `YYYY-MM` 的 UTC 日历月份。仅返回在该月份完成的筛查；若不指定则返回所有月份。格式错误的月份将返回 `400`。", "schema": { "type": "string", "pattern": "^\\d{4}-(0[1-9]|1[0-2])$", "example": "2026-09" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/aml-screening-history/export/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -o aml-screening-history.csv" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.sessions.export_aml_screening_history(\n \"11111111-2222-3333-4444-555555555555\",\n)\nwith open(\"download.csv\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.sessions.exportAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\");\nawait writeFile(\"download.csv\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Sessions.ExportAMLScreeningHistory(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsExportAMLScreeningHistoryParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.csv\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().exportAmlScreeningHistory(\"11111111-2222-3333-4444-555555555555\")\n .writeTo(Path.of(\"download.csv\"));" }, { "lang": "php", "label": "PHP", "source": "sessions->exportAmlScreeningHistory('11111111-2222-3333-4444-555555555555');\n$content->saveTo('download.csv');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.sessions.export_aml_screening_history(\"11111111-2222-3333-4444-555555555555\")\nFile.binwrite(\"download.csv\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Sessions.ExportAmlScreeningHistoryAsync(\"11111111-2222-3333-4444-555555555555\");\nawait content.SaveToAsync(\"download.csv\");" } ], "responses": { "200": { "description": "CSV 文件，以 `text/csv` 格式流式传输，并使用 CRLF 换行符。列按顺序如下：`screened_at`（重新筛查完成时间）、`outcome`（`NO_CHANGE`、`CHANGED` 或 `FAILED`）、`provider`（AML 数据源的不透明标识符；请勿根据它执行条件分支）、`aml_status`、`aml_score`、`total_hits`、`datasets_captured_at`、`datasets_sanctions_last_updated_at`、`datasets_pep_last_updated_at`、`datasets_warnings_last_updated_at`、`datasets_adverse_media_last_updated_at`、`datasets_catalog_version`、`run_id`（监控运行）、`entities_screened`（`1`，失败的运行则为 `0`）以及 `new_hits`（未知时为空）。日期格式为带 UTC 偏移量的 ISO 8601。尚无重新筛查的会话仅返回表头行。", "headers": { "Content-Disposition": { "description": "`attachment; filename=\"aml-screening-history-{sessionId}.csv\"`，或者当传递 `month` 时为 `aml-screening-history-{sessionId}-{month}.csv`。", "schema": { "type": "string", "example": "attachment; filename=\"aml-screening-history-11111111-2222-3333-4444-555555555555.csv\"" } } }, "content": { "text/csv": { "schema": { "type": "string", "format": "binary" }, "example": "screened_at,outcome,provider,aml_status,aml_score,total_hits,datasets_captured_at,datasets_sanctions_last_updated_at,datasets_pep_last_updated_at,datasets_warnings_last_updated_at,datasets_adverse_media_last_updated_at,datasets_catalog_version,run_id,entities_screened,new_hits\r\n2026-09-14T04:12:33.481207+00:00,NO_CHANGE,aml_data_source,Approved,0.0,0,2026-09-14T03:58:02.114820+00:00,2026-09-13T21:10:00+00:00,2026-09-13T08:00:00+00:00,2026-09-12T18:45:00+00:00,,2026-09-13,aaaaaaaa-1111-2222-3333-444444444444,1,0\r\n2026-09-13T04:11:58.020914+00:00,FAILED,aml_data_source,Approved,0.0,0,,,,,,,bbbbbbbb-1111-2222-3333-444444444444,0,\r\n" } } }, "400": { "description": "`month` 不是 `YYYY-MM` 日历月份。", "content": { "application/json": { "schema": { "type": "object", "properties": { "month": { "type": "array", "items": { "type": "string" } } } }, "examples": { "Malformed month": { "summary": "month=2026-13", "value": { "month": [ "Not a calendar month. Use YYYY-MM." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions read": { "summary": "作用域密钥缺少 decisions: read 权限", "value": { "detail": "This API key has no read access to decisions." } }, "Scoped key without media read": { "summary": "作用域密钥缺少 media: read 权限（响应为一个文件）", "value": { "detail": "This API key has no read access to media." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除或超出了限定作用域密钥的限制，或者该会话没有 AML 检查（针对给定的 `node_id`）。会话查找在凭证检查之前执行，因此即使没有有效密钥，未知的 `sessionId` 也会返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "summary": "不存在具有此 ID 的会话，或该会话已被删除", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "会话超出了限定作用域密钥的限制（对于刚刚删除的会话也会返回此错误）", "value": { "detail": "Session not found." } }, "No AML check": { "summary": "该会话从未运行过 AML 步骤", "value": { "detail": "The session does not have an AML check." } }, "No AML check for node": { "summary": "node_id 与该会话的 AML 检查不匹配", "value": { "detail": "The session does not have an AML check for node 'feature_aml_2'." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟最多 600 次 GET 请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 请求头显示了配额状态。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/add-images/": { "patch": { "summary": "向会话添加图片", "description": "为已完成的用户验证（KYC）会话的身份证件验证（`model_type=kyc`）或地址证明（`model_type=poa`）结果附加一份额外的图像或 PDF，例如在工作流外部收集的证明。该会话必须为 `Approved`、`Declined`、`In Review` 或 `Kyc Expired`，并包含由 `model_type` 指定的结果；不支持企业验证（KYB）会话。每次调用都会追加一个文件（当该步骤运行多次时，追加到最新的结果中），保留现有文件，并在会话活动日志中记录一条 `FILE_ADDED` 条目；上传不会发送 Webhook，也不会更改会话状态。文件在上传时会被压缩，并在会话决策的 `extra_files` 中返回。此 endpoint 限制为每个 API 密钥每分钟 10 次请求。具有作用域限制的 API 密钥需要 `sessions: write` 权限，若没有 `media: read` 权限，则接收到的 `extra_files` 链接为 `null`。", "operationId": "patch_v3_session_add_images", "x-didit-sdk": { "resource": "sessions", "method": "add_images", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "要向其添加文件的用户验证（KYC）会话的 UUID（`POST /v3/session/` 返回的 `session_id`）。企业验证（KYB）会话 ID 将返回 `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "file", "model_type" ], "properties": { "file": { "type": "string", "format": "binary", "description": "图像或 PDF。允许的扩展名：`jpg`、`jpeg`、`png`、`webp`、`tiff`、`pdf`。上传时最大支持 15 MB；随后文件会被压缩，若压缩后仍大于 2 MB（2,097,152 字节），将返回 `400` 并拒绝。空文件将被拒绝。" }, "model_type": { "type": "string", "enum": [ "kyc", "poa" ], "description": "`kyc` 将文件添加至身份证件验证结果，`poa` 添加至地址证明结果。", "example": "kyc" }, "file_password": { "type": "string", "description": "加密 PDF 的密码。未提供或提供错误密码时，加密 PDF 将返回 `400`。" } } }, "example": { "file": "(binary)", "model_type": "kyc" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/add-images/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'file=@./back-of-id.jpg' \\\n -F 'model_type=kyc'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.add_images(\n \"11111111-2222-3333-4444-555555555555\",\n file=open(\"image.jpg\", \"rb\"),\n model_type=\"kyc\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.addImages(\"11111111-2222-3333-4444-555555555555\", {\n file: await fileFromPath(\"image.jpg\"),\n model_type: \"kyc\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.AddImages(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsAddImagesParams{\n\tFile: didit.FileFromPath(\"image.jpg\"),\n\tModelType: \"kyc\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.SessionsAddImagesParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().addImages(\"11111111-2222-3333-4444-555555555555\", SessionsAddImagesParams.builder()\n .file(Path.of(\"image.jpg\"))\n .modelType(SessionsAddImagesParams.ModelType.of(\"kyc\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->addImages('11111111-2222-3333-4444-555555555555', [\n 'file' => File::fromPath('image.jpg'),\n 'model_type' => 'kyc',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.add_images(\n \"11111111-2222-3333-4444-555555555555\",\n file: Pathname(\"image.jpg\"),\n model_type: \"kyc\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.AddImagesAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsAddImagesParams\n{\n File = FileUpload.FromPath(\"image.jpg\"),\n ModelType = \"kyc\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "文件已添加。返回该结果的所有额外文件，包括新添加的文件。", "content": { "application/json": { "schema": { "type": "object", "required": [ "extra_files" ], "properties": { "extra_files": { "type": "array", "description": "`model_type` 指定结果的所有额外文件的短期预签名链接，最早的文件排在最前。对于不具备 `media: read` 权限的受限作用域 API 密钥，每个链接均为 `null`。后续可从会话决策中读取最新链接。", "items": { "type": "string", "format": "uri", "nullable": true } } } }, "example": { "extra_files": [ "https://media.example.com/session/11111111-2222-3333-4444-555555555555/kyc-extra-files/66666666-7777-8888-9999-000000000000.jpg?expires=1789383731&signature=abc123" ] } } } }, "400": { "description": "验证错误。字段错误以 `{\"\": [\"\"]}` 形式返回；加密 PDF 错误以 `{\"detail\": \"...\"}` 形式返回。", "content": { "application/json": { "examples": { "Missing file": { "summary": "表单中没有文件字段", "value": { "file": [ "No file was submitted." ] } }, "Missing model_type": { "summary": "省略了 model_type", "value": { "model_type": [ "This field is required." ] } }, "Invalid model_type": { "summary": "model_type 不是 kyc 或 poa", "value": { "model_type": [ "\"passport\" is not a valid choice." ] } }, "File too large": { "summary": "上传超过 15 MB", "value": { "file": [ "File size should not exceed 15 MB" ] } }, "Too large after compression": { "summary": "压缩后仍超过 2 MB", "value": { "file": [ "File size is too big. Max allowed size is 2097152 bytes." ] } }, "Encrypted PDF": { "summary": "未提供 file_password 的加密 PDF", "value": { "detail": "The PDF is encrypted. Please upload a decrypted PDF or a photo instead." } }, "Wrong PDF password": { "summary": "file_password 无法打开该 PDF", "value": { "detail": "The PDF password is incorrect. Please provide the correct password." } } } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without sessions write": { "summary": "作用域密钥缺少 sessions: write 权限", "value": { "detail": "This API key has no write access to sessions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除或超出了限定作用域密钥的限制；为 KYB 会话或未处于 `Approved`、`Declined`、`In Review` 或 `Kyc Expired` 状态；或者没有所请求 `model_type` 的结果（在验证文件之前检查）。会话查找在凭证检查之前执行，因此即使没有有效密钥，未知的 `sessionId` 也会返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "summary": "不存在具有此 ID 的会话，或该会话已被删除", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "会话超出了限定作用域密钥的工作流或仅限已通过状态的限制", "value": { "detail": "Session not found." } }, "Not eligible": { "summary": "会话尚未完成，或为 KYB 会话 ID", "value": { "detail": "No Session matches the given query." } }, "No ID verification": { "summary": "在未进行身份证件验证的会话上设置了 model_type=kyc", "value": { "detail": "The session does not have KYC data." } }, "No Proof of Address": { "summary": "在未提供地址证明的会话上设置了 model_type=poa", "value": { "detail": "The session does not have POA data." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟 10 次添加图片请求（被拒绝的请求也计算在内）。同时适用每分钟 300 次写入请求的共享额度。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 响应头显示了额度。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "Session add-images rate limit exceeded. You can make up to 10 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/update-aml-status/": { "patch": { "summary": "更新 AML 检查状态", "description": "设置整个会话 AML 筛查检查的状态（会话决策中 `aml_screenings[]` 条目的 `status`），例如在您的团队排除了所有命中项后设置为 `Approved`。适用于 KYC 和 KYB 会话 ID；当会话运行了多个 AML 步骤时，请传递 `node_id`（查询参数或请求体字段），否则将更新最新的 AML 检查。当状态实际发生变化时，会记录 `AML_STATUS_UPDATED` 活动条目并发送 `data.updated` [Webhook](https://docs.didit.me/zh/integration/webhooks)；发送当前状态将返回 `200` 且不进行任何更改。会话状态不会重新计算：会话决策请使用 `PATCH /v3/session/{sessionId}/update-status/`，单个命中项请使用 `PATCH /v3/session/{sessionId}/update-aml-hit-status/`。限定权限范围的 API 密钥需要 `decisions: write` 权限。", "operationId": "patch_v3_session_update_aml_status", "x-didit-sdk": { "resource": "sessions", "method": "update_aml_status", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "验证会话的 UUID（由 `POST /v3/session/` 返回的 `session_id`）。支持用户验证（KYC）和企业验证（KYB）会话 ID：服务器会跨两种会话类型解析该 ID。必须是格式正确的 UUID；格式不正确的值无法匹配路由并返回 HTML `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "node_id", "in": "query", "required": false, "description": "要更新的 AML 检查的工作流图谱节点 ID。仅在会话运行了多个 AML 步骤时需要。优先于请求体中的 `node_id`。", "schema": { "type": "string", "example": "feature_aml_1" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "AML 检查的新状态。", "example": "Approved" }, "node_id": { "type": "string", "description": "AML 检查的工作流图谱节点 ID，作为查询参数的替代项。", "example": "feature_aml_1" } } }, "example": { "status": "Approved" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PATCH 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/update-aml-status/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"status\": \"Approved\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_aml_status(\n \"11111111-2222-3333-4444-555555555555\",\n status=\"Approved\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateAmlStatus(\"11111111-2222-3333-4444-555555555555\", {\n status: \"Approved\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateAMLStatus(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsUpdateAMLStatusParams{\n\tStatus: \"Approved\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateAmlStatusParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateAmlStatus(\"11111111-2222-3333-4444-555555555555\", SessionsUpdateAmlStatusParams.builder()\n .status(SessionsUpdateAmlStatusParams.Status.of(\"Approved\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateAmlStatus('11111111-2222-3333-4444-555555555555', [\n 'status' => 'Approved',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_aml_status(\n \"11111111-2222-3333-4444-555555555555\",\n status: \"Approved\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateAmlStatusAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsUpdateAmlStatusParams\n{\n Status = \"Approved\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已设置的 AML 检查状态（若已具备该值则保持不变）。", "content": { "application/json": { "schema": { "type": "object", "required": [ "message", "status", "previous_status" ], "properties": { "message": { "type": "string", "description": "始终为 `AML status updated successfully`。" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "当前 AML 检查的状态。" }, "previous_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "调用前的状态。未发生变更时与 `status` 相同。" } } }, "example": { "message": "AML status updated successfully", "status": "Approved", "previous_status": "In Review" } } } }, "400": { "description": "验证错误：`status` 缺失或不属于允许的值。AML 检查查询会优先执行，因此即使请求体无效，没有 AML 检查的会话也会返回 `404`。", "content": { "application/json": { "examples": { "Missing status": { "summary": "空请求体或无状态", "value": { "status": [ "This field is required." ] } }, "Invalid status": { "summary": "status 不在枚举中", "value": { "status": [ "\"Cleared\" is not a valid choice." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除或超出了限定作用域密钥的限制，或者该会话没有 AML 检查（针对给定的 `node_id`）。会话查找在凭证检查之前执行，因此即使没有有效密钥，未知的 `sessionId` 也会返回 `404`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Unknown session": { "summary": "不存在具有此 ID 的会话，或该会话已被删除", "value": { "detail": "Not found." } }, "Outside key limits": { "summary": "会话超出了限定作用域密钥的限制（对于刚刚删除的会话也会返回此错误）", "value": { "detail": "Session not found." } }, "No AML check": { "summary": "该会话从未运行过 AML 步骤", "value": { "detail": "The session does not have an AML check." } }, "No AML check for node": { "summary": "node_id 与该会话的 AML 检查不匹配", "value": { "detail": "The session does not have an AML check for node 'feature_aml_2'." } } } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟 300 次写入（POST、PATCH、DELETE）请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 响应头显示了额度。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/status/": { "get": { "summary": "获取服务状态（公开，无需身份验证）", "description": "返回每个 Didit 服务的状态（`operational`、`degraded` 或 `down`）、整体状态（其中最差的状态），以及正在发生或在过去 7 天内已解决的突发事件。可用于为状态小组件提供数据支持，或在您的集成中检查 Didit 的健康状态。\n\n公开：无需发送认证请求头。响应不包含任何组织数据，对所有调用方均相同。响应会缓存 30 秒，因此轮询频率请勿超过每 30 秒一次。", "operationId": "get_v3_status", "tags": [ "Status" ], "security": [ {} ], "parameters": [], "responses": { "200": { "description": "当前服务状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceStatusFeed" }, "examples": { "One service degraded": { "summary": "一起正在发生的突发事件以及一起本周已解决的突发事件", "value": { "status": "degraded", "updated_at": "2026-10-13T09:41:07.512345Z", "services": [ { "key": "service_id_verification", "name": "ID verification", "status": "operational" }, { "key": "service_liveness_face_match", "name": "Liveness and face match", "status": "operational" }, { "key": "service_aml_screening", "name": "AML screening", "status": "operational" }, { "key": "service_kyb_registries", "name": "KYB registries", "status": "operational" }, { "key": "service_database_validation", "name": "Database validation", "status": "degraded" }, { "key": "service_phone_delivery", "name": "Phone verification delivery", "status": "operational" }, { "key": "service_email_delivery", "name": "Email verification delivery", "status": "operational" }, { "key": "service_transaction_monitoring", "name": "Transaction monitoring", "status": "operational" } ], "incidents": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "service": "service_database_validation", "service_name": "Database validation", "state": "degraded", "status": "ongoing", "title": "Database validation is degraded in Brazil.", "body": "Checks against Brazil (CPF) may be slow or fail since 08:55 UTC.", "affected": "Brazil (CPF)", "country_name": "Brazil", "started_at": "2026-10-13T08:55:00Z", "resolved_at": null, "duration_minutes": null }, { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "service": "service_aml_screening", "service_name": "AML screening", "state": "down", "status": "resolved", "title": "AML screening is back to normal.", "body": "Recovered at 14:32 UTC after 17 minutes.", "affected": "", "country_name": "", "started_at": "2026-10-11T14:15:00Z", "resolved_at": "2026-10-11T14:32:00Z", "duration_minutes": 17 } ] } }, "All operational": { "summary": "过去 7 天内没有事件", "value": { "status": "operational", "updated_at": "2026-10-13T09:41:07.512345Z", "services": [ { "key": "service_id_verification", "name": "ID verification", "status": "operational" }, { "key": "service_liveness_face_match", "name": "Liveness and face match", "status": "operational" }, { "key": "service_aml_screening", "name": "AML screening", "status": "operational" }, { "key": "service_kyb_registries", "name": "KYB registries", "status": "operational" }, { "key": "service_database_validation", "name": "Database validation", "status": "operational" }, { "key": "service_phone_delivery", "name": "Phone verification delivery", "status": "operational" }, { "key": "service_email_delivery", "name": "Email verification delivery", "status": "operational" }, { "key": "service_transaction_monitoring", "name": "Transaction monitoring", "status": "operational" } ], "incidents": [] } } } } } }, "429": { "description": "来自同一 IP 地址（或同一 API 密钥，如果您发送了密钥）的 GET 请求在一分钟内超过 600 次。重试前请遵循 `Retry-After`。", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string" } } }, "example": { "detail": "GET request rate limit exceeded. You can make up to 600 requests per minute." } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -fsS https://verification.didit.me/v3/status/" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresp = requests.get('https://verification.didit.me/v3/status/', timeout=5)\nresp.raise_for_status()\nfeed = resp.json()\nprint(feed['status'])\nfor service in feed['services']:\n if service['status'] != 'operational':\n print(service['key'], service['status'])" }, { "lang": "javascript", "label": "JavaScript", "source": "const feed = await fetch('https://verification.didit.me/v3/status/').then((r) => r.json());\nconsole.log(feed.status);\nconst affected = feed.services.filter((s) => s.status !== 'operational');\nconsole.log(affected.map((s) => `${s.key}: ${s.status}`));" } ], "x-didit-sdk": { "resource": "system", "method": "retrieve_status", "auth": "public", "server": false } } }, "/v3/organization/bank-verification-pricing/": { "get": { "summary": "获取银行验证价格（公开、未认证）", "description": "返回每个国家/地区中每种银行验证方式的标价：银行登录及其余额和交易附加功能，以及账户核验。某国家/地区当前不提供的方式将显示为不可用且没有价格。可用于在构建工作流前为银行步骤进行报价，或在您自己的产品中展示银行价格。\n\n公开：无需发送认证请求头。响应中不包含任何组织数据，对所有调用方均相同。该响应会在公共端缓存一小时并携带 `ETag`，因此在内容未发生变化时发送 `If-None-Match` 可收到 `304 Not Modified`。\n\n某种方式仅在 Didit 当前生产环境支持的国家/地区处于 `available` 状态，而在其他所有地方其 `price_usd` 均为 `null`，因此该信息流绝不会显示您无法购买的价格。`available: false` 涵盖没有核准价格的国家/地区、该国家/地区不支持的方式，以及尚未启用的路由。\n\n这些是计入套餐折扣前的标价。您的套餐折扣适用于整个银行价格，如果您的组织拥有协商价格或合同价格，则将替代标价。", "operationId": "get_v3_bank_verification_pricing", "tags": [ "Pricing" ], "security": [ {} ], "parameters": [], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -fsS https://verification.didit.me/v3/organization/bank-verification-pricing/" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# This call needs no API key.\nclient = Didit()\n\nresult = client.pricing.bank_verification()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// This call needs no API key.\nconst didit = new Didit();\n\nconst result = await didit.pricing.bankVerification();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// This call needs no API key.\nclient := didit.NewClient()\n\nresult, err := client.Pricing.BankVerification(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// This call needs no API key.\nDidit client = new Didit();\n\nvar result = client.pricing().bankVerification();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "pricing->bankVerification();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# This call needs no API key.\ndidit = Didit::Client.new\n\nresult = didit.pricing.bank_verification\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// This call needs no API key.\nusing var client = new DiditClient();\n\nvar result = await client.Pricing.BankVerificationAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "pricing", "method": "bank_verification", "auth": "none", "server": true }, "responses": { "200": { "description": "按国家/地区划分的银行验证标价。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BankVerificationPricing" }, "examples": { "Two countries": { "summary": "一个支持两种方式的国家/地区，一个两种方式均不支持的国家/地区", "value": { "currency": "USD", "statement_upload": { "price_usd": "0.0000", "included_after_charged_bank_attempt": true, "standalone_available": false }, "own_provider_fee_usd": "0.0200", "countries": { "GBR": { "name": "United Kingdom", "methods": { "open_banking": { "available": true, "market": "UK and EEA", "price_usd": "0.7900", "add_ons": { "balance": "0.3500", "transactions": "1.3000" } }, "account_lookup": { "available": true, "price_usd": "0.4000" } } }, "CAN": { "name": "Canada", "methods": { "open_banking": { "available": false, "market": null, "price_usd": null, "add_ons": {} }, "account_lookup": { "available": false, "price_usd": null } } } } } } } } } }, "304": { "description": "未修改：您在 `If-None-Match` 中发送的 `ETag` 仍然匹配。无响应体。" } } } }, "/v3/session/{sessionId}/simulate/": { "post": { "summary": "模拟沙盒会话的状态", "description": "在事后从您的后端强制设置沙盒会话的最终状态，无需运行流程。仅限沙盒应用：生产环境会话将返回 `404`。适用于用户验证（KYC）和企业验证（KYB）会话。\n\n设置 `new_status`，或通过 `scenario` 或 `risk` 来提供该状态。`risk`（或场景魔法值携带的第一个风险）会向该会话添加相应的警告。该变更会记录在会话的活动日志中。\n\n`send_webhooks`（默认为 `true`）会精确发送真实状态变更所触发的 Webhook。设为 `false` 时，状态依然会变更且控制台依然实时更新，但不会记录或发送任何 Webhook，遗漏 Webhook 恢复机制也绝不会重发该决策，随后的状态变更则照常发送 Webhook。响应将回显所应用的值。\n\n需要 `write:sessions` 权限；限定范围的 API 密钥需要对会话具有写入权限。未知的 `session_id` 返回 `404`，其他应用的会话返回 `403`，这两者均在读取请求体之前发生；生产环境会话仅在验证请求体之后才返回 `404`。若要使用会话自身的 token 从托管流程中进行模拟，请使用 `POST /v3/session/{sessionId}/sandbox/simulate/`。请参阅[沙盒与测试数据](/zh/integration/sandbox-testing)获取场景目录。", "operationId": "post_v3_session_simulate", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "沙盒验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID。", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateRequest" }, "examples": { "Scenario Without Webhooks": { "summary": "通过场景拒绝，不发送 Webhook", "value": { "scenario": "decline_aml_hit", "send_webhooks": false } }, "Status Only": { "summary": "批准并发送常规 Webhook", "value": { "new_status": "Approved" } } } } } }, "responses": { "200": { "description": "状态已更改。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateResponse" }, "examples": { "Simulated": { "summary": "通过场景拒绝，未发送 Webhook", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "previous_status": "In Progress", "status": "Declined", "scenario": "decline_aml_hit", "risk": "POSSIBLE_MATCH_FOUND", "send_webhooks": false } } } } } }, "400": { "description": "验证错误：未知的场景或风险、当 `scenario` 和 `risk` 均未提供时缺少 `new_status`、该 endpoint 不设置的状态，或者会话已处于所请求的状态（裸 JSON 数组）。", "content": { "application/json": { "examples": { "Unknown Scenario": { "summary": "scenario 不在目录中", "value": { "scenario": [ "Unknown sandbox scenario: 'not-a-scenario'." ] } }, "Unknown Risk": { "summary": "risk 不在目录中", "value": { "risk": [ "Unknown sandbox risk case: 'NOT_A_RISK'." ] } }, "Missing new_status": { "summary": "无 new_status、scenario 或 risk", "value": { "new_status": [ "This field is required." ] } }, "Invalid new_status": { "summary": "模拟未设置的状态", "value": { "new_status": [ "\"Resubmitted\" is not a valid choice." ] } }, "Same Status": { "summary": "会话已处于此状态", "value": [ "The new status is the same as the current status." ] } } } } }, "401": { "description": "作用域 API 密钥已过期。", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "已过有效期的作用域 API 密钥", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少凭据、调用方没有 `write:sessions` 权限、限定范围的 API 密钥缺少此 endpoint 所需的访问权限，或者 `session_id` 属于另一个应用。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "调用方缺少 write:sessions 权限", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "没有此访问权限的作用域 API 密钥", "value": { "detail": "This API key has no write access to sessions." } } } } } }, "404": { "description": "不存在具有此 `session_id` 的会话，或者该会话是生产环境（非沙盒）会话。", "content": { "application/json": { "examples": { "Not Found": { "summary": "未知会话或正在进行的会话", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/simulate/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"scenario\": \"decline_aml_hit\", \"send_webhooks\": false}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.simulate(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n scenario=\"decline_aml_hit\",\n send_webhooks=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.simulate(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n scenario: \"decline_aml_hit\",\n send_webhooks: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Simulate(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.SandboxSimulateRequest{\n\tScenario: didit.String(\"decline_aml_hit\"),\n\tSendWebhooks: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SandboxSimulateRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().simulate(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", SandboxSimulateRequest.builder()\n .scenario(\"decline_aml_hit\")\n .sendWebhooks(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->simulate('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'scenario' => 'decline_aml_hit',\n 'send_webhooks' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.simulate(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n scenario: \"decline_aml_hit\",\n send_webhooks: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.SimulateAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new SandboxSimulateRequest\n{\n Scenario = \"decline_aml_hit\",\n SendWebhooks = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "simulate", "auth": "api_key", "server": true } } }, "/v3/session/{sessionId}/sandbox/simulate/": { "post": { "summary": "从客户端模拟沙盒会话的状态", "description": "与 `POST /v3/session/{sessionId}/simulate/` 相同的模拟，使用会话自身的 `Session-Token`（由 [创建会话](/zh/sessions-api/create-session) 在 `session_token` 中返回）进行身份验证，而不是您的 API 密钥，以便测试工具或托管流程可以从客户端调用它。请求体、响应和 `send_webhooks` 的行为与该 endpoint 完全一致。\n\n生产环境（非沙盒）应用的 `Session-Token`，或者与路径中的 `sessionId` 不匹配的 token，将返回 `404`。请参阅 [沙盒与测试数据](/zh/integration/sandbox-testing)。", "operationId": "post_v3_session_sandbox_simulate", "tags": [ "Sessions" ], "security": [ { "SessionTokenAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "沙盒验证会话的 UUID。必须与用于身份验证的 Session-Token 中编码的会话匹配。", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateRequest" }, "examples": { "Scenario Without Webhooks": { "summary": "通过场景拒绝，不发送 Webhook", "value": { "scenario": "decline_aml_hit", "send_webhooks": false } }, "Status Only": { "summary": "批准并发送常规 Webhook", "value": { "new_status": "Approved" } } } } } }, "responses": { "200": { "description": "状态已更改。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxSimulateResponse" }, "examples": { "Simulated": { "summary": "通过场景拒绝，未发送 Webhook", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "previous_status": "In Progress", "status": "Declined", "scenario": "decline_aml_hit", "risk": "POSSIBLE_MATCH_FOUND", "send_webhooks": false } } } } } }, "400": { "description": "验证错误：未知的场景或风险、当 `scenario` 和 `risk` 均未提供时缺少 `new_status`、该 endpoint 不设置的状态，或者会话已处于所请求的状态（裸 JSON 数组）。", "content": { "application/json": { "examples": { "Unknown Scenario": { "summary": "scenario 不在目录中", "value": { "scenario": [ "Unknown sandbox scenario: 'not-a-scenario'." ] } }, "Unknown Risk": { "summary": "risk 不在目录中", "value": { "risk": [ "Unknown sandbox risk case: 'NOT_A_RISK'." ] } }, "Missing new_status": { "summary": "无 new_status、scenario 或 risk", "value": { "new_status": [ "This field is required." ] } }, "Invalid new_status": { "summary": "模拟未设置的状态", "value": { "new_status": [ "\"Resubmitted\" is not a valid choice." ] } }, "Same Status": { "summary": "会话已处于此状态", "value": [ "The new status is the same as the current status." ] } } } } }, "403": { "description": "`Session-Token` 请求头缺失或无效。", "content": { "application/json": { "examples": { "Invalid Session Token": { "summary": "缺少或无效的 Session-Token", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "`Session-Token` 属于生产环境（非沙盒）应用，或与路径中的 `sessionId` 不匹配。", "content": { "application/json": { "examples": { "Not Found": { "summary": "活跃会话，或 session_id / token 不匹配", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/sandbox/simulate/ \\\n -H 'Session-Token: YOUR_SESSION_TOKEN' \\\n -H 'Content-Type: application/json' \\\n -d '{\"new_status\": \"Approved\", \"send_webhooks\": false}'" }, { "lang": "python", "label": "Python", "source": "import requests\n\nresponse = requests.post(\n \"https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/sandbox/simulate/\",\n headers={\"Session-Token\": \"YOUR_SESSION_TOKEN\"},\n json={\"new_status\": \"Approved\", \"send_webhooks\": False},\n)\nresponse.raise_for_status()\nprint(response.json())" } ], "x-didit-sdk": { "resource": "sessions", "method": "simulate_sandbox", "auth": "device_token", "server": false } } }, "/v3/session/{sessionId}/features/overrides/": { "get": { "summary": "列出会话的检查覆盖项", "description": "对用户验证（KYC）或企业验证（KYB）会话中单个功能（步骤）状态的每次覆盖，最新的排在最前且不分页：已应用的、等待用户完成流程的（`pending_until_flow_finishes`）以及已取消的，每项都包含请求者、原因以及是否在用户仍在流程中时应用（`forced`）。\n\n`person_in_flow` 会告知您带有 `defer_until_flow_finishes: true` 的新覆盖是否会处于等待状态。`flow_finished_at` 是用户最后一次完成流程的时间；如果他们仍在流程中（包括重新提交）或会话在他们完成前已关闭，则为 `null`。\n\n需要 `read:sessions` 权限；受限的 API 密钥需要对决策拥有读取权限。", "operationId": "get_v3_session_feature_overrides", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID。", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "responses": { "200": { "description": "会话的检查覆盖记录，最新的排在最前。", "content": { "application/json": { "schema": { "type": "object", "required": [ "session_id", "person_in_flow", "flow_finished_at", "overrides" ], "properties": { "session_id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "person_in_flow": { "type": "boolean", "description": "该人员是否仍在流程中，因此带有 `defer_until_flow_finishes: true` 的新覆盖操作将等待。", "example": true }, "flow_finished_at": { "type": "string", "format": "date-time", "nullable": true, "description": "当事人最后一次完成流程的时间。当其仍在流程中（包括重新提交）以及会话在完成前已关闭（已放弃、已过期或在流程中做出决策）时为 `null`。", "example": null }, "overrides": { "type": "array", "description": "该会话的每次覆盖，最新的排在最前。", "items": { "$ref": "#/components/schemas/FeatureStatusOverride" } } } }, "examples": { "Overrides": { "summary": "一个处于等待状态的覆盖项，一个已应用的覆盖项", "value": { "session_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "person_in_flow": true, "flow_finished_at": null, "overrides": [ { "id": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3", "node_id": "feature_liveness_1", "feature_type": "", "feature_model": "Face", "previous_status": "Declined", "new_status": "Approved", "state": "pending_until_flow_finishes", "forced": false, "reason": "Liveness retried with a reviewer present.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": null, "cancelled_at": null, "cancel_reason": null }, { "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "node_id": "feature_ocr_1", "feature_type": "", "feature_model": "KYC", "previous_status": "In Review", "new_status": "Approved", "state": "applied", "forced": true, "reason": "Document manually verified by compliance.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": "2026-10-13T09:15:00Z", "cancelled_at": null, "cancel_reason": null } ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "已过有效期的作用域 API 密钥", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少凭据、调用方没有 `read:sessions` 权限、限定范围的 API 密钥缺少此 endpoint 所需的访问权限，或者 `session_id` 属于另一个应用。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "调用方缺少 read:sessions 权限", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "没有此访问权限的作用域 API 密钥", "value": { "detail": "This API key has no read access to decisions." } } } } } }, "404": { "description": "不存在具有此 `session_id` 的 KYC 或 KYB 会话。", "content": { "application/json": { "examples": { "Not Found": { "summary": "未知的 session_id", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/features/overrides/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.list_feature_overrides(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listFeatureOverrides(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListFeatureOverrides(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().listFeatureOverrides(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listFeatureOverrides('3fa85f64-5717-4562-b3fc-2c963f66afa6');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_feature_overrides(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListFeatureOverridesAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "list_feature_overrides", "auth": "api_key", "server": true } } }, "/v3/session/{sessionId}/features/overrides/{overrideId}/cancel/": { "post": { "summary": "取消等待流程完成的检查覆盖", "description": "取消仍处于 `pending_until_flow_finishes` 状态的功能（步骤）状态覆盖，使其永不生效。该检查保持其原有状态，取消操作会在会话活动中记录为 `FEATURE_OVERRIDE_CANCELLED`，且不会发送 Webhook。响应为带有 `state: cancelled` 和 `cancel_reason: cancelled_by_reviewer` 的覆盖对象。\n\n已生效或已被取消的覆盖将返回 `409` 及错误代码 `feature_override_not_pending`。可通过 `GET /v3/session/{sessionId}/features/overrides/` 或功能状态更新返回的 `override` 中查找覆盖 ID。\n\n需要 `write:sessions` 权限；受范围限制的 API 密钥需要对 decisions 具有写入权限。", "operationId": "post_v3_session_feature_override_cancel", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID。", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } }, { "in": "path", "name": "overrideId", "required": true, "description": "要取消的覆盖项 `id`。", "schema": { "type": "string", "format": "uuid", "example": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3" } } ], "responses": { "200": { "description": "覆盖已取消，且永不生效。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FeatureStatusOverride" }, "examples": { "Cancelled": { "summary": "已取消的覆盖", "value": { "id": "9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3", "node_id": "feature_liveness_1", "feature_type": "", "feature_model": "Face", "previous_status": "Declined", "new_status": "Approved", "state": "cancelled", "forced": false, "reason": "Liveness retried with a reviewer present.", "requested_by": { "email": "reviewer@example.com", "name": "Alex Reviewer", "type": "CONSOLE_USER" }, "requested_at": "2026-10-13T09:15:00Z", "applied_at": null, "cancelled_at": "2026-10-13T09:20:00Z", "cancel_reason": "cancelled_by_reviewer" } } } } } }, "401": { "description": "作用域 API 密钥已过期。", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "已过有效期的作用域 API 密钥", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少凭据、调用方没有 `write:sessions` 权限、限定范围的 API 密钥缺少此 endpoint 所需的访问权限，或者 `session_id` 属于另一个应用。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "调用方缺少 write:sessions 权限", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "没有此访问权限的作用域 API 密钥", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "不存在具有此 `session_id` 的 KYC 或 KYB 会话，或者该会话不存在具有此 `overrideId` 的覆盖配置。", "content": { "application/json": { "examples": { "Not Found": { "summary": "未知的 session_id", "value": { "detail": "Not found." } }, "Override Not Found": { "summary": "该会话中不存在具有此 id 的覆盖项", "value": { "detail": "Override not found." } } } } } }, "409": { "description": "覆盖已应用或已被取消。", "content": { "application/json": { "examples": { "Not Pending": { "summary": "只有等待中的覆盖才能被取消", "value": { "detail": "This override is no longer pending: it already applied or was cancelled.", "code": "feature_override_not_pending" } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/features/overrides/9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3/cancel/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.cancel_feature_override(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.cancelFeatureOverride(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.CancelFeatureOverride(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().cancelFeatureOverride(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->cancelFeatureOverride('3fa85f64-5717-4562-b3fc-2c963f66afa6', '9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.cancel_feature_override(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.CancelFeatureOverrideAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", \"9b2f4c1e-8d3a-4e5f-a6b7-c8d9e0f1a2b3\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "cancel_feature_override", "auth": "api_key", "server": true } } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/add/": { "post": { "summary": "向网络添加标签", "description": "将您应用的一个标签添加到网络中。返回网络详情，其中的 `tags` 会列出您的应用在该网络上的标签。若标签为新增则返回 `201`，若标签已存在于网络上则返回 `200`。属于其他应用或不存在的标签将返回 404 `Tag not found.`。需要完全访问权限的 API 密钥，或者控制台成员具有 `write:networks` 权限。", "operationId": "add_network_tag", "tags": [ "Networks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "description": "网络 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkTagRequest" }, "example": { "tag_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/3fa85f64-5717-4562-b3fc-2c963f66afa6/tags/add/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"tag_uuid\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.add_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid=\"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.addTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.AddTag(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.NetworkTagRequest{\n\tTagUUID: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.NetworkTagRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().addTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", NetworkTagRequest.builder()\n .tagUuid(\"7c9e6679-7425-40de-944b-e07fc1f90ae7\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->addTag('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'tag_uuid' => '7c9e6679-7425-40de-944b-e07fc1f90ae7',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.add_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.AddTagAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new NetworkTagRequest\n{\n TagUuid = \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "标签已添加。返回网络详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [ { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "SUSPICIOUS", "color": "#6366F1", "source": "custom", "added_by": null, "added_at": "2026-10-13T08:15:00Z" } ], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "200": { "description": "该标签已存在于网络中并保持原样。返回网络详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [ { "uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7", "name": "SUSPICIOUS", "color": "#6366F1", "source": "custom", "added_by": null, "added_at": "2026-10-13T08:15:00Z" } ], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "400": { "description": "无效的请求体：缺少 `tag_uuid` 或其不是 UUID。", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_uuid": { "type": "array", "items": { "type": "string" } } } }, "examples": { "Missing tag_uuid": { "summary": "缺少 tag_uuid", "value": { "tag_uuid": [ "This field is required." ] } }, "Invalid tag_uuid": { "summary": "无效的 tag_uuid", "value": { "tag_uuid": [ "Must be a valid UUID." ] } } } } } }, "401": { "description": "凭据缺失或无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Missing or invalid credentials": { "summary": "凭据缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "API 密钥属于另一个应用，或者是一个访问权限受限的密钥：Networks endpoint 需要具有完全访问权限的密钥。控制台成员 token 需要 `write:networks` 权限。若组织未启用 Networks，也会返回 `code: networks_not_entitled`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Networks not enabled": { "summary": "网络未启用", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "受限的 API 密钥", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "无权限", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未找到。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Network not found": { "summary": "未找到网络", "value": { "detail": "Network not found." } }, "Tag not found": { "summary": "未找到标签", "value": { "detail": "Tag not found." } } } } } } }, "x-didit-sdk": { "resource": "networks", "method": "add_tag", "auth": "api_key", "server": true, "scope": "application" } } }, "/v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/tags/remove/": { "post": { "summary": "从网络中移除标签", "description": "从网络中移除您应用的一个标签。返回网络详情。如果标签不在该网络上，或不属于您的应用，则返回 404。需要完全访问权限的 API 密钥，或者控制台成员需具备 `write:networks` 权限。", "operationId": "remove_network_tag", "tags": [ "Networks" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" }, { "name": "network_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "description": "网络 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkTagRequest" }, "example": { "tag_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/networks/3fa85f64-5717-4562-b3fc-2c963f66afa6/tags/remove/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"tag_uuid\": \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.networks.remove_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid=\"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.networks.removeTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Networks.RemoveTag(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.NetworkTagRequest{\n\tTagUUID: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.NetworkTagRequest;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.networks().removeTag(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", NetworkTagRequest.builder()\n .tagUuid(\"7c9e6679-7425-40de-944b-e07fc1f90ae7\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "networks->removeTag('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'tag_uuid' => '7c9e6679-7425-40de-944b-e07fc1f90ae7',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.networks.remove_tag(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n tag_uuid: \"7c9e6679-7425-40de-944b-e07fc1f90ae7\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Networks.RemoveTagAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new NetworkTagRequest\n{\n TagUuid = \"7c9e6679-7425-40de-944b-e07fc1f90ae7\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "标签已从网络中移除。返回网络详情。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NetworkDetailResponse" }, "example": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "network_id": "N-0042", "name": null, "status": "in_review", "risk": { "score": 82, "band": "high", "bar": 0.82 }, "pattern_types": [ "exact_same_device", "same_email" ], "signal_types": [ "device", "email" ], "member_counts": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signal_coverage": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } }, "first_activity_at": "2026-10-01T09:12:44Z", "last_activity_at": "2026-10-12T16:03:10Z", "stats": { "members": { "total": 3, "users": 3, "businesses": 0, "transaction_parties": 0 }, "member_status": { "approved": 1, "declined": 1, "in_review": 0, "not_completed": 1 }, "signals": { "total": 2, "by_type": { "device": { "signals": 1, "subjects": 3, "coverage": 1.0 }, "email": { "signals": 1, "subjects": 2, "coverage": 0.6667 } } } }, "fraud_tags": [], "risk_signals": { "residential_proxy_reuse": { "detected": false, "signal_count": 0, "max_subject_count": 0 }, "email_intelligence": { "enriched_signal_count": 1, "high_risk_count": 0, "social_profile_count": 0 }, "phone_intelligence": { "enriched_signal_count": 0, "high_risk_count": 0 } }, "reviewed_at": "2026-10-12T16:30:00Z", "reviewed_by": "reviewer@example.com", "review_reason": "Shared device across three new accounts.", "notes_count": 0, "sharing_mode": "global", "cross_org_available": true, "cross_org_unavailable_reason": null, "tags": [], "outcomes": { "approved": 1, "declined": 1, "in_review": 0, "total": 3 }, "patterns": [ { "type": "background", "score": 0.8125, "members": 3, "reason": null, "computed_at": "2026-10-13T08:00:00Z" } ] } } } }, "400": { "description": "无效的请求体：缺少 `tag_uuid` 或其不是 UUID。", "content": { "application/json": { "schema": { "type": "object", "properties": { "tag_uuid": { "type": "array", "items": { "type": "string" } } } }, "examples": { "Missing tag_uuid": { "summary": "缺少 tag_uuid", "value": { "tag_uuid": [ "This field is required." ] } }, "Invalid tag_uuid": { "summary": "无效的 tag_uuid", "value": { "tag_uuid": [ "Must be a valid UUID." ] } } } } } }, "401": { "description": "凭据缺失或无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Missing or invalid credentials": { "summary": "凭据缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } } } } } }, "403": { "description": "API 密钥属于另一个应用，或者是一个访问权限受限的密钥：Networks endpoint 需要具有完全访问权限的密钥。控制台成员 token 需要 `write:networks` 权限。若组织未启用 Networks，也会返回 `code: networks_not_entitled`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Networks not enabled": { "summary": "网络未启用", "value": { "detail": "Networks is disabled for this organization. Contact Didit support if you believe this is an error.", "code": "networks_not_entitled" } }, "Restricted API key": { "summary": "受限的 API 密钥", "value": { "detail": "This API key has no access to this endpoint." } }, "No permission": { "summary": "无权限", "value": { "detail": "You do not have permission to perform this action." } } } } } }, "404": { "description": "未找到。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "description": "在带代码的错误中存在，例如 `networks_not_entitled`。" } } }, "examples": { "Network not found": { "summary": "未找到网络", "value": { "detail": "Network not found." } }, "Tag not found": { "summary": "未找到标签", "value": { "detail": "Tag not found." } }, "Tag not on the network": { "summary": "网络上不存在该标签", "value": { "detail": "This tag is not on the network." } } } } } } }, "x-didit-sdk": { "resource": "networks", "method": "remove_tag", "auth": "api_key", "server": true, "scope": "application" } } }, "/v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/requests/{request_uuid}/remind/": { "post": { "summary": "提醒客户有关请求", "description": "重新向同一个已核验的收件人发送处于等待状态的客户请求邮件，内容保持不变。您最多每 24 小时对一个请求提醒一次。提醒不会更改任何其他内容：请求保留其截止日期，案件保留其状态。每次提醒都会作为 action 为 `reminded` 的 CUSTOMER_REQUEST 事件记录在案件中。响应中的 `delivery_status` 表示此提醒的投递结束状态：SENT、SIMULATED（邮件未发送）或 UNKNOWN（邮件可能已被接收；不会自动重新发送）。`next_reminder_at` 是您可以再次对此请求进行提醒的时间。当客户已不再有该请求可供回复时返回 409 及 `reason`；如果在过去 24 小时内已提醒过该请求，则返回 429 及 `retry_at` 和 `Retry-After` 请求头。需要 `write:cases` 权限。", "operationId": "organization_application_cases_requests_remind_create", "parameters": [ { "in": "path", "name": "organization_id", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "组织 UUID。" }, { "in": "path", "name": "application_id", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "应用 UUID。" }, { "in": "path", "name": "case_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "案件 UUID。" }, { "in": "path", "name": "request_uuid", "schema": { "type": "string", "format": "uuid" }, "required": true, "description": "客户请求 UUID，来自案件的请求列表。" } ], "tags": [ "Case Management" ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/cases/c1a5e000-0000-4000-8000-000000000001/requests/3fa85f64-5717-4562-b3fc-2c963f66afa6/remind/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nresult = client.cases.requests.remind(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nconst result = await didit.cases.requests.remind(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nclient := didit.NewClient()\n\nresult, err := client.Cases.Requests.Remind(ctx, \"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nvar result = client.cases().requests().remind(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "cases->requests->remind('11111111-2222-3333-4444-555555555555', '11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\nresult = didit.cases.requests.remind(\n \"11111111-2222-3333-4444-555555555555\",\n \"11111111-2222-3333-4444-555555555555\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nvar result = await client.Cases.Requests.RemindAsync(\"11111111-2222-3333-4444-555555555555\", \"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "提醒已记录，且已发送对应电子邮件。", "content": { "application/json": { "schema": { "type": "object", "required": [ "request", "reminded_at", "delivery_status", "next_reminder_at" ], "properties": { "request": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" }, "reminded_at": { "type": "string", "format": "date-time", "description": "记录此提醒的时间。" }, "delivery_status": { "type": "string", "enum": [ "SENT", "SIMULATED", "UNKNOWN" ], "description": "此提醒的投递结束状态。SIMULATED：邮件未发送。UNKNOWN：邮件可能已被接收；不会自动重新发送。" }, "next_reminder_at": { "type": "string", "format": "date-time", "description": "您可以再次对该请求发送提醒的时间：`reminded_at` 加上 24 小时。" } } }, "example": { "request": { "uuid": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "purpose": "confirm_details", "language": "en", "recipient": "customer@example.com", "expires_at": "2026-10-20T09:00:00Z", "actor_email": "reviewer@example.com", "delivery_status": "SENT", "delivered_at": "2026-10-13T09:00:04Z", "cancelled_at": null, "responded_at": null, "response": null, "has_attachment": false, "created_at": "2026-10-13T09:00:00Z" }, "reminded_at": "2026-10-14T10:30:00Z", "delivery_status": "SENT", "next_reminder_at": "2026-10-15T10:30:00Z" } } } }, "400": { "description": "该案件有待批准的决议。请求体为一个字符串列表。", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "Customer messages require an active case without a pending resolution." ] } } }, "403": { "description": "调用方缺少必需的案件权限。" }, "404": { "description": "此调用方无法访问该请求或案件。" }, "409": { "description": "该请求不再等待客户操作，因此无需向其发送提醒。`reason` 说明了原因：`answered`（客户已回复）、`cancelled`、`expired`、`closed`（请求发出后案件已解决，即使之后重新打开）、`not_actionable`（进行中的审核更新不要求任何操作）、`not_delivered`（第一封邮件尚未发出）或 `contact_unavailable`（已验证的邮箱不再可用）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "case_request_not_waiting" ] }, "reason": { "type": "string", "enum": [ "answered", "cancelled", "expired", "closed", "not_actionable", "not_delivered", "contact_unavailable" ] } } }, "example": { "detail": "This request no longer waits on the customer, so there is nothing to remind them of.", "code": "case_request_not_waiting", "reason": "answered" } } } }, "429": { "description": "过去 24 小时内已就该请求发送过提醒。`retry_at` 和 `Retry-After` 请求头指明了您何时可以再次提醒。", "headers": { "Retry-After": { "description": "再次对该请求发送提醒前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 3600 } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "case_request_reminder_too_soon" ] }, "retry_at": { "type": "string", "format": "date-time" } } }, "example": { "detail": "This request was already reminded in the last 24 hours.", "code": "case_request_reminder_too_soon", "retry_at": "2026-10-15T10:30:00Z" } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-didit-sdk": { "resource": "cases.requests", "method": "remind", "auth": "api_key", "server": true, "scope": "application" } } }, "/v3/session/{sessionId}/decision-email-preview/": { "post": { "summary": "预览会话的决策电子邮件", "description": "渲染当您使用 `send_email: true` 将会话设置为 `Approved` 或 `Declined` 时该人员收到的电子邮件，而无需更改会话或发送任何内容。响应将准确显示发送的主题和 HTML、收件人、发件人、语言，以及确认更改是否会真正发送电子邮件（`will_be_sent`、`not_sent_reason`）。\n\n收件人是该人员自己的地址：他们在工作流的邮箱验证步骤中核验的地址，或者是在创建会话时在 `contact_details` 中提供的地址。发件人是在适用白标时您应用的已验证发件人域名（`sender_kind: customer`），否则为 Didit 的发件人（`sender_kind: didit`）。\n\n要准确发送您预览的内容，请调用[更新会话状态](/zh/sessions-api/update-status)，传入相同的 `new_status`、`send_email: true`、将 `email_address` 设置为 `recipient`、`email_language` 设置为 `language` 并将 `email_preview_token` 设置为 `preview_token`。凭证将在 15 分钟后过期。如果收件人、语言、会话状态、发件人或电子邮件自预览以来发生更改，则更新将在发生任何更改之前返回 `409`；请重新预览并使用新凭证进行确认。\n\n适用于处于 `Approved`、`Declined`、`In Review`、`Kyc Expired`、`Abandoned` 或 `Resubmitted` 状态的用户验证（KYC）和企业验证（KYB）会话。状态检查在请求体验证之前运行。需要 `write:sessions` 权限；受限 API 密钥需要对决策的写入权限。响应使用 `Cache-Control: no-store`：请将其视为敏感验证内容。", "operationId": "post_v3_session_decision_email_preview", "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "in": "path", "name": "sessionId", "required": true, "description": "验证会话的 UUID。支持用户（KYC）和企业（KYB）会话 ID。", "schema": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "new_status" ], "properties": { "new_status": { "type": "string", "enum": [ "Approved", "Declined" ], "description": "您想要预览其邮件的决策。", "example": "Approved" }, "email_language": { "type": "string", "default": "en", "description": "邮件语言，默认值与“更新会话状态”相同。未提供的语言将回退为英语；响应中的 `language` 会指明所使用的语言。", "example": "en" } } }, "examples": { "Approved": { "summary": "预览英文版“已通过”电子邮件", "value": { "new_status": "Approved" } }, "Declined in Spanish": { "summary": "预览西班牙语版“已拒绝”电子邮件", "value": { "new_status": "Declined", "email_language": "es" } } } } } }, "responses": { "200": { "description": "仅供预览。会话保持不变且不会发送电子邮件。", "headers": { "Cache-Control": { "description": "始终为 `no-store`：预览包含验证内容，切勿缓存。", "schema": { "type": "string", "example": "no-store" } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "recipient", "recipient_source", "sender", "sender_name", "sender_email", "sender_kind", "subject", "html", "text", "language", "will_be_sent", "not_sent_reason", "preview_token" ], "properties": { "recipient": { "type": "string", "description": "邮件发送的目标地址。若该人员无已知地址，则为空字符串：此时无法发送邮件，且 `preview_token` 同样为空。确认时请将其作为 `email_address` 传递。", "example": "person@example.com" }, "recipient_source": { "type": "string", "enum": [ "email_verification", "contact_details", "" ], "description": "`recipient` 的来源。`email_verification`：用户在流程的邮箱验证步骤中验证的地址。`contact_details`：创建会话时在 `contact_details` 中提供的地址。没有地址时为空字符串。", "example": "email_verification" }, "sender": { "type": "string", "description": "发送邮件时使用的 `From` 请求头。", "example": "Example App " }, "sender_name": { "type": "string", "description": "`sender` 的显示名称部分。", "example": "Example App" }, "sender_email": { "type": "string", "format": "email", "description": "`sender` 的地址部分。", "example": "no-reply@mail.example.com" }, "sender_kind": { "type": "string", "enum": [ "customer", "didit" ], "description": "`customer`：邮件从您应用的已验证发送方域名发出（白标）。`didit`：从 Didit 自己的发送方发出。", "example": "customer" }, "subject": { "type": "string", "description": "与发送时完全一致的主题行。", "example": "Your verification has been approved in Example App" }, "html": { "type": "string", "description": "发送时完全一致的电子邮件 HTML，其徽标作为 data URL 嵌入。请在沙盒 frame 中渲染，切勿直接在您的应用 DOM 中渲染。", "example": "..." }, "text": { "type": "string", "description": "电子邮件的纯文本内容，与该用户的“消息”会话中保留的一致，用于紧凑预览（HTML 仍为该用户收到的电子邮件形式）。", "example": "Verification Approved\n\nYour identity has been successfully verified with Acme Pay. No further action is needed on your part." }, "language": { "type": "string", "description": "邮件所用的语言。如果您请求的 `email_language` 不支持，则为英语（`en`）。", "example": "en" }, "will_be_sent": { "type": "boolean", "description": "使用 `send_email: true` 确认更改是否会发送此电子邮件。当设置了 `not_sent_reason` 时为 `false`。", "example": true }, "not_sent_reason": { "type": "string", "nullable": true, "enum": [ "status_unchanged", "notification_emails_disabled", "no_recipient", "sandbox", null ], "description": "确认操作不会发送电子邮件的原因；若将发送邮件，则为 `null`。`status_unchanged`：会话已处于该状态，因此更新未做任何更改且不会发送任何内容。`notification_emails_disabled`：创建会话时未设置 `contact_details.send_notification_emails: true`，因此不会向 `contact_details` 中提供的地址发送决策电子邮件。`no_recipient`：未获取到该人员的地址。`sandbox`：属于沙盒会话且收件人未选择接收沙盒邮件投递，因此仅模拟发送。", "example": null }, "preview_token": { "type": "string", "description": "此特定邮件的签名收据，有效期为 15 分钟。将其作为 `email_preview_token` 传递给[更新会话状态](/zh/sessions-api/update-status)。当没有收件人时为空字符串。", "example": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } } }, "examples": { "Will Be Sent": { "summary": "“已通过”邮件将发送至在流程中验证的邮箱地址", "value": { "recipient": "person@example.com", "recipient_source": "email_verification", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Your verification has been approved in Example App", "html": "...", "language": "en", "will_be_sent": true, "not_sent_reason": null, "preview_token": "eyJkaWdlc3QiOiI0ZjJhIn0:1uExAm:Pl3x4mpleS1gnatureValue000000000000000" } }, "No Recipient": { "summary": "该人员没有已知的地址", "value": { "recipient": "", "recipient_source": "", "sender": "Example App ", "sender_name": "Example App", "sender_email": "no-reply@mail.example.com", "sender_kind": "customer", "subject": "Your verification has been declined in Example App", "html": "...", "language": "en", "will_be_sent": false, "not_sent_reason": "no_recipient", "preview_token": "" } } } } } }, "400": { "description": "会话未处于此 endpoint 接受的状态（`{\"detail\": ...}`），或请求体无效（`{\"\": [\"\"]}`）。", "content": { "application/json": { "examples": { "Wrong Current Status": { "summary": "会话不处于此 endpoint 接受的状态", "value": { "detail": "Only sessions with status Approved, Declined, In Review, Kyc Expired, Abandoned, Resubmitted can be updated. Current status: In Progress" } }, "Invalid new_status": { "summary": "new_status 不是 Approved 或 Declined", "value": { "new_status": [ "\"Resubmitted\" is not a valid choice." ] } }, "Missing new_status": { "summary": "遗漏了必填字段", "value": { "new_status": [ "This field is required." ] } } } } } }, "401": { "description": "作用域 API 密钥已过期。", "content": { "application/json": { "examples": { "Expired API Key": { "summary": "已过有效期的作用域 API 密钥", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "缺少凭据、调用方没有 `write:sessions` 权限、限定范围的 API 密钥缺少此 endpoint 所需的访问权限，或者 `session_id` 属于另一个应用。", "content": { "application/json": { "examples": { "Invalid Credentials": { "summary": "x-api-key 缺失或无效", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Missing Privilege": { "summary": "调用方缺少 write:sessions 权限", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped Key Without Access": { "summary": "没有此访问权限的作用域 API 密钥", "value": { "detail": "This API key has no write access to decisions." } } } } } }, "404": { "description": "不存在具有此 `session_id` 的 KYC 或 KYB 会话。", "content": { "application/json": { "examples": { "Not Found": { "summary": "未知的 session_id", "value": { "detail": "Not found." } } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST \\\n https://verification.didit.me/v3/session/3fa85f64-5717-4562-b3fc-2c963f66afa6/decision-email-preview/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"new_status\": \"Approved\", \"email_language\": \"en\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.preview_decision_email(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n new_status=\"Approved\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.previewDecisionEmail(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", {\n new_status: \"Approved\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.PreviewDecisionEmail(ctx, \"3fa85f64-5717-4562-b3fc-2c963f66afa6\", didit.SessionsPreviewDecisionEmailParams{\n\tNewStatus: \"Approved\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsPreviewDecisionEmailParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().previewDecisionEmail(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", SessionsPreviewDecisionEmailParams.builder()\n .newStatus(SessionsPreviewDecisionEmailParams.NewStatus.of(\"Approved\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->previewDecisionEmail('3fa85f64-5717-4562-b3fc-2c963f66afa6', [\n 'new_status' => 'Approved',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.preview_decision_email(\n \"3fa85f64-5717-4562-b3fc-2c963f66afa6\",\n new_status: \"Approved\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.PreviewDecisionEmailAsync(\"3fa85f64-5717-4562-b3fc-2c963f66afa6\", new SessionsPreviewDecisionEmailParams\n{\n NewStatus = \"Approved\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "x-didit-sdk": { "resource": "sessions", "method": "preview_decision_email", "auth": "api_key", "server": true } } }, "/v3/travel-rule/join/{token}/": { "get": { "summary": "获取自由加入邀请", "description": "公开，无需身份验证。在加入链接处于开放状态时显示其对应的邀请信息：发起方、邀请发送至的地址以及将预填的目录值。token 即作为身份验证。", "operationId": "getTravelRuleJoinInvitation", "x-didit-sdk": { "resource": "travel_rule.join", "method": "get_invitation", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "来自加入链接的邀请 token。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/join/{token}/" } ], "responses": { "200": { "description": "邀请。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinInvitation" } } } }, "404": { "description": "没有与此链接对应的邀请。" }, "410": { "description": "邀请已不再有效：已过期、已被使用或已被撤回。" } } }, "post": { "summary": "注册免费 Travel Rule 账户", "description": "公开，无需身份验证。为收到请求的交易对手 VASP 创建免费的 Travel Rule 账户。邮箱必须是接收邀请的地址。系统会向该邮箱发送一个 6 位字符的代码；将其发送至验证 endpoint 即可完成。每个地址和每个 IP 的注册尝试均受到速率限制。", "operationId": "registerTravelRuleJoin", "x-didit-sdk": { "resource": "travel_rule.join", "method": "register", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "来自加入链接的邀请 token。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinRegisterRequest" }, "example": { "email": "compliance@example.com", "password": "a-long-passphrase" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/join/{token}/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\": \"compliance@example.com\", \"password\": \"a-long-passphrase\"}'" } ], "responses": { "202": { "description": "账户已创建，验证码已通过邮件发送。", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "提示交易对手查收其邮箱中的验证码。" }, "email": { "type": "string", "format": "email", "description": "验证码发送的目标地址。" } } } } } }, "400": { "description": "电子邮件不是受邀地址，或者密码/地址被拒绝。" }, "404": { "description": "没有与此链接对应的邀请。" }, "410": { "description": "邀请已不再有效：已过期、已被使用或已被撤回。" }, "429": { "description": "加入尝试次数过多。`X-RateLimit-*` 请求头指明了已消耗的额度。" } } } }, "/v3/travel-rule/join/{token}/verify/": { "post": { "summary": "验证免费 Travel Rule 账户", "description": "公开，无需身份验证。使用邮件发送的代码，创建免费组织，并返回其应用在工作区 endpoint 上使用的凭证。接收 Travel Rule 数据是免费的。", "operationId": "verifyTravelRuleJoin", "x-didit-sdk": { "resource": "travel_rule.join", "method": "verify", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" }, "description": "来自加入链接的邀请 token。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinVerifyRequest" }, "example": { "email": "compliance@example.com", "code": "123456" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/join/{token}/verify/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\": \"compliance@example.com\", \"code\": \"123456\"}'" } ], "responses": { "201": { "description": "组织及应用凭据。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleJoinCredentials" } } } }, "400": { "description": "验证码或邮箱已被拒绝。" }, "404": { "description": "没有与此链接对应的邀请。" }, "410": { "description": "邀请已不再有效：已过期、已被使用或已被撤回。" }, "429": { "description": "加入尝试次数过多。`X-RateLimit-*` 请求头指明了已消耗的额度。" } } } }, "/v3/travel-rule/workspace/": { "get": { "summary": "获取免费 Travel Rule 工作区", "description": "读取加入免费计划的应用的免费工作区：目录认领、域名证明、计费和 Didit 网络列表。", "operationId": "getTravelRuleWorkspace", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "get", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/workspace/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.get()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.get();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.Get(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().get();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->get();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.get\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.GetAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "工作区。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "404": { "description": "此应用未加入免费额度，因此没有免费工作区。" } } } }, "/v3/travel-rule/workspace/claim/": { "post": { "summary": "认领名录条目", "description": "认领代表该工作区的名录条目。当工作邮箱属于该条目列出的域名时，认领即获证明并立即生效：VASP 档案和 Travel Rule 设置将根据该条目自动填充，并且 Travel Rule 将被开启，因此下一次向其发起的转账将通过 Didit 网络路由。否则，认领将等待审核（`pending_review`）。", "operationId": "claimTravelRuleWorkspace", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "claim", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceClaimRequest" }, "example": { "vasp_id": "0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/claim/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"vasp_id\": \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.claim(\n vasp_id=\"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.claim({\n vasp_id: \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.Claim(ctx, didit.TravelRuleWorkspaceClaimRequest{\n\tVASPID: \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWorkspaceClaimRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().claim(TravelRuleWorkspaceClaimRequest.builder()\n .vaspId(\"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->claim([\n 'vasp_id' => '0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.claim(vasp_id: \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.ClaimAsync(new TravelRuleWorkspaceClaimRequest\n{\n VaspId = \"0b0c9d3e-5a53-4a3e-9d6e-1f2f6f6a1c11\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "工作区及其认领状态。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "目录中没有具有此 id 的条目。" }, "404": { "description": "此应用未加入免费额度，因此没有免费工作区。" } } } }, "/v3/travel-rule/workspace/domain/code/": { "post": { "summary": "发送域名验证码邮件", "description": "向工作区的工作邮箱发送一次性验证码，以证明其控制该邮箱域名。受速率限制，且每个验证码仅允许有限次数的错误尝试。同时返回 DNS 替代方案的 TXT 记录。", "operationId": "sendTravelRuleWorkspaceDomainCode", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "send_domain_code", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/domain/code/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.send_domain_code()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.sendDomainCode();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.SendDomainCode(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().sendDomainCode();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->sendDomainCode();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.send_domain_code\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.SendDomainCodeAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "域名、其状态及 TXT 记录。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceDomainCodeResponse" } } } }, "404": { "description": "此应用未加入免费额度，因此没有免费工作区。" } } } }, "/v3/travel-rule/workspace/domain/confirm/": { "post": { "summary": "确认域名验证码", "description": "使用通过邮件发送的验证码，并将邮箱域名标记为已验证。", "operationId": "confirmTravelRuleWorkspaceDomain", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "confirm_domain", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceDomainConfirmRequest" }, "example": { "code": "123456" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/domain/confirm/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"code\": \"123456\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.confirm_domain(\n code=\"123456\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.confirmDomain({\n code: \"123456\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.ConfirmDomain(ctx, didit.TravelRuleWorkspaceDomainConfirmRequest{\n\tCode: \"123456\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWorkspaceDomainConfirmRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().confirmDomain(TravelRuleWorkspaceDomainConfirmRequest.builder()\n .code(\"123456\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->confirmDomain([\n 'code' => '123456',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.confirm_domain(code: \"123456\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.ConfirmDomainAsync(new TravelRuleWorkspaceDomainConfirmRequest\n{\n Code = \"123456\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "工作区。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "验证码错误、已过期或已被使用。" }, "404": { "description": "此应用未加入免费额度，因此没有免费工作区。" } } } }, "/v3/travel-rule/workspace/domain/dns/": { "post": { "summary": "通过其 TXT 记录验证域名", "description": "检查由 code endpoint 返回的 `didit-tr-verify.` TXT 记录，并在匹配时将该域名标记为已验证。邮件发送的验证码或 TXT 记录这两种证明之一即可满足要求。", "operationId": "verifyTravelRuleWorkspaceDomainDns", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "verify_domain_dns", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/domain/dns/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.verify_domain_dns()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.verifyDomainDns();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.VerifyDomainDNS(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().verifyDomainDns();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->verifyDomainDns();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.verify_domain_dns\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.VerifyDomainDnsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "工作区。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "未找到 TXT 记录或记录不匹配。" }, "404": { "description": "此应用未加入免费额度，因此没有免费工作区。" } } } }, "/v3/travel-rule/workspace/billing/": { "post": { "summary": "启用出站计费", "description": "为工作区开启出站 Travel Rule 计费。接收仍然免费。此设置无法通过 API 关闭：请联系 Didit 支持团队。", "operationId": "enableTravelRuleWorkspaceBilling", "x-didit-sdk": { "resource": "travel_rule.workspace", "method": "enable_billing", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspaceBillingRequest" }, "example": { "enabled": true } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/workspace/billing/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"enabled\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.workspace.enable_billing(\n enabled=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.workspace.enableBilling({\n enabled: true,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.Workspace.EnableBilling(ctx, didit.TravelRuleWorkspaceBillingRequest{\n\tEnabled: didit.Bool(true),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWorkspaceBillingRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().workspace().enableBilling(TravelRuleWorkspaceBillingRequest.builder()\n .enabled(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->workspace->enableBilling([\n 'enabled' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.workspace.enable_billing(enabled: true)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Workspace.EnableBillingAsync(new TravelRuleWorkspaceBillingRequest\n{\n Enabled = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已设置 `billing_enabled` 为 true 的工作区。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWorkspace" } } } }, "400": { "description": "`enabled` 为 false。" }, "404": { "description": "此应用未加入免费额度，因此没有免费工作区。" } } } }, "/v3/investigator/summary/": { "get": { "operationId": "investigator_summary", "summary": "调查员摘要", "description": "阶段、队列数量、今天已准备和已决策的报告、30 天一致率、价格以及每个队列的自主级别。受限密钥需要 `decisions` 作用域（读取）；交易警报还需要 `transactions` 作用域。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "stage": { "type": "string" }, "last_report_at": { "type": "string", "format": "date-time", "nullable": true }, "prepared_today": { "type": "integer" }, "ready_to_accept": { "type": "integer" }, "open": { "type": "integer" }, "decided_today": { "type": "integer" }, "automation_rate_month": { "type": "number", "nullable": true }, "preparing": { "type": "integer" } } } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity`（会话，以及非交易规则开启的案件）或 `transactions`（交易警报，以及由交易规则开启的案件）。" }, { "in": "query", "name": "timezone", "schema": { "type": "string" }, "description": "\"今天\"所依据的 IANA 时区（例如 `Europe/Madrid`）。默认为 UTC。" } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_summary", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_summary()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveSummary();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveSummary(ctx, didit.InvestigatorRetrieveSummaryParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveSummary();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveSummary();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_summary\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveSummaryAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/queue/": { "get": { "operationId": "investigator_queue", "summary": "列出调查员队列", "description": "在开放的报告中，优先显示 **Ready to accept**，然后按截止时间、风险和等待时间排序。`counts` 涵盖范围内的所有类型。`count` 上限为 100。受限密钥需要 `decisions` 作用域（读取权限）；交易警报还需要 `transactions`。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "counts": { "type": "object", "additionalProperties": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/InvestigatorQueueRow" } } } } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity`（会话，以及非交易规则开启的案件）或 `transactions`（交易警报，以及由交易规则开启的案件）。" }, { "in": "query", "name": "kind", "schema": { "type": "string" }, "description": "`session`、`business_session`、`transaction` 或 `case`，或以逗号分隔的多个值。" }, { "in": "query", "name": "queue", "schema": { "type": "string", "enum": [ "kyc", "kyb", "aml", "transactions", "cases" ] } }, { "in": "query", "name": "recommendation", "schema": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] } }, { "in": "query", "name": "confidence", "schema": { "type": "string", "enum": [ "high", "moderate", "low" ] } }, { "in": "query", "name": "ready", "schema": { "type": "boolean" } }, { "in": "query", "name": "search", "schema": { "type": "string" }, "description": "姓名、企业、案件标题、号码、交易 ID 或项目 ID。" }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "x-didit-sdk": { "resource": "investigator", "method": "list_queue", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.investigator.list_queue():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.investigator.listQueue()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Investigator.ListQueueAutoPaging(ctx, didit.InvestigatorListQueueParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.investigator().listQueue()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "investigator->listQueue() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.investigator.list_queue.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Investigator.ListQueueAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/investigator/runs/{run_id}/": { "get": { "operationId": "investigator_run_retrieve", "summary": "获取 Investigator 报告", "description": "单次运行的完整报告。当运行没有已完成的报告或其条目已被删除时返回 404。受限密钥需要 `decisions` 作用域（读取权限）；交易警报还需要 `transactions` 作用域。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorRunDetail" } } } }, "404": { "description": "未找到，或没有报告。" }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_run", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_run(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveRun(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveRun(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveRun(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveRun('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_run(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveRunAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/runs/{run_id}/accept/": { "post": { "operationId": "investigator_run_accept", "summary": "接受建议", "description": "通过该项目的常规路径应用建议的操作，以便触发您常用的 Webhook。附带 `narrative` 会将其标记为已编辑并接受。受限密钥需要 `decisions` 作用域（写入权限）；交易警报还需要 `transactions`（写入权限）。升级验证或交易会开启一个案件。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorDecision" } } } }, "409": { "description": "已做出决策、报告未就绪，或保护措施锁定了该项。" }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorAcceptRequest" }, "example": { "send_email": false } } } }, "x-didit-sdk": { "resource": "investigator", "method": "accept_run", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.accept_run(\n \"11111111-2222-3333-4444-555555555555\",\n send_email=False,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.acceptRun(\"11111111-2222-3333-4444-555555555555\", {\n send_email: false,\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.AcceptRun(ctx, \"11111111-2222-3333-4444-555555555555\", didit.InvestigatorAcceptRequest{\n\tSendEmail: didit.Bool(false),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.InvestigatorAcceptRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().acceptRun(\"11111111-2222-3333-4444-555555555555\", InvestigatorAcceptRequest.builder()\n .sendEmail(false)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->acceptRun('11111111-2222-3333-4444-555555555555', [\n 'send_email' => false,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.accept_run(\n \"11111111-2222-3333-4444-555555555555\",\n send_email: false\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.AcceptRunAsync(\"11111111-2222-3333-4444-555555555555\", new InvestigatorAcceptRequest\n{\n SendEmail = false,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/runs/{run_id}/override/": { "post": { "operationId": "investigator_run_override", "summary": "覆盖建议", "description": "采取附带类别和原因的另一项操作。同时覆盖 Investigator 自动做出的且仍然有效的决策。受限密钥需要 `decisions` 权限（写）；交易警报还需要 `transactions` 权限（写）。上报验证或交易将打开一个案件。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorDecision" } } } }, "409": { "description": "已做出决策，或保护措施锁定了该项。" }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "path", "name": "run_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorOverrideRequest" }, "example": { "action": "decline", "category": "evidence_misread", "reason": "The proof of address is older than three months." } } } }, "x-didit-sdk": { "resource": "investigator", "method": "override_run", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.override_run(\n \"11111111-2222-3333-4444-555555555555\",\n action=\"decline\",\n category=\"evidence_misread\",\n reason=\"The proof of address is older than three months.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.overrideRun(\"11111111-2222-3333-4444-555555555555\", {\n action: \"decline\",\n category: \"evidence_misread\",\n reason: \"The proof of address is older than three months.\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.OverrideRun(ctx, \"11111111-2222-3333-4444-555555555555\", didit.InvestigatorOverrideRequest{\n\tAction: \"decline\",\n\tCategory: \"evidence_misread\",\n\tReason: \"The proof of address is older than three months.\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.InvestigatorOverrideRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().overrideRun(\"11111111-2222-3333-4444-555555555555\", InvestigatorOverrideRequest.builder()\n .action(InvestigatorOverrideRequest.Action.of(\"decline\"))\n .category(InvestigatorOverrideRequest.Category.of(\"evidence_misread\"))\n .reason(\"The proof of address is older than three months.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->overrideRun('11111111-2222-3333-4444-555555555555', [\n 'action' => 'decline',\n 'category' => 'evidence_misread',\n 'reason' => 'The proof of address is older than three months.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.override_run(\n \"11111111-2222-3333-4444-555555555555\",\n action: \"decline\",\n category: \"evidence_misread\",\n reason: \"The proof of address is older than three months.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.OverrideRunAsync(\"11111111-2222-3333-4444-555555555555\", new InvestigatorOverrideRequest\n{\n Action = \"decline\",\n Category = \"evidence_misread\",\n Reason = \"The proof of address is older than three months.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/runs/batch-accept/": { "post": { "operationId": "investigator_batch_accept", "summary": "批量接受建议", "description": "最多接受 50 份标记为准备接受的报告。每份报告都有其独立的决策：无法接受的报告将被跳过并附带原因。受限密钥需要 `decisions` 作用域（写入权限）；交易警报还需要 `transactions`（写入权限）。上报验证或交易会创建一个案件。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorBatchAcceptResponse" } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorBatchAcceptRequest" } } } }, "x-didit-sdk": { "resource": "investigator", "method": "batch_accept_runs", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.batch_accept_runs(\n run_ids=[\"11111111-2222-3333-4444-555555555555\"],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.batchAcceptRuns({\n run_ids: [\"11111111-2222-3333-4444-555555555555\"],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.BatchAcceptRuns(ctx, didit.InvestigatorBatchAcceptRequest{\n\tRunIDs: []string{\"11111111-2222-3333-4444-555555555555\"},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.InvestigatorBatchAcceptRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().batchAcceptRuns(InvestigatorBatchAcceptRequest.builder()\n .runIds(List.of(\"11111111-2222-3333-4444-555555555555\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->batchAcceptRuns([\n 'run_ids' => ['11111111-2222-3333-4444-555555555555'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.batch_accept_runs(run_ids: [\"11111111-2222-3333-4444-555555555555\"])\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.BatchAcceptRunsAsync(new InvestigatorBatchAcceptRequest\n{\n RunIds = new string[] { \"11111111-2222-3333-4444-555555555555\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/transactions/{transaction_id}/": { "get": { "operationId": "investigator_transaction_retrieve", "summary": "获取交易的 Investigator 审核", "description": "交易的最新审核，若从未审核过则为 `investigator: null`。受限密钥需要 `decisions` 和 `transactions` 权限范围（读取）。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "investigator": { "$ref": "#/components/schemas/InvestigatorBlock" } } } } } }, "404": { "description": "不是该应用的交易。" }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "path", "name": "transaction_id", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_transaction", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_transaction(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveTransaction(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveTransaction(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveTransaction(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveTransaction('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_transaction(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveTransactionAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/guardrails/": { "get": { "operationId": "investigator_guardrails", "summary": "列出已锁定的防护规则", "description": "适用于每个队列的五项安全防线。它们无法关闭。受限密钥需要 `decisions` 作用域（读取权限）；交易警报还需要 `transactions` 作用域。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "sanctions_to_person", "no_tipping_off", "no_protected_characteristics", "never_files_reports", "every_decision_logged" ] }, "title": { "type": "string" }, "description": { "type": "string" }, "locked": { "type": "boolean" } } } } } } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "x-didit-sdk": { "resource": "investigator", "method": "list_guardrails", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.list_guardrails()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.listGuardrails();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.ListGuardrails(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().listGuardrails();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->listGuardrails();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.list_guardrails\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.ListGuardrailsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/dashboard/": { "get": { "operationId": "investigator_dashboard", "summary": "调查员仪表板", "description": "过去 30 天：审核、决策、自动化率、节省小时数、支出、人工干预、上线以来的质量抽样、各队列及每周数据。受限密钥需要 `decisions` 作用域（读取权限）；交易警报还需要 `transactions`。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "stage": { "type": "string" }, "window_days": { "type": "integer" }, "reviews": { "type": "integer" }, "decided": { "type": "integer" }, "automated": { "type": "integer" }, "automation_rate": { "type": "number", "nullable": true }, "hours_saved": { "type": "number", "nullable": true } } } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity`（会话，以及非交易规则开启的案件）或 `transactions`（交易警报，以及由交易规则开启的案件）。" } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_dashboard", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_dashboard()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveDashboard();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveDashboard(ctx, didit.InvestigatorRetrieveDashboardParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveDashboard();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveDashboard();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_dashboard\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveDashboardAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/performance/": { "get": { "operationId": "investigator_performance", "summary": "调查员绩效", "description": "一段时间内与团队的一致性、处理量、节省的时间、置信度校准、各队列结果、人工覆盖原因以及分歧情况。受限密钥需要具备 `decisions` 作用域（读取）；交易警报还需要 `transactions` 作用域。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true, "properties": { "period": { "type": "integer" }, "start": { "type": "string", "format": "date" }, "end": { "type": "string", "format": "date" }, "investigated": { "type": "integer" } } } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity`（会话，以及非交易规则开启的案件）或 `transactions`（交易警报，以及由交易规则开启的案件）。" }, { "in": "query", "name": "period", "schema": { "type": "string", "enum": [ "7", "30", "90" ], "default": "30" }, "description": "天数，截止到今天。" } ], "x-didit-sdk": { "resource": "investigator", "method": "retrieve_performance", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_performance()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrievePerformance();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrievePerformance(ctx, didit.InvestigatorRetrievePerformanceParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrievePerformance();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrievePerformance();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_performance\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrievePerformanceAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/investigator/activity/": { "get": { "operationId": "investigator_activity", "summary": "列出调查员活动", "description": "仅追加的审计日志，最新的排在最前。批量接受算作一条记录。按分组添加 `counts` 以及 `actors`。受限密钥需要 `decisions` 权限（只读）；交易警报还需要 `transactions` 权限。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "counts": { "type": "object", "additionalProperties": true }, "actors": { "type": "array", "items": {} }, "results": { "type": "array", "items": { "type": "object", "additionalProperties": true, "description": "`id`、`at`、`kind`、`group`、`queue`、`run_id`、`item`、`actor`、`agent_version`、`data`、`report_version`、`steps`、`sources`、`batch`。" } } } } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity`（会话，以及非交易规则开启的案件）或 `transactions`（交易警报，以及由交易规则开启的案件）。" }, { "in": "query", "name": "group", "schema": { "type": "string", "enum": [ "agent", "decisions", "overrides", "autonomy" ] } }, { "in": "query", "name": "actor", "schema": { "type": "string" }, "description": "`agent` 表示 Investigator，或者是个人的邮箱。" }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "until", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "limit", "schema": { "type": "integer" } }, { "in": "query", "name": "offset", "schema": { "type": "integer" } } ], "x-didit-sdk": { "resource": "investigator", "method": "list_activity", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.investigator.list_activity():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.investigator.listActivity()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.Investigator.ListActivityAutoPaging(ctx, didit.InvestigatorListActivityParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.investigator().listActivity()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "investigator->listActivity() as $item) {\n print_r($item);\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.investigator.list_activity.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.Investigator.ListActivityAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/investigator/activity/export/": { "get": { "operationId": "investigator_activity_export", "summary": "导出调查员活动", "description": "与 CSV 相同的条目，每个决策一行，最新的排在最前，最多 10,000 个条目。受限密钥需要 `decisions` 作用域（读取）；交易警报还需要 `transactions`。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "text/csv": { "schema": { "type": "string" } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "parameters": [ { "in": "query", "name": "scope", "schema": { "type": "string", "enum": [ "all", "identity", "transactions" ], "default": "all" }, "description": "`identity`（会话，以及非交易规则开启的案件）或 `transactions`（交易警报，以及由交易规则开启的案件）。" }, { "in": "query", "name": "group", "schema": { "type": "string", "enum": [ "agent", "decisions", "overrides", "autonomy" ] } }, { "in": "query", "name": "actor", "schema": { "type": "string" }, "description": "`agent` 表示 Investigator，或者是个人的邮箱。" }, { "in": "query", "name": "since", "schema": { "type": "string", "format": "date-time" } }, { "in": "query", "name": "until", "schema": { "type": "string", "format": "date-time" } } ], "x-didit-sdk": { "resource": "investigator", "method": "export_activity", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\ncontent = client.investigator.export_activity()\nwith open(\"download.csv\", \"wb\") as file:\n file.write(content)" }, { "lang": "javascript", "label": "Node.js", "source": "import { writeFile } from \"node:fs/promises\";\nimport Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst content = await didit.investigator.exportActivity();\nawait writeFile(\"download.csv\", Buffer.from(await content.arrayBuffer()));" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresp, err := client.Investigator.ExportActivity(ctx, didit.InvestigatorExportActivityParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer resp.Body.Close()\nfile, err := os.Create(\"download.csv\")\nif err != nil {\n\tlog.Fatal(err)\n}\ndefer file.Close()\nif _, err := io.Copy(file, resp.Body); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.investigator().exportActivity()\n .writeTo(Path.of(\"download.csv\"));" }, { "lang": "php", "label": "PHP", "source": "investigator->exportActivity();\n$content->saveTo('download.csv');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ncontent = didit.investigator.export_activity\nFile.binwrite(\"download.csv\", content)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar content = await client.Investigator.ExportActivityAsync();\nawait content.SaveToAsync(\"download.csv\");" } ] } }, "/v3/investigator/settings/": { "get": { "operationId": "investigator_settings_retrieve", "summary": "获取 Investigator 设置", "description": "阶段（`none`、`shadow` 或 `live`）以及月度支出限制与本月支出。受限密钥需要 `applications` 权限范围（读取）。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorSettings" } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "x-didit-sdk": { "resource": "investigator", "method": "retrieve_settings", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.retrieve_settings()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.retrieveSettings();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.RetrieveSettings(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().retrieveSettings();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->retrieveSettings();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.retrieve_settings\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.RetrieveSettingsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "patch": { "operationId": "investigator_settings_update", "summary": "更新调查员设置", "description": "更改阶段、每月消费限额，或两者同时更改。升级超过 `none` 需要包含 Investigator 的套餐（Growth 或更高版本）；`live` 还需要一份对其定价的合同（如果您有合同）。受限密钥需要 `applications` 作用域（写入权限）。", "tags": [ "Investigator" ], "security": [ { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorSettings" } } } }, "400": { "description": "两个字段均未发送，或值无效。" }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "该密钥缺少相应作用域、该项目类型不可读，或套餐不包含 Investigator。" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvestigatorSettings" }, "example": { "stage": "shadow", "monthly_spend_limit": "500.00" } } } }, "x-didit-sdk": { "resource": "investigator", "method": "update_settings", "auth": "api_key", "server": true }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.investigator.update_settings(\n stage=\"shadow\",\n monthly_spend_limit=\"500.00\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.investigator.updateSettings({\n stage: \"shadow\",\n monthly_spend_limit: \"500.00\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Investigator.UpdateSettings(ctx, didit.InvestigatorSettingsParam{\n\tStage: didit.Some(didit.InvestigatorSettingsStage(\"shadow\")),\n\tMonthlySpendLimit: didit.String(\"500.00\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.InvestigatorSettings;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.investigator().updateSettings(InvestigatorSettings.builder()\n .stage(InvestigatorSettings.Stage.of(\"shadow\"))\n .monthlySpendLimit(\"500.00\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "investigator->updateSettings([\n 'stage' => 'shadow',\n 'monthly_spend_limit' => '500.00',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.investigator.update_settings(\n stage: \"shadow\",\n monthly_spend_limit: \"500.00\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Investigator.UpdateSettingsAsync(new InvestigatorSettings\n{\n Stage = new InvestigatorSettingsStage(\"shadow\"),\n MonthlySpendLimit = \"500.00\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/travel-rule/wallet-addresses/import/": { "post": { "summary": "批量导入钱包地址", "description": "单次调用即可向您的 Travel Rule 地址簿添加最多 10,000 个钱包（支持 JSON 或 CSV 文件格式）。钱包可通过其地址发送，也可通过其小写地址的 SHA-256 哈希值（`address_hash`）发送以保护地址隐私，或两者同时发送。导入具有幂等性：地址簿中已存在的钱包将报告为 `existing` 且保持不变，因此可重复发送相同文件。每一行均独立验证，因此单行错误绝不会导致其他行失败。仅通过哈希导入的钱包仅与发往该地址的转账相匹配，并且可以像其他任何条目一样使用钱包所有权小部件进行证明。", "operationId": "importTravelRuleWalletAddresses", "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-didit-sdk": { "resource": "travel_rule.wallet_addresses", "method": "bulk_import", "auth": "api_key", "server": true }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "entries" ], "properties": { "entries": { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/WalletAddressImportRow" } } } }, { "type": "array", "minItems": 1, "maxItems": 10000, "items": { "$ref": "#/components/schemas/WalletAddressImportRow" } } ] }, "example": { "entries": [ { "address": "0xBeneficiaryWallet01", "chain": "ETH", "holder_name": "Ana Diaz", "holder_vendor_data": "user-042" }, { "address_hash": "4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e", "chain": "bitcoin", "holder_vendor_data": "user-043" }, { "address": "rExchangeSharedAddress01", "chain": "XRP", "memo": "104729", "holder_name": "Ana Diaz" } ] } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "最大 5 MB 的 UTF-8 CSV 文件，带有列名的表头行（列名为字段名或其别名）。空单元格视为未发送；导入不读取的列将被忽略。" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl (JSON)", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/import/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"entries\": [{\"address\": \"0xBeneficiaryWallet01\", \"chain\": \"ETH\", \"holder_name\": \"Ana Diaz\"}, {\"address\": \"rExchangeSharedAddress01\", \"chain\": \"XRP\", \"memo\": \"104729\"}]}'" }, { "lang": "curl", "label": "curl (CSV)", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/import/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -F 'file=@wallets.csv;type=text/csv'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_addresses.bulk_import(\n body={\n \"entries\": [{\n \"address\": \"0xBeneficiaryWallet01\",\n \"chain\": \"ETH\",\n \"holder_name\": \"Ana Diaz\",\n \"holder_vendor_data\": \"user-042\",\n }, {\n \"address_hash\": \"4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e\",\n \"chain\": \"bitcoin\",\n \"holder_vendor_data\": \"user-043\",\n }, {\n \"address\": \"rExchangeSharedAddress01\",\n \"chain\": \"XRP\",\n \"memo\": \"104729\",\n \"holder_name\": \"Ana Diaz\",\n }],\n },\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletAddresses.bulkImport({\n file: await fileFromPath(\"wallet-addresses.csv\"),\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.WalletAddresses.BulkImport(ctx, didit.TravelRuleWalletAddressesBulkImportParams{\n\tFile: didit.Some(didit.FileFromPath(\"wallet-addresses.csv\")),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport me.didit.Didit;\nimport me.didit.types.TravelRuleWalletAddressesBulkImportParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletAddresses().bulkImport(TravelRuleWalletAddressesBulkImportParams.builder()\n .file(Path.of(\"wallet-addresses.csv\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletAddresses->bulkImport([\n 'file' => File::fromPath('wallet-addresses.csv'),\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_addresses.bulk_import(\n body: {\n entries: [{\n address: \"0xBeneficiaryWallet01\",\n chain: \"ETH\",\n holder_name: \"Ana Diaz\",\n holder_vendor_data: \"user-042\",\n }, {\n address_hash: \"4f7d2e1c9b8a7f6e5d4c3b2a1f0e9d8c7b6a5f4e3d2c1b0a9f8e7d6c5b4a3f2e\",\n chain: \"bitcoin\",\n holder_vendor_data: \"user-043\",\n }, {\n address: \"rExchangeSharedAddress01\",\n chain: \"XRP\",\n memo: \"104729\",\n holder_name: \"Ana Diaz\",\n }],\n }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletAddresses.BulkImportAsync(new TravelRuleWalletAddressesBulkImportParams\n{\n File = FileUpload.FromPath(\"wallet-addresses.csv\"),\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "每一行都已创建、已在账簿中，或者是先前某行的重复项。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressImportReport" }, "example": { "total": 3, "created": 2, "existing": 1, "duplicate": 0, "failed": 0, "rows": [ { "row": 1, "status": "existing", "entry_id": "11111111-2222-3333-4444-555555555555", "errors": {}, "duplicate_of_row": null }, { "row": 2, "status": "created", "entry_id": "22222222-3333-4444-5555-666666666666", "errors": {}, "duplicate_of_row": null }, { "row": 3, "status": "created", "entry_id": "33333333-4444-5555-6666-777777777777", "errors": {}, "duplicate_of_row": null } ] } } } }, "207": { "description": "至少有一行失败；其余行已导入。每个失败的行均指明了其错误。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletAddressImportReport" }, "example": { "total": 2, "created": 1, "existing": 0, "duplicate": 0, "failed": 1, "rows": [ { "row": 1, "status": "created", "entry_id": "44444444-5555-6666-7777-888888888888", "errors": {}, "duplicate_of_row": null }, { "row": 2, "status": "failed", "entry_id": null, "errors": { "address": [ "Send address, address_hash or both." ] }, "duplicate_of_row": null } ] } } } }, "400": { "description": "请求本身无法读取：同时提供了 `entries` 和 `file`，或两者均未提供；超过 10,000 行；文件超过 5 MB、不是 UTF-8 编码的 CSV、没有表头行或没有数据行。", "content": { "application/json": { "schema": { "type": "object" }, "example": { "file": [ "At most 10000 rows per import." ] } } } } } } }, "/v3/travel-rule/counterparty-contacts/": { "get": { "summary": "列出交易对手联系人", "description": "EMAIL 渠道可为您应用写入的合规地址：Didit 平台联系人加上您应用自身的私有联系人，包括已退信的联系人，按最新优先排序。通过 `limit`（默认 50）和 `offset` 进行分页；`count` 最大统计到 100，因此 100 表示 100 或更多。", "operationId": "listTravelRuleCounterpartyContacts", "x-didit-sdk": { "resource": "travel_rule.counterparty_contacts", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "counterparty", "in": "query", "schema": { "type": "string", "format": "uuid" }, "description": "仅该目录条目的联系人。必须是 UUID；空值表示不进行过滤。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "页面大小，默认为 50。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "要跳过的行。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/travel-rule/counterparty-contacts/?counterparty={vasp_id}' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.counterparty_contacts.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.counterpartyContacts.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.CounterpartyContacts.ListAutoPaging(ctx, didit.TravelRuleCounterpartyContactsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().counterpartyContacts().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->counterpartyContacts->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.counterparty_contacts.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.CounterpartyContacts.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "联系人。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleCounterpartyContact" } } } }, "example": { "count": 1, "next": null, "previous": null, "results": [ { "uuid": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b", "counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "counterparty_name": "Example Counterparty VASP", "email": "compliance@counterparty.example", "name": "Compliance desk", "source": "application", "scope": "application", "created_by": "", "verified_at": null, "is_invalid": false, "invalid_reason": "", "invalid_detail": "", "invalid_at": null, "created_at": "2026-10-19T09:00:00Z" } ] } } } }, "400": { "description": "`counterparty` 不是有效的 UUID。", "content": { "application/json": { "example": { "counterparty": [ "Must be a valid UUID." ] } } } } } }, "post": { "summary": "添加交易对手联系人", "description": "为单个名录条目添加私有合规地址。仅您的应用可以查看和使用该地址，并且 EMAIL 通道会优先写入该地址，之后才会联系平台联系人。如果添加的地址已存在于您自己的联系人中，则会返回该联系人。", "operationId": "createTravelRuleCounterpartyContact", "x-didit-sdk": { "resource": "travel_rule.counterparty_contacts", "method": "create", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyContactCreate" }, "example": { "counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "email": "compliance@counterparty.example", "name": "Compliance desk" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/counterparty-contacts/ \\\n -H 'x-api-key: YOUR_API_KEY' -H 'Content-Type: application/json' \\\n -d '{\"counterparty\": \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\", \"email\": \"compliance@counterparty.example\", \"name\": \"Compliance desk\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.counterparty_contacts.create(\n counterparty=\"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n email=\"compliance@counterparty.example\",\n name=\"Compliance desk\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.counterpartyContacts.create({\n counterparty: \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n email: \"compliance@counterparty.example\",\n name: \"Compliance desk\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.CounterpartyContacts.Create(ctx, didit.TravelRuleCounterpartyContactCreate{\n\tCounterparty: \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n\tEmail: \"compliance@counterparty.example\",\n\tName: didit.String(\"Compliance desk\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleCounterpartyContactCreate;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().counterpartyContacts().create(TravelRuleCounterpartyContactCreate.builder()\n .counterparty(\"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\")\n .email(\"compliance@counterparty.example\")\n .name(\"Compliance desk\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->counterpartyContacts->create([\n 'counterparty' => '0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91',\n 'email' => 'compliance@counterparty.example',\n 'name' => 'Compliance desk',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.counterparty_contacts.create(\n counterparty: \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n email: \"compliance@counterparty.example\",\n name: \"Compliance desk\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.CounterpartyContacts.CreateAsync(new TravelRuleCounterpartyContactCreate\n{\n Counterparty = \"0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91\",\n Email = \"compliance@counterparty.example\",\n Name = \"Compliance desk\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "201": { "description": "联系人已添加。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleCounterpartyContact" }, "example": { "uuid": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b", "counterparty": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "counterparty_name": "Example Counterparty VASP", "email": "compliance@counterparty.example", "name": "Compliance desk", "source": "application", "scope": "application", "created_by": "", "verified_at": null, "is_invalid": false, "invalid_reason": "", "invalid_detail": "", "invalid_at": null, "created_at": "2026-10-19T09:00:00Z" } } } }, "400": { "description": "字段缺失或无效，或者没有名录条目具有此 ID。", "content": { "application/json": { "example": { "counterparty": [ "No directory entry with this id." ] } } } } } } }, "/v3/travel-rule/counterparty-contacts/{contact_uuid}/": { "delete": { "summary": "删除交易对手联系人", "description": "删除您应用自有的一个联系人。EMAIL 通道将立即停止向其写入。平台联系人无法删除。", "operationId": "deleteTravelRuleCounterpartyContact", "x-didit-sdk": { "resource": "travel_rule.counterparty_contacts", "method": "delete", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "contact_uuid", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X DELETE https://verification.didit.me/v3/travel-rule/counterparty-contacts/{contact_uuid}/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.travel_rule.counterparty_contacts.delete(\n \"11111111-2222-3333-4444-555555555555\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.travelRule.counterpartyContacts.delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.TravelRule.CounterpartyContacts.Delete(ctx, \"11111111-2222-3333-4444-555555555555\"); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.travelRule().counterpartyContacts().delete(\"11111111-2222-3333-4444-555555555555\");" }, { "lang": "php", "label": "PHP", "source": "travelRule->counterpartyContacts->delete('11111111-2222-3333-4444-555555555555');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.counterparty_contacts.delete(\"11111111-2222-3333-4444-555555555555\")" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.TravelRule.CounterpartyContacts.DeleteAsync(\"11111111-2222-3333-4444-555555555555\");" } ], "responses": { "204": { "description": "已删除。" }, "404": { "description": "您的应用中没有具有此 id 的联系人。平台联系人也会返回 404。" } } } }, "/v3/travel-rule/transfers/": { "get": { "summary": "列出 Travel Rule 转账", "description": "您的应用的 Travel Rule 转账记录，按最新优先排序，使用 `limit`（默认 50）和 `offset` 进行分页。行记录仅包含 VASP 名称、钱包和备注，绝不包含个人数据。使用逗号分隔的值可选择多个。未知值将返回 400 并指明参数，例如 `{\"direction\": [\"Unknown value(s): inbound.\"]}`。", "operationId": "listTravelRuleTransfers", "x-didit-sdk": { "resource": "travel_rule.transfers", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "INBOUND、OUTBOUND 或两者以逗号分隔。区分大小写。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "一个或多个转账状态，以逗号分隔。" }, { "name": "rail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "INTERNAL、TRP、GTR、TRUST、VERIFYVASP、SYGNA、EMAIL、TEST_VASP 中的一个或多个，以逗号分隔。" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "withdrawal、deposit 或 message，以逗号分隔。" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "交易的币种，不区分大小写。" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "在此日期（UTC）或之后创建的转账，格式为 YYYY-MM-DD。" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "在此日期（UTC）或之前创建的转账，格式为 YYYY-MM-DD。" }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "来自 GET /v3/travel-rule/vasps/ 的名录条目或 Didit 网络成员的 `id`：用于获取您与该交易对手之间的转账。无效的 id 值将返回 400。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1 }, "description": "页面大小，默认为 50。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "要跳过的行。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/travel-rule/transfers/?direction=OUTBOUND&status=AWAITING_COUNTERPARTY' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.transfers.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.transfers.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.Transfers.ListAutoPaging(ctx, didit.TravelRuleTransfersListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().transfers().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->transfers->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.transfers.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.Transfers.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "一页转账。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleTransferRow" } } } }, "example": { "count": 1, "next": null, "previous": null, "results": [ { "id": "5b0f6c2e-2a4d-4f0e-9a41-0c3f9a7e1d22", "transaction_id": "a3c1e8f4-7b62-4d1a-8e0b-2f9d6c4b7a10", "txn_id": "wd-2026-10-19-0042", "txn_date": "2026-10-19T08:41:12Z", "kind": "withdrawal", "direction": "OUTBOUND", "status": "AWAITING_COUNTERPARTY", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "Origin CASP SL", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": null, "deadline_at": "2026-10-21T08:41:13Z", "created_at": "2026-10-19T08:41:13Z" } ] } } } }, "400": { "description": "过滤器值无效。", "content": { "application/json": { "example": { "start_date": [ "Use the YYYY-MM-DD format." ] } } } } } } }, "/v3/session/imports/providers/": { "get": { "summary": "列出迁移提供商", "description": "可从中迁移验证的 15 家提供商：各自连接所需的内容、其 API 是否支持列出记录、其密钥所需的权限以及其默认状态映射。", "operationId": "get_v3_session_imports_providers_list", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_providers", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "迁移提供商。", "content": { "application/json": { "schema": { "type": "object", "properties": { "providers": { "type": "array", "items": { "$ref": "#/components/schemas/ImportProvider" } }, "mapping_targets": { "type": "array", "items": { "type": "string" } }, "skipped_statuses": { "type": "array", "items": { "type": "string" } } } } } } }, "403": { "description": "API 密钥缺失、无效或已撤销，或者调用方无法为此应用导入验证。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.list_providers()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.listProviders();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.ListProviders(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().listProviders();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listProviders();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.list_providers\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ListProvidersAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/providers/check/": { "post": { "summary": "核验提供商密钥", "description": "在创建迁移之前，使用您的密钥读取提供商。不存储任何内容。", "operationId": "post_v3_session_imports_providers_check", "x-didit-sdk": { "resource": "sessions.imports", "method": "check_provider", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ], "description": "迁移来源，来自 `GET /v3/session/imports/providers/`。当 `source` 为 `provider` 时必填。" }, "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "服务商的只读密钥，其字段名称由 `credential_fields` 列出。静态加密存储，从不返回，并在导入结束时抹除。请作为 multipart 中的 JSON 字符串发送。" }, "options": { "type": "object", "properties": { "region": { "type": "string", "description": "服务商区域，为其 `regions` 之一（Onfido：`eu`、`us`、`ca`）。" } } }, "record_ids": { "type": "array", "items": { "type": "string" }, "description": "对于 `api_ids` 提供商：导出的首个记录 ID。" } }, "required": [ "provider", "credentials" ] }, "example": { "provider": "sumsub", "credentials": { "app_token": "YOUR_PROVIDER_APP_TOKEN", "secret_key": "YOUR_PROVIDER_SECRET_KEY" } } } } }, "responses": { "200": { "description": "该密钥可以读取记录。", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" }, "provider": { "type": "string" }, "credential_hint": { "type": "string", "nullable": true } } } } } }, "400": { "description": "服务商拒绝了该密钥：`code`、`detail`、`missing_permissions`、`suggested_region`。" }, "403": { "description": "API 密钥缺失、无效或已撤销，或者调用方无法为此应用导入验证。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.check_provider(\n provider=\"sumsub\",\n credentials={\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.checkProvider({\n provider: \"sumsub\",\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.CheckProvider(ctx, didit.SessionsImportsCheckProviderParams{\n\tProvider: \"sumsub\",\n\tCredentials: map[string]string{\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsImportsCheckProviderParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().checkProvider(SessionsImportsCheckProviderParams.builder()\n .provider(SessionsImportsCheckProviderParams.Provider.of(\"sumsub\"))\n .credentials(Map.of(\"app_token\", \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\", \"YOUR_PROVIDER_SECRET_KEY\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->checkProvider([\n 'provider' => 'sumsub',\n 'credentials' => ['app_token' => 'YOUR_PROVIDER_APP_TOKEN', 'secret_key' => 'YOUR_PROVIDER_SECRET_KEY'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.check_provider(\n provider: \"sumsub\",\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.CheckProviderAsync(new SessionsImportsCheckProviderParams\n{\n Provider = \"sumsub\",\n Credentials = new Dictionary { [\"app_token\"] = \"YOUR_PROVIDER_APP_TOKEN\", [\"secret_key\"] = \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/start/": { "post": { "summary": "发起试运行", "description": "启动空运行（dry run）已完成（`READY`）的迁移：同一个任务将以本次发送的状态映射和人脸模板选择进行实际导入。", "operationId": "post_v3_session_imports_start", "x-didit-sdk": { "resource": "sessions.imports", "method": "start", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] }, "description": "对提供商默认状态映射的修改：将源状态映射到 Didit 状态。`Not Finished` 和 `Abandoned` 会被跳过并计数，绝不会被导入。" }, "face_templates": { "type": "boolean", "default": false, "description": "根据导入的自拍照构建人脸模板，并对照应用的人脸库和黑名单进行搜索。匹配项仅会被标记以供审核。需要 `lawful_basis_confirmed`。" }, "lawful_basis_confirmed": { "type": "boolean", "default": false, "description": "确认您拥有合法依据将这些自拍照共享给作为处理者的 Didit。" } } } } } }, "responses": { "200": { "description": "导入任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "该任务当前的状态不支持此操作。" }, "403": { "description": "API 密钥缺失、无效或已撤销，或者调用方无法为此应用导入验证。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.start(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.start(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Start(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsImportsStartParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().start(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->start('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.start(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.StartAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/pause/": { "post": { "summary": "暂停导入任务", "description": "暂停排队中或正在运行的导入任务。", "operationId": "post_v3_session_imports_pause", "x-didit-sdk": { "resource": "sessions.imports", "method": "pause", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "导入任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "该任务当前的状态不支持此操作。" }, "403": { "description": "API 密钥缺失、无效或已撤销，或者调用方无法为此应用导入验证。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.pause(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.pause(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Pause(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().pause(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->pause('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.pause(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.PauseAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/resume/": { "post": { "summary": "恢复导入任务", "description": "恢复您暂停的导入。因服务商速率限制而暂停的任务会自动恢复。", "operationId": "post_v3_session_imports_resume", "x-didit-sdk": { "resource": "sessions.imports", "method": "resume", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "导入任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "该任务当前的状态不支持此操作。" }, "403": { "description": "API 密钥缺失、无效或已撤销，或者调用方无法为此应用导入验证。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.resume(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.resume(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Resume(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().resume(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->resume('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.resume(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ResumeAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/cancel/": { "post": { "summary": "取消导入作业", "description": "取消导入。已导入的内容将保留；上传的文件和密钥将被清除。", "operationId": "post_v3_session_imports_cancel", "x-didit-sdk": { "resource": "sessions.imports", "method": "cancel", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "导入任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "该任务当前的状态不支持此操作。" }, "403": { "description": "API 密钥缺失、无效或已撤销，或者调用方无法为此应用导入验证。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.cancel(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.cancel(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Cancel(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().cancel(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->cancel('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.cancel(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.CancelAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/imports/{importId}/retry/": { "post": { "summary": "重试迁移", "description": "重新运行已结束的迁移作为新作业，并使用新密钥（旧密钥已被擦除）。它将保留提供商、工作流、区域、状态映射和人脸模板选项；Didit 中已存在的所有内容都将被跳过。", "operationId": "post_v3_session_imports_retry", "x-didit-sdk": { "resource": "sessions.imports", "method": "retry", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "importId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "credentials": { "type": "object", "additionalProperties": { "type": "string" }, "description": "服务商的只读密钥，其字段名称由 `credential_fields` 列出。静态加密存储，从不返回，并在导入结束时抹除。请作为 multipart 中的 JSON 字符串发送。" }, "file": { "type": "string", "format": "binary", "description": "再次返回记录 ID 或导出文件，适用于 `api_ids` 和 `export_file` 提供商。" } } }, "example": { "credentials": { "app_token": "YOUR_PROVIDER_APP_TOKEN", "secret_key": "YOUR_PROVIDER_SECRET_KEY" } } } } }, "responses": { "201": { "description": "新的导入任务。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionImportJob" } } } }, "400": { "description": "不是迁移、未结束，或提供商拒绝了密钥。" }, "403": { "description": "API 密钥缺失、无效或已撤销，或者调用方无法为此应用导入验证。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.retry(\n \"11111111-2222-3333-4444-555555555555\",\n credentials={\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"},\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.retry(\"11111111-2222-3333-4444-555555555555\", {\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Retry(ctx, \"11111111-2222-3333-4444-555555555555\", didit.SessionsImportsRetryParams{\n\tCredentials: didit.Some(map[string]string{\"app_token\": \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\": \"YOUR_PROVIDER_SECRET_KEY\"}),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.util.Map;\nimport me.didit.Didit;\nimport me.didit.types.SessionsImportsRetryParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().retry(\"11111111-2222-3333-4444-555555555555\", SessionsImportsRetryParams.builder()\n .credentials(Map.of(\"app_token\", \"YOUR_PROVIDER_APP_TOKEN\", \"secret_key\", \"YOUR_PROVIDER_SECRET_KEY\"))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->retry('11111111-2222-3333-4444-555555555555', [\n 'credentials' => ['app_token' => 'YOUR_PROVIDER_APP_TOKEN', 'secret_key' => 'YOUR_PROVIDER_SECRET_KEY'],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.retry(\n \"11111111-2222-3333-4444-555555555555\",\n credentials: { app_token: \"YOUR_PROVIDER_APP_TOKEN\", secret_key: \"YOUR_PROVIDER_SECRET_KEY\" }\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Collections.Generic;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.RetryAsync(\"11111111-2222-3333-4444-555555555555\", new SessionsImportsRetryParams\n{\n Credentials = new Dictionary { [\"app_token\"] = \"YOUR_PROVIDER_APP_TOKEN\", [\"secret_key\"] = \"YOUR_PROVIDER_SECRET_KEY\" },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/import-jobs/": { "get": { "summary": "列出导入任务", "description": "以统一格式呈现的应用的每次导入：验证导入与迁移，包括个人与企业。", "operationId": "get_v3_import_jobs_list", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_jobs", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "scope", "in": "query", "schema": { "type": "string", "enum": [ "all", "sessions", "users", "businesses" ], "default": "all" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "导入任务，按最新优先排序。", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJobSummary" } }, "counts": { "type": "object", "properties": { "all": { "type": "integer" }, "running_and_waiting": { "type": "integer" }, "needs_attention": { "type": "integer" }, "done": { "type": "integer" } } } } } } } }, "403": { "description": "API 密钥缺失、无效或已撤销，或者调用方无法为此应用导入验证。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.list_jobs()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.listJobs();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.ListJobs(ctx, didit.SessionsImportsListJobsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().listJobs();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listJobs();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.list_jobs\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ListJobsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/import-jobs/active/": { "get": { "summary": "列出活跃的导入作业", "description": "当前正在运行或等待的内容，以及刚刚结束的内容，用于进度指示器。", "operationId": "get_v3_import_jobs_active", "x-didit-sdk": { "resource": "sessions.imports", "method": "list_active_jobs", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "responses": { "200": { "description": "进行中的导入任务。", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/ImportJobSummary" } }, "running": { "type": "integer" } } } } } }, "403": { "description": "API 密钥缺失、无效或已撤销，或者调用方无法为此应用导入验证。", "content": { "application/json": { "examples": { "Forbidden": { "value": { "detail": "You do not have permission to perform this action." } } } } } } }, "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.imports.list_active_jobs()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.imports.listActiveJobs();\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.ListActiveJobs(ctx)\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().imports().listActiveJobs();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->imports->listActiveJobs();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.imports.list_active_jobs\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.Imports.ListActiveJobsAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/organization/{organization_id}/application/{application_id}/transactions/delete/": { "delete": { "summary": "批量删除交易", "description": "永久删除一笔或多笔交易。使用 `transaction_uuids` 进行选择，或使用 `delete_all: true` 删除应用中的所有交易。\n\n删除交易时，仅属于该交易的记录也会一并删除：包括其交易方、标签、备注、支付方式关联、证件及其实体文件存储的所有版本、规则运行记录、警报、提供商结果、网络快照和 Travel Rule 数据。案件、人员和企业将予以保留；它们与已删除交易的关联将被清除。法规报告草稿将不再列出该交易，并会在不包含该交易的情况下重新生成。删除操作是永久且不可逆的；没有撤销 endpoint。\n\n如果所选交易中有任何一笔已列入已定稿的法规报告中，整个请求将被拒绝并返回 `409`，且不会删除任何内容。响应体使用 `code: in_filed_report`，并指明每笔交易以及列出该交易的报告。请删除这些报告，然后重试该请求。", "operationId": "batch_delete_transactions", "x-didit-sdk": { "resource": "transactions", "method": "batch_delete", "auth": "api_key", "server": true, "scope": "application" }, "tags": [ "Transactions" ], "parameters": [ { "name": "organization_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "组织 UUID。" }, { "name": "application_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "应用 UUID。" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "oneOf": [ { "title": "Selected transactions", "required": [ "transaction_uuids" ], "properties": { "transaction_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "要删除的 Didit 交易 UUID。除非 `delete_all` 为 true，否则为必填项。", "minItems": 1 }, "delete_all": { "type": "boolean", "enum": [ false ], "default": false, "description": "当您使用 `transaction_uuids` 选择交易时，请省略此参数或传入 `false`。" } } }, { "title": "All transactions", "required": [ "delete_all" ], "properties": { "delete_all": { "type": "boolean", "enum": [ true ], "description": "删除应用中的所有交易。`transaction_uuids` 会被忽略。" }, "transaction_uuids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "当 `delete_all` 为 true 时被忽略。" } } } ] }, "examples": { "Selected transactions": { "value": { "transaction_uuids": [ "abcdef12-3456-7890-abcd-ef1234567890", "12345678-90ab-cdef-1234-567890abcdef" ] } }, "All transactions": { "value": { "delete_all": true } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl (selected transactions)", "source": "curl -X DELETE 'https://verification.didit.me/v3/organization/11111111-2222-3333-4444-555555555555/application/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/transactions/delete/' \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"transaction_uuids\": [\"abcdef12-3456-7890-abcd-ef1234567890\"]}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\nclient = Didit()\n\nclient.transactions.batch_delete(\n body={\n \"transaction_uuids\": [\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"],\n },\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nconst didit = new Didit();\n\nawait didit.transactions.batchDelete({\n transaction_uuids: [\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"],\n});" }, { "lang": "java", "label": "Java", "source": "import java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.TransactionsBatchDeleteParams;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nDidit client = new Didit();\n\nclient.transactions().batchDelete(TransactionsBatchDeleteParams.builder()\n .putAdditionalProperty(\"transaction_uuids\", List.of(\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"))\n .build());" }, { "lang": "php", "label": "PHP", "source": "transactions->batchDelete([\n 'transaction_uuids' => ['abcdef12-3456-7890-abcd-ef1234567890', '12345678-90ab-cdef-1234-567890abcdef'],\n]);" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n# and DIDIT_APPLICATION_ID.\ndidit = Didit::Client.new\n\ndidit.transactions.batch_delete(\n body: {\n transaction_uuids: [\"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\"],\n }\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY, DIDIT_ORGANIZATION_ID\n// and DIDIT_APPLICATION_ID.\nusing var client = new DiditClient();\n\nawait client.Transactions.BatchDeleteAsync(new TransactionsBatchDeleteParams\n{\n TransactionUuids = new string[] { \"abcdef12-3456-7890-abcd-ef1234567890\", \"12345678-90ab-cdef-1234-567890abcdef\" },\n});" } ], "responses": { "204": { "description": "所选交易已删除。" }, "400": { "description": "未提供交易选择器。", "content": { "application/json": { "schema": { "type": "object", "properties": { "transaction_uuids": { "type": "array", "items": { "type": "string" } } } }, "example": { "transaction_uuids": [ "This field is required unless delete_all is true." ] } } } }, "403": { "description": "该 API 密钥无法删除交易。该 endpoint 需要 `write:transactions` 权限。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } } } } }, "409": { "description": "所选交易中至少有一笔列在已定稿的监管报告中。未删除任何内容。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InFiledReportError" } } } } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/travel-rule/networks/": { "get": { "summary": "获取 Travel Rule 网络", "description": "针对此应用读取每个网络的真实状态：是通过您自己的成员身份发送还是通过 Didit 的成员身份发送，以及目前无法发送的原因。还会返回尽职调查问卷和您的参与者。读取操作不会创建任何内容。", "operationId": "getTravelRuleNetworks", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "retrieve", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/networks/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.retrieve()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.retrieve();\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().retrieve();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->retrieve();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.retrieve\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.RetrieveAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "网络状态、问卷和参与者。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworksOverview" }, "examples": { "Before the questionnaire": { "value": { "platform_networks_enabled": false, "questionnaire": { "status": "draft", "answers": {}, "submitted_at": null, "reviewed_at": null, "review_note": "", "history": [], "updated_at": null }, "participants": [], "networks": { "gtr": { "rail": "GTR", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "trust": { "rail": "TRUST", "mode": "unavailable", "state": "unavailable", "reason": "own_membership_only", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "verifyvasp": { "rail": "VERIFYVASP", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 }, "sygna": { "rail": "SYGNA", "mode": "unavailable", "state": "didit_onboarding", "reason": "didit_membership_not_live", "platform_available": false, "connected": false, "participant": null, "vasps_reachable": 0, "routed_30d": 0 } } } } } } } }, "401": { "description": "API 密钥缺失或无效。" } } } }, "/v3/travel-rule/networks/questionnaire/": { "get": { "summary": "获取网络问卷", "description": "读取此应用对应的 Didit 网络尽职调查问卷、其状态以及 Didit 的审核备注。从未保存过问卷的应用将读取到一个空白草稿。", "operationId": "getTravelRuleNetworkQuestionnaire", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "retrieve_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET https://verification.didit.me/v3/travel-rule/networks/questionnaire/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.retrieve_questionnaire()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.retrieveQuestionnaire();\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().retrieveQuestionnaire();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->retrieveQuestionnaire();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.retrieve_questionnaire\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.RetrieveQuestionnaireAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "问卷。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" } } } }, "401": { "description": "API 密钥缺失或无效。" } } }, "put": { "summary": "保存网络问卷答案", "description": "在问卷处于 draft 或 changes_requested 状态时保存答案。保存操作是部分保存：您未发送的答案将被保留。", "operationId": "updateTravelRuleNetworkQuestionnaire", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "update_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X PUT https://verification.didit.me/v3/travel-rule/networks/questionnaire/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"legal_name\": \"Example VASP Ltd\", \"incorporation_country\": \"ES\", \"aml_ctf_policy_attested\": true}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.update_questionnaire(\n legal_name=\"Example VASP Ltd\",\n incorporation_country=\"ES\",\n aml_ctf_policy_attested=True,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.updateQuestionnaire({\n legal_name: \"Example VASP Ltd\",\n incorporation_country: \"ES\",\n aml_ctf_policy_attested: true,\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleNetworkQuestionnaireAnswers;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().updateQuestionnaire(TravelRuleNetworkQuestionnaireAnswers.builder()\n .legalName(\"Example VASP Ltd\")\n .incorporationCountry(\"ES\")\n .amlCtfPolicyAttested(true)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->updateQuestionnaire([\n 'legal_name' => 'Example VASP Ltd',\n 'incorporation_country' => 'ES',\n 'aml_ctf_policy_attested' => true,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.update_questionnaire(\n legal_name: \"Example VASP Ltd\",\n incorporation_country: \"ES\",\n aml_ctf_policy_attested: true\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.UpdateQuestionnaireAsync(new TravelRuleNetworkQuestionnaireAnswers\n{\n LegalName = \"Example VASP Ltd\",\n IncorporationCountry = \"ES\",\n AmlCtfPolicyAttested = true,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaireAnswers" }, "example": { "legal_name": "Example VASP Ltd", "incorporation_country": "ES", "aml_ctf_policy_attested": true } } } }, "responses": { "200": { "description": "包含合并后答案的问卷。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" } } } }, "400": { "description": "验证错误，以字段为键。" }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "通过 Didit 会员资格访问网络目前尚未开放。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_platform_networks_disabled" ] } } } } } }, "409": { "description": "问卷由 Didit 处理或已做出决策：仅在处于 draft 或 changes_requested 状态时才可更改。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_questionnaire_not_editable" ] } } } } } } } } }, "/v3/travel-rule/networks/questionnaire/submit/": { "post": { "summary": "提交网络问卷", "description": "将已保存的问卷提交给 Didit 进行审核。已保存的回答必须完整：除 lei 和 data_protection_contact_email 之外的每个字段均须填写，且三项证明必须为 true。Didit 会批准、要求修改（编辑并重新提交）或拒绝该问卷。当问卷获批时，您在其处于待处理状态期间所请求的网络将被移交至其入驻流程。", "operationId": "submitTravelRuleNetworkQuestionnaire", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "submit_questionnaire", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/networks/questionnaire/submit/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.submit_questionnaire()\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.submitQuestionnaire();\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().submitQuestionnaire();\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->submitQuestionnaire();\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.submit_questionnaire\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.SubmitQuestionnaireAsync();\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已提交的问卷。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" } } } }, "400": { "description": "保存的答案不完整或无效，以字段为键。" }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "通过 Didit 会员资格访问网络目前尚未开放。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_platform_networks_disabled" ] } } } } } }, "409": { "description": "问卷由 Didit 处理或已做出决策：仅在处于 draft 或 changes_requested 状态时才可更改。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_questionnaire_not_editable" ] } } } } } } } } }, "/v3/travel-rule/networks/{network}/request/": { "post": { "summary": "申请 Travel Rule 网络", "description": "在 Didit 会员资格支持的网络（GTR 或 Sygna）上申请此应用专属的参与者。如果没有已通过的问卷，参与者将等待问卷（questionnaire_pending）；如果有，则进入网络入驻流程（submitted_to_network），并在网络分配代码后激活。具有幂等性：处于待处理、入驻中或已上线状态的参与者将原样返回。如果网络拒绝了注册（设置了 last_error），再次请求将重试。TRUST 和 VerifyVASP 仅可通过您自己的会员资格访问：TRUST 按 VASP 接纳成员，而 VerifyVASP Enclave 仅服务于一个 VASP ID。", "operationId": "requestTravelRuleNetworkAccess", "x-didit-sdk": { "resource": "travel_rule.networks", "method": "request_access", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "network", "in": "path", "required": true, "schema": { "type": "string", "enum": [ "gtr", "sygna" ] }, "description": "通过 Didit 成员身份加入的网络。" } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/networks/gtr/request/ \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.networks.request_access(\n \"your-network\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.networks.requestAccess(\"your-network\");\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().networks().requestAccess(\"your-network\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->networks->requestAccess('your-network');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.networks.request_access(\"your-network\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.Networks.RequestAccessAsync(\"your-network\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "您在该网络上的参与方。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleNetworkParticipant" } } } }, "400": { "description": "未知网络、Didit 不支持的网络（连接您自己的会员资格），或沙盒应用。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_network_own_membership_only", "travel_rule_network_sandbox_application" ] } } } } } }, "401": { "description": "API 密钥缺失或无效。" }, "403": { "description": "通过 Didit 会员资格访问网络目前尚未开放。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "travel_rule_platform_networks_disabled" ] } } } } } } } } }, "/v3/address-validation/": { "post": { "summary": "核验地址", "description": "确认地址存在并获取规范化结果：其投递行、组成部分和坐标。该接口仅确认地址；绝不会将地址与个人关联。\n\n**请求。**将地址作为单行（`address`）或结构化字段（`address_line_1`，以及可选的 `address_line_2`、`city`、`region`、`postal_code`）发送，不能同时使用两者，且必须提供其 `country`（ISO 3166-1 alpha-2 或 alpha-3）。\n\n**结果。**`address_validation.status` 包括 `verified`（已确认到建筑物）、`partially_verified`（仅确认到街道或更高级别）、`not_verified`（仅匹配到地区或城市，或完全未匹配）或 `unavailable`（验证无法运行）。每个已完成的请求 HTTP 状态码均为 `200`，包括 `unavailable`；若结果为 `unavailable`，请稍后重试。\n\n**计费。**生产环境调用按每条验证地址 $0.10 收费。结果为 `unavailable` 时不收费。除使用记录外不存储任何内容：不会创建会话，且结果仅在此响应中返回。\n\n**沙盒。**沙盒密钥会验证请求并始终返回一个反映所发送地址的确定性 `verified` 结果，且不消耗额度。\n\n**身份验证。**在 `x-api-key` 中发送您应用的 API 密钥。缺失或无效的凭据将返回 `403`：此 API 绝不会返回 `401`。\n\n**速率限制。**各 POST/PATCH/DELETE endpoint 间每个 API 密钥共享每分钟 300 次请求的写入预算（创建交易和事件摄取具有单独的 600 次预算）。", "operationId": "post_v3_address_validation", "x-didit-sdk": { "resource": "address_validation", "method": "validate", "auth": "api_key", "server": true }, "tags": [ "Standalone APIs" ], "security": [ { "ApiKeyAuth": [] } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/address-validation/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\n \"address_line_1\": \"1600 Amphitheatre Pkwy\",\n \"city\": \"Mountain View\",\n \"region\": \"CA\",\n \"postal_code\": \"94043\",\n \"country\": \"US\"\n }'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.address_validation.validate(\n address_line_1=\"1600 Amphitheatre Pkwy\",\n city=\"Mountain View\",\n region=\"CA\",\n postal_code=\"94043\",\n country=\"US\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.addressValidation.validate({\n address_line_1: \"1600 Amphitheatre Pkwy\",\n city: \"Mountain View\",\n region: \"CA\",\n postal_code: \"94043\",\n country: \"US\",\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.AddressValidationRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.addressValidation().validate(AddressValidationRequest.builder()\n .addressLine1(\"1600 Amphitheatre Pkwy\")\n .city(\"Mountain View\")\n .region(\"CA\")\n .postalCode(\"94043\")\n .country(\"US\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "addressValidation->validate([\n 'address_line_1' => '1600 Amphitheatre Pkwy',\n 'city' => 'Mountain View',\n 'region' => 'CA',\n 'postal_code' => '94043',\n 'country' => 'US',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.address_validation.validate(\n address_line_1: \"1600 Amphitheatre Pkwy\",\n city: \"Mountain View\",\n region: \"CA\",\n postal_code: \"94043\",\n country: \"US\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.AddressValidation.ValidateAsync(new AddressValidationRequest\n{\n AddressLine1 = \"1600 Amphitheatre Pkwy\",\n City = \"Mountain View\",\n Region = \"CA\",\n PostalCode = \"94043\",\n Country = \"US\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationRequest" }, "examples": { "Structured": { "summary": "结构化地址字段", "value": { "address_line_1": "1600 Amphitheatre Pkwy", "city": "Mountain View", "region": "CA", "postal_code": "94043", "country": "US" } }, "One line": { "summary": "单行完整地址", "value": { "address": "Paseo de la Castellana 259, 28046 Madrid", "country": "ES" } } } } } }, "responses": { "200": { "description": "核验已完成。请读取 `address_validation.status`；已完成的请求其 HTTP 状态码始终为 `200`。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressValidationResponse" }, "examples": { "Verified": { "summary": "真实地址，已确认至建筑物级别", "value": { "request_id": "6f7d2c1e-1c5a-4a1e-9b8f-2a1f0f4b9c3d", "address_validation": { "status": "verified", "verification_level": "premise", "address": { "address_line_1": "1600 Amphitheatre Pkwy", "address_line_2": null, "city": "Mountain View", "region": "CA", "postal_code": "94043-1351", "country": "US" }, "formatted_address": "1600 Amphitheatre Pkwy, Mountain View CA 94043-1351", "latitude": 37.422022, "longitude": -122.08429 }, "created_at": "2026-10-27T11:20:00.000000+00:00" } }, "Not verified": { "summary": "虚构的街道：仅城市匹配", "value": { "request_id": "0b9e3f4a-6c2d-4e8b-a1f7-5d3c2b1a0e9f", "address_validation": { "status": "not_verified", "verification_level": "locality", "address": { "address_line_1": "Calle Inventada Que No Existe 99999 28046", "address_line_2": null, "city": "Madrid", "region": "Madrid", "postal_code": null, "country": "ES" }, "formatted_address": "Calle Inventada Que No Existe 99999 28046, Madrid, MADRID, SPAIN", "latitude": 40.42603054, "longitude": -3.68645331 }, "created_at": "2026-10-27T11:21:00.000000+00:00" } }, "Unavailable": { "summary": "核验无法运行；未收取费用", "value": { "request_id": "3c1b2a0f-9e8d-4c7b-b6a5-1f0e9d8c7b6a", "address_validation": { "status": "unavailable", "verification_level": null, "address": null, "formatted_address": null, "latitude": null, "longitude": null }, "created_at": "2026-10-27T11:22:00.000000+00:00" } } } } } }, "400": { "$ref": "#/components/responses/AddressValidationValidationError" }, "403": { "$ref": "#/components/responses/AddressValidationPermissionDenied" }, "429": { "$ref": "#/components/responses/RateLimitedWrite" } } } }, "/v3/travel-rule/wallet-proofs/": { "get": { "summary": "列出待审核的钱包截图证明", "description": "您的屏幕截图钱包所有权证明审核队列。屏幕截图是 Didit 无法自行核验的唯一一种证明：终端用户从小组件上传后，它将处于 PENDING 状态，直到您通过 POST /v3/travel-rule/wallet-proofs/{proof_uuid}/decision/ 进行批准或拒绝。按时间从早到晚排序，因此队列从等待时间最长的证明开始处理。仅显示已上传的屏幕截图，终端用户尚未上传文件的证明绝不会出现，您从地址簿中删除的钱包的证明也绝不会出现（Didit 会将这些证明关闭为 OWNERSHIP_CHANGED）。", "operationId": "listTravelRuleWalletProofs", "x-didit-sdk": { "resource": "travel_rule.wallet_proofs", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "status", "in": "query", "description": "要列出哪些证明。默认为 PENDING，即尚待决定的证明。", "schema": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ], "default": "PENDING" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 50, "minimum": 1 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "default": 0, "minimum": 0 } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl https://verification.didit.me/v3/travel-rule/wallet-proofs/?status=PENDING \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.wallet_proofs.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.walletProofs.list()) {\n console.log(item);\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().walletProofs().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletProofs->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.wallet_proofs.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.WalletProofs.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ], "responses": { "200": { "description": "分页截图证明。数量在 100 以内时为精确值，超过 100 时上限截断为 100。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleWalletProofReview" } } } } } } }, "400": { "description": "未知状态。" }, "401": { "description": "x-api-key 缺失或无效。" }, "403": { "description": "调用方缺少交易权限。" } } } }, "/v3/travel-rule/wallet-proofs/{proof_uuid}/decision/": { "post": { "summary": "批准或拒绝钱包截图证明", "description": "从您的审核队列中裁决屏幕截图证明。approve 会验证该证明和地址簿条目，并将股权结构应用于创建该挂件会话所针对的转账，与已验证签名的效果完全相同。屏幕截图永远无法确认另一位 Didit 客户通过 INTERNAL 轨道发送的转账：该操作需要签名消息或测试充值。reject 会将该证明关闭为 REJECTED，failure_reason 为 REVIEW_REJECTED；终端用户可以从挂件启动新的证明。备注会与证明一同保留。", "operationId": "decideTravelRuleWalletProof", "x-didit-sdk": { "resource": "travel_rule.wallet_proofs", "method": "decide", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "proof_uuid", "in": "path", "required": true, "description": "来自审核队列的 proof_id。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWalletProofDecision" }, "example": { "decision": "approve", "note": "Address matches the wallet app." } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/wallet-proofs/{proof_uuid}/decision/ \\\n -H 'x-api-key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"decision\": \"approve\", \"note\": \"Address matches the wallet app.\"}'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.wallet_proofs.decide(\n \"11111111-2222-3333-4444-555555555555\",\n decision=\"approve\",\n note=\"Address matches the wallet app.\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.walletProofs.decide(\"11111111-2222-3333-4444-555555555555\", {\n decision: \"approve\",\n note: \"Address matches the wallet app.\",\n});\nconsole.log(result);" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleWalletProofDecision;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().walletProofs().decide(\"11111111-2222-3333-4444-555555555555\", TravelRuleWalletProofDecision.builder()\n .decision(TravelRuleWalletProofDecision.Decision.of(\"approve\"))\n .note(\"Address matches the wallet app.\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->walletProofs->decide('11111111-2222-3333-4444-555555555555', [\n 'decision' => 'approve',\n 'note' => 'Address matches the wallet app.',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.wallet_proofs.decide(\n \"11111111-2222-3333-4444-555555555555\",\n decision: \"approve\",\n note: \"Address matches the wallet app.\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.WalletProofs.DecideAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleWalletProofDecision\n{\n Decision = \"approve\",\n Note = \"Address matches the wallet app.\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "已确定的证明。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWalletProofReview" } } } }, "400": { "description": "无效的决策，或备注超过 512 个字符。" }, "401": { "description": "x-api-key 缺失或无效。" }, "403": { "description": "调用方缺少交易权限。" }, "404": { "description": "您的应用中不存在具有此 ID 的已提交屏幕截图证明。" }, "409": { "description": "证明已做出决策（响应体携带其状态），或者错误码为 OWNERSHIP_CHANGED：生成小部件会话后钱包持有者发生变更或钱包被删除，因此证明已关闭且当前持有者需要新的证明。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } } } } }, "/v3/travel-rule/widget/{token}/proofs/": { "post": { "summary": "发起钱包所有权证明", "description": "基于小部件会话 token 的公开 endpoint，无需 API 密钥：当终端用户选择证明方法时，托管小部件会调用此接口。证明仅在发生此调用后才会存在并计入您的证明转化漏斗。再次选择相同方法将返回已开启的证明（200，相同的 challenge 或充值金额），而不会发起第二个证明；选择其他方法则会将未完成的证明关闭为 METHOD_SWITCHED（已提交的屏幕截图或仍在检查中的测试充值除外）。MESSAGE_SIGNING 返回待签名的 challenge；SATOSHI_TEST 返回充值地址、精确金额和时间窗口；SELF_DECLARATION 则立即可通过验证（状态为 VERIFIED）。各链族验证的签名格式：EVM 链采用十六进制编码的 personal_sign (EIP-191) 签名；比特币采用 Base64 编码的 BIP-137 signmessage 签名（P2PKH、P2SH-P2WPKH 和 P2WPKH 地址）或 BIP-322 simple 签名（P2WPKH 和 P2TR 地址）；Solana 采用对 challenge 进行签名且以 Base58 编码的 Ed25519 签名；Tron 采用十六进制编码的 signMessageV2 (TIP-191) 签名。BIP-322 full 签名、资金证明签名或多签地址将因 SIGNATURE_UNSUPPORTED_SCHEME 而失败。", "operationId": "createTravelRuleWidgetProof", "x-didit-sdk": { "resource": "travel_rule", "method": "create_widget_proof", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "生成 widget 会话时返回的不透明会话 token。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofCreate" } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget/{token}/proofs/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"method\": \"MESSAGE_SIGNING\"}'" } ], "responses": { "201": { "description": "新的 PENDING 证明（SELF_DECLARATION 为 VERIFIED）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofSummary" } } } }, "200": { "description": "已恢复此前为此方式打开的证明。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofSummary" } } } }, "400": { "description": "无效的请求体、钱包与转账不匹配、不允许 SCREENSHOT，或者当该方法在对应链上不可用时返回代码 CHAIN_UNSUPPORTED。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "403": { "description": "此应用不允许 SELF_DECLARATION。" }, "404": { "description": "未知的 token。" }, "409": { "description": "代码 OWNERSHIP_CHANGED：生成会话后钱包的持有者发生变更，或钱包已被删除；请为当前持有者生成新会话。当会话缺少 satoshi_deposit_address 时针对 SATOSHI_TEST 也会返回此代码；当会话没有剩余尝试次数时也会返回此响应（不含代码；响应体包含 max_attempts、attempts_used 以及值为 0 的 attempts_remaining）：请生成新会话。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "410": { "description": "会话已过期。" } } } }, "/v3/travel-rule/widget/{token}/proofs/{proof_id}/verify/": { "post": { "summary": "提交钱包所有权证明材料", "description": "基于小部件会话 token 的公开 endpoint，无需 API 密钥。发送该证明方法所需的凭据：MESSAGE_SIGNING 需提供签名，SATOSHI_TEST 需提供 txid（JSON），SCREENSHOT 需提供文件（multipart）。每次提交均计为一次尝试。验证失败的签名或不匹配的充值将返回 400 状态码及错误代码，并使证明保持 PENDING 状态，以便终端用户重试。已检测到但尚未确认的充值将返回 200 及状态 PENDING，并在时间窗口关闭前自动重新检查。屏幕截图将返回 200 及状态 PENDING，并在您的审核队列中等待处理（GET /v3/travel-rule/wallet-proofs/）。EXPIRED 或 REJECTED 状态的证明后续绝不会通过验证：请发起新的证明。各链族验证的签名格式：EVM 链采用十六进制编码的 personal_sign (EIP-191) 签名；比特币采用 Base64 编码的 BIP-137 signmessage 签名（P2PKH、P2SH-P2WPKH 和 P2WPKH 地址）或 BIP-322 simple 签名（P2WPKH 和 P2TR 地址）；Solana 采用对 challenge 进行签名且以 Base58 编码的 Ed25519 签名；Tron 采用十六进制编码的 signMessageV2 (TIP-191) 签名。BIP-322 full 签名、资金证明签名或多签地址将因 SIGNATURE_UNSUPPORTED_SCHEME 而失败。", "operationId": "verifyTravelRuleWidgetProof", "x-didit-sdk": { "resource": "travel_rule", "method": "verify_widget_proof", "auth": "public", "server": false }, "tags": [ "Travel Rule" ], "security": [ {} ], "parameters": [ { "name": "token", "in": "path", "required": true, "description": "生成 widget 会话时返回的不透明会话 token。", "schema": { "type": "string" } }, { "name": "proof_id", "in": "path", "required": true, "description": "启动证明时返回的 proof_id。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "signature": { "type": "string", "description": "MESSAGE_SIGNING：钱包对证明挑战的签名。" }, "txid": { "type": "string", "description": "SATOSHI_TEST：测试存款的交易 ID。" } } } }, "multipart/form-data": { "schema": { "type": "object", "required": [ "file" ], "properties": { "file": { "type": "string", "format": "binary", "description": "SCREENSHOT：显示终端用户钱包应用中钱包的图片。" } } } } } }, "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST https://verification.didit.me/v3/travel-rule/widget/{token}/proofs/{proof_id}/verify/ \\\n -H 'Content-Type: application/json' \\\n -d '{\"signature\": \"0x...\"}'" } ], "responses": { "200": { "description": "VERIFIED，或仍为 PENDING（待审核的截图、尚未索引或尚未确认的存款，错误代码为 DEPOSIT_NOT_FOUND 或 DEPOSIT_UNCONFIRMED）。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofVerifyResult" } } } }, "400": { "description": "缺少证明材料；失败的尝试使证明保持 PENDING 状态以便终端用户重试（错误代码 SIGNATURE_INVALID、SIGNATURE_UNSUPPORTED_SCHEME 或 DEPOSIT_LOOKUP_FAILED）；或者测试充值导致证明被拒绝（错误代码 DEPOSIT_MISMATCH、DEPOSIT_STALE 或 TXID_REUSED，状态 REJECTED，并附带该会话的尝试次数）：在 attempts_remaining 大于 0 时，重新选择方式将启动新的证明。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "404": { "description": "未知的 token，或此会话没有此类证明。" }, "409": { "description": "代码 OWNERSHIP_CHANGED（证明以此代码关闭）；已关闭的证明（REJECTED 或 EXPIRED），包含其状态、关闭时的代码以及会话的尝试次数：重新选择一种方式以发起新的证明；或 SELF_DECLARATION 证明，在发起时即已验证。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } }, "410": { "description": "会话已过期，或在中本聪测试窗口关闭时返回代码 WINDOW_EXPIRED。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleWidgetProofError" } } } } } } }, "/v3/id-verification/wallets/verifications/{request_id}/response/": { "post": { "operationId": "submit_wallet_verification_response", "x-didit-sdk": { "resource": "id_wallets", "method": "submit_verification_response", "auth": "api_key", "server": true }, "description": "数字凭证 API 钱包（Google Wallet）：针对 next_action 为 request_digital_credential 的验证，将钱包返回给您页面或应用的内容发送过来。Didit 会解密该内容，对照受信任签发方根证书核验签发方签名，对照签名摘要核验每个返回的值，并核验设备针对您的源站和此请求的签名，然后对验证做出决策：已通过（计费一次）或附带错误代码的已拒绝。一次性使用：第二次提交会返回已做出决策的验证。", "summary": "提交钱包响应", "parameters": [ { "in": "path", "name": "request_id", "schema": { "type": "string", "format": "uuid" }, "description": "start endpoint 返回的 request_id。", "required": true } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialResponseRequest" }, "example": { "response": { "protocol": "openid4vp-v1-signed", "data": { "response": "" } } } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialResponseRequest" }, "example": { "response": { "protocol": "openid4vp-v1-signed", "data": { "response": "" } } } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialResponseRequest" }, "example": { "response": { "protocol": "openid4vp-v1-signed", "data": { "response": "" } } } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "google_wallet", "name": "Google Wallet", "issuing_authority": "Google Wallet (ID pass) and US state issuers (mobile driving licence)" }, "country": "USA", "status": "Approved", "outcome": "verified", "error": null, "interaction": "digital_credentials", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": null, "identity": { "full_name": "Alex Example", "first_name": "Alex", "last_name": "Example", "date_of_birth": "1990-01-31", "nationality": "USA", "issuing_state": "USA" }, "attributes": { "document_number": "X0000000", "document_expiry_date": "2030-01-31" }, "level_of_assurance": "substantial", "verified_at": "2026-01-01T10:01:00Z", "signature_valid": true, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" } } }, "description": "缺少凭据（x-api-key 或 Authorization: Bearer）。" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 not_found：此应用下没有任何钱包验证具有该 request_id。" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}）。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 not_a_digital_credentials_wallet：此验证不接收钱包响应。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法验证该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/response/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"response\": {\n \"protocol\": \"openid4vp-v1-signed\",\n \"data\": {\n \"response\": \"\"\n }\n }\n}'" } ] } }, "/v3/id-verification/wallets/google-wallet/": { "post": { "operationId": "start_google_wallet_wallet_verification", "x-didit-sdk": { "resource": "id_wallets", "method": "start_google_wallet", "auth": "api_key", "server": true }, "description": "在无需任何工作流的情况下启动 Google Wallet 登录（Google Wallet（身份证件凭证）及美国各州签发机构（移动驾照）；USA、GBR、BRA、SGP、TWN）。仅在身份验证成功时计费一次。响应包含 next_action.type=request_digital_credential 以及 Didit 为您的应用签名的请求，该请求仅可从来源使用。在用户手势触发时，将 next_action.digital_credentials.request 传递给 navigator.credentials.get({digital: ...})（或作为 GetDigitalCredentialOption requestJson 传递给 Android Credential Manager），然后将钱包返回的内容 POST 到 /v3/id-verification/wallets/verifications/{request_id}/response/。当钱包位于其他设备上时，浏览器会提供其自带的二维码。沙盒应用将获得确定性模拟（simulated: true），绝不会联系服务商。", "summary": "开始 Google Wallet 验证", "parameters": [ { "in": "header", "name": "Idempotency-Key", "schema": { "type": "string" }, "description": "可选的重试安全密钥（最多 255 个字符）。使用相同的密钥、钱包和请求体进行重试将返回原始验证结果，而不会发起第二次登录；若将相同密钥用于其他钱包或请求体，则返回 409 idempotency_key_reused。" } ], "tags": [ "Digital ID wallets" ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest" }, "example": { "country": "USA", "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "origin": "https://app.example.com" } }, "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest" } }, "multipart/form-data": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest" } } }, "required": true }, "security": [ { "ApiKeyAuth": [] }, { "BearerAuth": [] } ], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResponse" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "wallet_verification": { "wallet": { "id": "google_wallet", "name": "Google Wallet", "issuing_authority": "Google Wallet (ID pass) and US state issuers (mobile driving licence)" }, "country": "USA", "status": "Not Finished", "outcome": "pending", "error": null, "interaction": "digital_credentials", "simulated": false, "expires_at": "2026-01-01T10:10:00Z", "next_action": { "type": "request_digital_credential", "digital_credentials": { "protocol": "openid4vp-v1-signed", "request": { "requests": [ { "protocol": "openid4vp-v1-signed", "data": { "request": "" } } ] } } }, "identity": null, "attributes": null, "level_of_assurance": null, "verified_at": null, "signature_valid": null, "credential_type": "person_identification" }, "vendor_data": "your-customer-reference", "metadata": { "reference": "example" }, "created_at": "2026-01-01T10:00:00Z" } } }, "description": "" }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartBadRequest" } } }, "description": "字段验证错误（{field: [messages]}），或错误 return_url_invalid、return_url_not_allowed、origin_invalid、origin_not_allowed、invalid_personal_code、invalid_phone_number 或 idempotency_key_invalid。" }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationStartForbidden" } } }, "description": "缺少凭据（{detail}），或出现 wallet_unavailable、insufficient_credits 或 contract_rate_missing 错误。" }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 idempotency_key_reused 或 idempotency_key_in_progress（附带 Retry-After）。" }, "502": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_provider_unavailable：提供商无法启动；未创建任何内容。" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } } }, "description": "错误 wallet_not_configured：此环境无法访问该钱包。" } }, "x-codeSamples": [ { "lang": "curl", "label": "cURL", "source": "curl --request POST \\\n --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \\\n --header 'x-api-key: YOUR_API_KEY' \\\n --header 'Idempotency-Key: your-unique-attempt-key' \\\n --header 'Content-Type: application/json' \\\n --data '{\n \"country\": \"USA\",\n \"vendor_data\": \"your-customer-reference\",\n \"metadata\": {\n \"reference\": \"example\"\n },\n \"origin\": \"https://app.example.com\"\n}'" } ], "x-didit-wallet-id": "google_wallet" } }, "/v3/session/{sessionId}/kyb/documents/": { "post": { "summary": "向会话上传 KYB 证件", "description": "从您自己的服务器而非托管页面，将一份或多份企业文件（公司章程、股东名册、公司注册证书等）上传到企业验证会话的 KYB 证件步骤。Didit 会运行托管流水线：压缩、OCR、防篡改和跨证件比对、证件分组，并在满足所需的证件分组时推进会话。无论您发送多少个文件，该步骤均按固定单价收取一次费用。会话必须处于进行中且处于 KYB 证件步骤，并且在公司登记步骤中选择的公司必须存在。通过 `GET /v3/session/{sessionId}/kyb/extracted-parties/` 读取证件中指名的人员。需要 `write:businesses` 权限。", "operationId": "post_v3_session_kyb_documents", "x-didit-sdk": { "resource": "sessions", "method": "upload_kyb_documents", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "企业验证（KYB）会话的 UUID。它必须属于 API 密钥所属的应用。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "KYB 步骤的工作流节点。仅在工作流具有多个 KYB 节点时需要；默认情况下，Didit 会使用会话自身的节点。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "required": [ "documents" ], "properties": { "documents": { "type": "array", "items": { "type": "string", "format": "binary" }, "description": "待上传的文件：JPG、JPEG、PNG、TIFF、WEBP、PDF 或它们的 ZIP 压缩包。PDF 最大 50 MB，照片压缩前最大 6 MB。" }, "document_passwords": { "type": "array", "items": { "type": "string" }, "description": "`documents` 中的每个文件按相同顺序对应一个条目：受密码保护的 PDF 填写密码，其他任何文件留空。" }, "document_group": { "type": "string", "enum": [ "LEGAL_PRESENCE", "COMPANY_DETAILS", "OWNERSHIP_STRUCTURE", "REPRESENTATIVES_AUTHORIZATION" ], "description": "此上传所对应的必需证件组。" }, "locale": { "type": "string", "maxLength": 10, "description": "用于翻译下一步响应的区域设置。" } } } } } }, "responses": { "200": { "description": "已处理的证件。当所有必需组均满足时，会话将推进，且 `next_step` 指明下一步骤；否则会话将停留在 Documents 步骤，并由 `document_groups` 和 `document_answer` 说明仍缺少的内容。", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "next_step": { "type": "string", "nullable": true, "description": "上传后会话所处的步骤。" }, "kyb_status": { "type": "string", "description": "公司核验的状态。" }, "document_answer": { "type": "object", "additionalProperties": true, "description": "每个已上传证件的结果以及剩余的上传次数。" } }, "additionalProperties": true }, "example": { "valid": true, "next_step": "KYB_KEY_PEOPLE", "kyb_status": "In Progress" } } } }, "400": { "description": "证件被拒绝（篡改、无法辨认或不受支持），或者会话中尚无 KYB 企业。在剩余尝试次数内使用其他文件重试。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "message": "No KYB company found. Submit company data first." } } } }, "402": { "description": "该组织已无可用额度用于证件步骤。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "detail": "Insufficient credits." } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除、属于另一个应用或超出了限定作用域密钥的限制；无法通过 detail 区分具体情况。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "会话已完成（`kyb_session_not_writable`）或未处于 KYB 证件步骤（`kyb_step_mismatch`，`next_step` 指明其当前所处的步骤）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" }, "code": { "type": "string" }, "next_step": { "type": "string" } } }, "example": { "detail": "The session is not on the step this operation completes.", "code": "kyb_step_mismatch", "next_step": "KYB_REGISTRY" } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟 300 次写入（POST、PATCH、DELETE）请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 响应头显示了额度。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } }, "503": { "$ref": "#/components/responses/DocumentProcessingBusy" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.upload_kyb_documents(\n \"33333333-4444-5555-6666-777777777777\",\n documents=[open(\"document.pdf\", \"rb\")],\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit, { fileFromPath } from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.uploadKybDocuments(\"33333333-4444-5555-6666-777777777777\", {\n documents: [await fileFromPath(\"document.pdf\")],\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UploadKYBDocuments(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsUploadKYBDocumentsParams{\n\tDocuments: []didit.File{didit.FileFromPath(\"document.pdf\")},\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.nio.file.Path;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsUploadKybDocumentsParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().uploadKybDocuments(\"33333333-4444-5555-6666-777777777777\", SessionsUploadKybDocumentsParams.builder()\n .documents(List.of(Path.of(\"document.pdf\")))\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->uploadKybDocuments('33333333-4444-5555-6666-777777777777', [\n 'documents' => [File::fromPath('document.pdf')],\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.upload_kyb_documents(\n \"33333333-4444-5555-6666-777777777777\",\n documents: [Pathname(\"document.pdf\")]\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UploadKybDocumentsAsync(\"33333333-4444-5555-6666-777777777777\", new SessionsUploadKybDocumentsParams\n{\n Documents = new FileUpload[] { FileUpload.FromPath(\"document.pdf\") },\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/extracted-parties/": { "get": { "summary": "列出上传证件中所提及的当事方", "description": "返回上传到此 KYB 会话的证件中所提及的股东和董事，按人合并并归属于提及他们的证件。将他们展示给您的申请人以进行确认，然后使用参与方草稿 endpoint 进行申报。范围值仍保持范围格式：`ownership_percent.text` 保留原样的数值文本，而 `min` / `max` 保留从中读取的数字。此处没有人会被标记为 UBO；该判定是在提交参与方时，根据工作流的角色设置和股权结构阈值来决定的。相同的列表也包含在会话决策中的 `document_verifications[].extracted_parties` 内。需要 `read:businesses` 或 `read:sessions`。", "operationId": "get_v3_session_kyb_extracted_parties", "x-didit-sdk": { "resource": "sessions", "method": "list_kyb_extracted_parties", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "企业验证（KYB）会话的 UUID。它必须属于 API 密钥所属的应用。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "KYB 步骤的工作流节点。仅在工作流具有多个 KYB 节点时需要；默认情况下，Didit 会使用会话自身的节点。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "当前证件中注明的当事方。", "content": { "application/json": { "schema": { "type": "object", "required": [ "parties", "document_count" ], "properties": { "parties": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "appointment_date": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "roles": { "type": "array", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "ownership_percent": { "type": "object", "properties": { "text": { "type": "string", "nullable": true, "description": "文件上明确注明的持股比例数值，例如 `25-50%`、`>50%` 或 `NO EXHIBE`。" }, "min": { "type": "number", "nullable": true, "description": "从 `text` 中读取的较小数字；未说明时为 null。" }, "max": { "type": "number", "nullable": true, "description": "从 `text` 中读取的数值上限；当未注明时为 null。" } } } } } }, "documents": { "type": "array", "description": "提及该参与方的已上传证件。", "items": { "type": "object", "properties": { "document_uuid": { "type": "string", "format": "uuid" }, "document_type": { "type": "string", "nullable": true }, "document_subtype": { "type": "string", "nullable": true }, "original_filename": { "type": "string", "nullable": true }, "status": { "type": "string", "nullable": true } } } } } }, "description": "上传证件中提及的股东和董事，按人合并。此处不会将任何人标记为 UBO：该标记在提交各方信息时确定。" }, "document_count": { "type": "integer", "description": "读取该列表所来源的已上传证件数量。" }, "node_id": { "type": "string", "nullable": true } } }, "example": { "parties": [ { "name": "Ana Lopez", "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "appointment_date": null, "designation": "Administrador unico", "roles": [ { "role": "shareholder", "ownership_percent": { "text": "60%", "min": 60, "max": 60 } } ], "documents": [ { "document_uuid": "0a3f1e2c-7c2f-4a1b-9d55-2f8d2a5d6b41", "document_type": "OWNERSHIP_STRUCTURE", "document_subtype": "ARTICLES_OF_INCORPORATION", "original_filename": "acta_constitutiva.pdf", "status": "Approved" } ] } ], "document_count": 1, "node_id": "node_kyb_documents" } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除、属于另一个应用或超出了限定作用域密钥的限制；无法通过 detail 区分具体情况。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "detail": "Session not found." } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.list_kyb_extracted_parties(\n \"33333333-4444-5555-6666-777777777777\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listKybExtractedParties(\"33333333-4444-5555-6666-777777777777\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListKYBExtractedParties(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsListKYBExtractedPartiesParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().listKybExtractedParties(\"33333333-4444-5555-6666-777777777777\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listKybExtractedParties('33333333-4444-5555-6666-777777777777');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_kyb_extracted_parties(\"33333333-4444-5555-6666-777777777777\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListKybExtractedPartiesAsync(\"33333333-4444-5555-6666-777777777777\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/parties/drafts/": { "get": { "summary": "列出 KYB 相关方草稿", "description": "列出您正在为此 KYB 会话准备的参与方，按创建时间从早到晚排序。草稿并非正式申报的参与方：它不会出现在决策或控制台中，且在您通过 `POST /v3/session/{sessionId}/kyb/parties/submit/` 提交之前不会创建验证会话。需要 `write:businesses` 权限。", "operationId": "get_v3_session_kyb_party_drafts", "x-didit-sdk": { "resource": "sessions", "method": "list_kyb_party_drafts", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "企业验证（KYB）会话的 UUID。它必须属于 API 密钥所属的应用。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "KYB 步骤的工作流节点。仅在工作流具有多个 KYB 节点时需要；默认情况下，Didit 会使用会话自身的节点。", "schema": { "type": "string" } } ], "responses": { "200": { "description": "存储的草稿。", "content": { "application/json": { "schema": { "type": "object", "properties": { "parties": { "type": "array", "items": { "type": "object", "required": [ "draft_id", "created_at", "updated_at", "party" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "party": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "该主体是个人还是公司。" }, "full_name": { "type": "string", "maxLength": 255, "description": "个人的姓名。发送此字段，或者发送 `first_name` 和 `last_name`。" }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "当事方持有的角色。可与 `roles` 互换；两者都发送时将被合并。" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "该主体拥有的每个角色。人员至少需要一个角色（在此处或在 `role` 中）。" }, "position": { "type": "string", "maxLength": 128, "description": "个人的职位头衔。" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "企业相关方的名称。当 `entity_type` 为 `company` 时必填。" }, "registration_number": { "type": "string", "maxLength": 100, "description": "企业关联方的注册号。" }, "email": { "type": "string", "format": "email", "description": "验证链接发送到的位置。当当事方必须完成验证时为必填项，这取决于工作流的角色设置和股权结构阈值。" }, "ownership_percent": { "type": "number", "nullable": true, "description": "该方拥有的公司股份比例。" }, "nationality": { "type": "string", "maxLength": 100, "description": "个人的国籍，或企业的注册国家/地区。每个当事方都必须提供此信息。" }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "工作流定义的附加字段。" }, "skip_verification": { "type": "boolean", "default": false, "description": "请求跳过此主体的验证。仅当主体的角色在工作流的“关键人员”设置中允许跳过时才有效。" } } } } } }, "node_id": { "type": "string", "nullable": true } } }, "example": { "parties": [ { "draft_id": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d", "created_at": "2026-10-31T10:00:00Z", "updated_at": "2026-10-31T10:00:00Z", "party": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 60, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } ], "node_id": "node_kyb_key_people" } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除、属于另一个应用或超出了限定作用域密钥的限制；无法通过 detail 区分具体情况。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "detail": "Session not found." } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.list_kyb_party_drafts(\n \"33333333-4444-5555-6666-777777777777\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.listKybPartyDrafts(\"33333333-4444-5555-6666-777777777777\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ListKYBPartyDrafts(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsListKYBPartyDraftsParams{})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().listKybPartyDrafts(\"33333333-4444-5555-6666-777777777777\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->listKybPartyDrafts('33333333-4444-5555-6666-777777777777');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.list_kyb_party_drafts(\"33333333-4444-5555-6666-777777777777\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ListKybPartyDraftsAsync(\"33333333-4444-5555-6666-777777777777\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "post": { "summary": "创建 KYB 相关方草稿", "description": "向您为此 KYB 会话准备的列表中添加一个参与方（个人或企业）。适用与托管关键人员界面相同的字段和规则：个人需要 `full_name` 或 `first_name` 和 `last_name`、至少一个角色以及国籍；企业需要 `company_name` 并在 `nationality` 中填写注册国家/地区。在调用 `POST /v3/session/{sessionId}/kyb/parties/submit/` 之前，不会申报任何内容，也不会进行计费。需要 `write:businesses` 权限。", "operationId": "post_v3_session_kyb_party_drafts", "x-didit-sdk": { "resource": "sessions", "method": "create_kyb_party_draft", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "企业验证（KYB）会话的 UUID。它必须属于 API 密钥所属的应用。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "KYB 步骤的工作流节点。仅在工作流具有多个 KYB 节点时需要；默认情况下，Didit 会使用会话自身的节点。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "该主体是个人还是公司。" }, "full_name": { "type": "string", "maxLength": 255, "description": "个人的姓名。发送此字段，或者发送 `first_name` 和 `last_name`。" }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "当事方持有的角色。可与 `roles` 互换；两者都发送时将被合并。" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "该主体拥有的每个角色。人员至少需要一个角色（在此处或在 `role` 中）。" }, "position": { "type": "string", "maxLength": 128, "description": "个人的职位头衔。" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "企业相关方的名称。当 `entity_type` 为 `company` 时必填。" }, "registration_number": { "type": "string", "maxLength": 100, "description": "企业关联方的注册号。" }, "email": { "type": "string", "format": "email", "description": "验证链接发送到的位置。当当事方必须完成验证时为必填项，这取决于工作流的角色设置和股权结构阈值。" }, "ownership_percent": { "type": "number", "nullable": true, "description": "该方拥有的公司股份比例。" }, "nationality": { "type": "string", "maxLength": 100, "description": "个人的国籍，或企业的注册国家/地区。每个当事方都必须提供此信息。" }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "工作流定义的附加字段。" }, "skip_verification": { "type": "boolean", "default": false, "description": "请求跳过此主体的验证。仅当主体的角色在工作流的“关键人员”设置中允许跳过时才有效。" } } }, "example": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 60, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } } }, "responses": { "201": { "description": "草稿已创建。", "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_id", "created_at", "updated_at", "party" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "party": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "该主体是个人还是公司。" }, "full_name": { "type": "string", "maxLength": 255, "description": "个人的姓名。发送此字段，或者发送 `first_name` 和 `last_name`。" }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "当事方持有的角色。可与 `roles` 互换；两者都发送时将被合并。" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "该主体拥有的每个角色。人员至少需要一个角色（在此处或在 `role` 中）。" }, "position": { "type": "string", "maxLength": 128, "description": "个人的职位头衔。" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "企业相关方的名称。当 `entity_type` 为 `company` 时必填。" }, "registration_number": { "type": "string", "maxLength": 100, "description": "企业关联方的注册号。" }, "email": { "type": "string", "format": "email", "description": "验证链接发送到的位置。当当事方必须完成验证时为必填项，这取决于工作流的角色设置和股权结构阈值。" }, "ownership_percent": { "type": "number", "nullable": true, "description": "该方拥有的公司股份比例。" }, "nationality": { "type": "string", "maxLength": 100, "description": "个人的国籍，或企业的注册国家/地区。每个当事方都必须提供此信息。" }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "工作流定义的附加字段。" }, "skip_verification": { "type": "boolean", "default": false, "description": "请求跳过此主体的验证。仅当主体的角色在工作流的“关键人员”设置中允许跳过时才有效。" } } } } }, "example": { "draft_id": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d", "created_at": "2026-10-31T10:00:00Z", "updated_at": "2026-10-31T10:00:00Z", "party": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 60, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } } } }, "400": { "description": "参与方字段无效或缺少必填字段。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "non_field_errors": [ "Person parties require at least one role." ] } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除、属于另一个应用或超出了限定作用域密钥的限制；无法通过 detail 区分具体情况。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "会话已完成（`kyb_session_not_writable`）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" }, "code": { "type": "string" } } }, "example": { "detail": "This verification session is no longer accepting changes.", "code": "kyb_session_not_writable" } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟 300 次写入（POST、PATCH、DELETE）请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 响应头显示了额度。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.create_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n entity_type=\"person\",\n first_name=\"Ana\",\n last_name=\"Lopez\",\n roles=[\"ubo\", \"director\"],\n date_of_birth=\"1984-06-12\",\n email=\"ana.lopez@example.com\",\n ownership_percent=60.0,\n nationality=\"MEX\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.createKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", {\n entity_type: \"person\",\n first_name: \"Ana\",\n last_name: \"Lopez\",\n roles: [\"ubo\", \"director\"],\n date_of_birth: \"1984-06-12\",\n email: \"ana.lopez@example.com\",\n ownership_percent: 60.0,\n nationality: \"MEX\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.CreateKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsCreateKYBPartyDraftParams{\n\tEntityType: \"person\",\n\tFirstName: didit.String(\"Ana\"),\n\tLastName: didit.String(\"Lopez\"),\n\tRoles: didit.Some([]didit.SessionsCreateKYBPartyDraftParamsRoles{\"ubo\", \"director\"}),\n\tDateOfBirth: didit.String(\"1984-06-12\"),\n\tEmail: didit.String(\"ana.lopez@example.com\"),\n\tOwnershipPercent: didit.Float(60.0),\n\tNationality: \"MEX\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import java.time.LocalDate;\nimport java.util.List;\nimport me.didit.Didit;\nimport me.didit.types.SessionsCreateKybPartyDraftParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().createKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", SessionsCreateKybPartyDraftParams.builder()\n .entityType(SessionsCreateKybPartyDraftParams.EntityType.of(\"person\"))\n .firstName(\"Ana\")\n .lastName(\"Lopez\")\n .roles(List.of(SessionsCreateKybPartyDraftParams.Roles.of(\"ubo\"), SessionsCreateKybPartyDraftParams.Roles.of(\"director\")))\n .dateOfBirth(LocalDate.parse(\"1984-06-12\"))\n .email(\"ana.lopez@example.com\")\n .ownershipPercent(60.0)\n .nationality(\"MEX\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->createKybPartyDraft('33333333-4444-5555-6666-777777777777', [\n 'entity_type' => 'person',\n 'first_name' => 'Ana',\n 'last_name' => 'Lopez',\n 'roles' => ['ubo', 'director'],\n 'date_of_birth' => '1984-06-12',\n 'email' => 'ana.lopez@example.com',\n 'ownership_percent' => 60.0,\n 'nationality' => 'MEX',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.create_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n entity_type: \"person\",\n first_name: \"Ana\",\n last_name: \"Lopez\",\n roles: [\"ubo\", \"director\"],\n date_of_birth: \"1984-06-12\",\n email: \"ana.lopez@example.com\",\n ownership_percent: 60.0,\n nationality: \"MEX\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.CreateKybPartyDraftAsync(\"33333333-4444-5555-6666-777777777777\", new SessionsCreateKybPartyDraftParams\n{\n EntityType = \"person\",\n FirstName = \"Ana\",\n LastName = \"Lopez\",\n Roles = new SessionsCreateKybPartyDraftParamsRoles[] { \"ubo\", \"director\" },\n DateOfBirth = \"1984-06-12\",\n Email = \"ana.lopez@example.com\",\n OwnershipPercent = 60.0,\n Nationality = \"MEX\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/kyb/parties/drafts/{draftId}/": { "patch": { "summary": "编辑 KYB 关联方草稿", "description": "更改某一当事方草稿的字段。编辑内容会合并到已存储的草稿中，且合并后的当事方会作为一个整体进行验证，因此导致当事方信息不完整的编辑将被拒绝。更改 `first_name` 或 `last_name` 会替换已存储的姓名。需要 `write:businesses` 权限。", "operationId": "patch_v3_session_kyb_party_draft", "x-didit-sdk": { "resource": "sessions", "method": "update_kyb_party_draft", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "企业验证（KYB）会话的 UUID。它必须属于 API 密钥所属的应用。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "draftId", "in": "path", "required": true, "description": "参与方草稿的 UUID（创建时返回的 `draft_id`）。", "schema": { "type": "string", "format": "uuid", "example": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d" } }, { "name": "node_id", "in": "query", "required": false, "description": "KYB 步骤的工作流节点。仅在工作流具有多个 KYB 节点时需要；默认情况下，Didit 会使用会话自身的节点。", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "description": "参与方字段的任意子集。编辑内容将合并到已存储的草稿中，合并后的参与方会作为整体进行验证，因此编辑前能够提交的草稿在编辑后依然可以提交。", "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "该主体是个人还是公司。" }, "full_name": { "type": "string", "maxLength": 255, "description": "个人的姓名。发送此字段，或者发送 `first_name` 和 `last_name`。" }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "当事方持有的角色。可与 `roles` 互换；两者都发送时将被合并。" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "该主体拥有的每个角色。人员至少需要一个角色（在此处或在 `role` 中）。" }, "position": { "type": "string", "maxLength": 128, "description": "个人的职位头衔。" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "企业相关方的名称。当 `entity_type` 为 `company` 时必填。" }, "registration_number": { "type": "string", "maxLength": 100, "description": "企业关联方的注册号。" }, "email": { "type": "string", "format": "email", "description": "验证链接发送到的位置。当当事方必须完成验证时为必填项，这取决于工作流的角色设置和股权结构阈值。" }, "ownership_percent": { "type": "number", "nullable": true, "description": "该方拥有的公司股份比例。" }, "nationality": { "type": "string", "maxLength": 100, "description": "个人的国籍，或企业的注册国家/地区。每个当事方都必须提供此信息。" }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "工作流定义的附加字段。" }, "skip_verification": { "type": "boolean", "default": false, "description": "请求跳过此主体的验证。仅当主体的角色在工作流的“关键人员”设置中允许跳过时才有效。" } } }, "example": { "ownership_percent": 55 } } } }, "responses": { "200": { "description": "草稿已更新。", "content": { "application/json": { "schema": { "type": "object", "required": [ "draft_id", "created_at", "updated_at", "party" ], "properties": { "draft_id": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "party": { "type": "object", "required": [ "entity_type", "nationality" ], "properties": { "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "该主体是个人还是公司。" }, "full_name": { "type": "string", "maxLength": 255, "description": "个人的姓名。发送此字段，或者发送 `first_name` 和 `last_name`。" }, "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "当事方持有的角色。可与 `roles` 互换；两者都发送时将被合并。" }, "roles": { "type": "array", "items": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "description": "该主体拥有的每个角色。人员至少需要一个角色（在此处或在 `role` 中）。" }, "position": { "type": "string", "maxLength": 128, "description": "个人的职位头衔。" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "company_name": { "type": "string", "maxLength": 255, "description": "企业相关方的名称。当 `entity_type` 为 `company` 时必填。" }, "registration_number": { "type": "string", "maxLength": 100, "description": "企业关联方的注册号。" }, "email": { "type": "string", "format": "email", "description": "验证链接发送到的位置。当当事方必须完成验证时为必填项，这取决于工作流的角色设置和股权结构阈值。" }, "ownership_percent": { "type": "number", "nullable": true, "description": "该方拥有的公司股份比例。" }, "nationality": { "type": "string", "maxLength": 100, "description": "个人的国籍，或企业的注册国家/地区。每个当事方都必须提供此信息。" }, "phone_number": { "type": "string", "maxLength": 32 }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "工作流定义的附加字段。" }, "skip_verification": { "type": "boolean", "default": false, "description": "请求跳过此主体的验证。仅当主体的角色在工作流的“关键人员”设置中允许跳过时才有效。" } } } } }, "example": { "draft_id": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d", "created_at": "2026-10-31T10:00:00Z", "updated_at": "2026-10-31T10:00:00Z", "party": { "entity_type": "person", "first_name": "Ana", "last_name": "Lopez", "roles": [ "ubo", "director" ], "ownership_percent": 55, "nationality": "MEX", "email": "ana.lopez@example.com", "date_of_birth": "1984-06-12" } } } } }, "400": { "description": "合并的当事方无效。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "non_field_errors": [ "Person parties require at least one role." ] } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话或草稿不存在，或者会话超出了密钥所属应用或限定作用域密钥的限制。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "会话已完成（`kyb_session_not_writable`）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" }, "code": { "type": "string" } } }, "example": { "detail": "This verification session is no longer accepting changes.", "code": "kyb_session_not_writable" } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟 300 次写入（POST、PATCH、DELETE）请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 响应头显示了额度。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.update_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n ownership_percent=55.0,\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.updateKybPartyDraft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n {\n ownership_percent: 55.0,\n },\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.UpdateKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", didit.SessionsUpdateKYBPartyDraftParams{\n\tOwnershipPercent: didit.Float(55.0),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsUpdateKybPartyDraftParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().updateKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", SessionsUpdateKybPartyDraftParams.builder()\n .ownershipPercent(55.0)\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->updateKybPartyDraft('33333333-4444-5555-6666-777777777777', '5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d', [\n 'ownership_percent' => 55.0,\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.update_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n ownership_percent: 55.0\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.UpdateKybPartyDraftAsync(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", new SessionsUpdateKybPartyDraftParams\n{\n OwnershipPercent = 55.0,\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] }, "delete": { "summary": "删除 KYB 相关方草稿", "description": "删除一个相关方草稿。已申报的相关方不受影响。需要 `write:businesses`。", "operationId": "delete_v3_session_kyb_party_draft", "x-didit-sdk": { "resource": "sessions", "method": "delete_kyb_party_draft", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "企业验证（KYB）会话的 UUID。它必须属于 API 密钥所属的应用。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "draftId", "in": "path", "required": true, "description": "参与方草稿的 UUID（创建时返回的 `draft_id`）。", "schema": { "type": "string", "format": "uuid", "example": "5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d" } }, { "name": "node_id", "in": "query", "required": false, "description": "KYB 步骤的工作流节点。仅在工作流具有多个 KYB 节点时需要；默认情况下，Didit 会使用会话自身的节点。", "schema": { "type": "string" } } ], "responses": { "204": { "description": "草稿已删除。无响应体。" }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话或草稿不存在，或者会话超出了密钥所属应用或限定作用域密钥的限制。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "会话已完成（`kyb_session_not_writable`）。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" }, "code": { "type": "string" } } }, "example": { "detail": "This verification session is no longer accepting changes.", "code": "kyb_session_not_writable" } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟 300 次写入（POST、PATCH、DELETE）请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 响应头显示了额度。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nclient.sessions.delete_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nawait didit.sessions.deleteKybPartyDraft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\",\n);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nif err := client.Sessions.DeleteKYBPartyDraft(ctx, \"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\", didit.SessionsDeleteKYBPartyDraftParams{}); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nclient.sessions().deleteKybPartyDraft(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\");" }, { "lang": "php", "label": "PHP", "source": "sessions->deleteKybPartyDraft('33333333-4444-5555-6666-777777777777', '5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d');" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.sessions.delete_kyb_party_draft(\n \"33333333-4444-5555-6666-777777777777\",\n \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\"\n)" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait client.Sessions.DeleteKybPartyDraftAsync(\"33333333-4444-5555-6666-777777777777\", \"5b0d7a52-9d3e-4f0c-8c6a-0e5f3a1b2c4d\");" } ] } }, "/v3/session/{sessionId}/kyb/parties/submit/": { "post": { "summary": "提交 KYB 相关方草稿", "description": "将已保存的草稿申报为公司的关键人员。这是在您 API 密钥下的托管关键人员步骤：Didit 会根据工作流的角色设置和股权结构阈值判定必须验证哪些当事方，为他们每个人创建一个个人 KYC 会话（若为企业所有者则创建 KYB 子会话），发送工作流要求的邮件，并推进该会话。每个子会话的计费方式与托管流程中相同。草稿在调用后即被消耗。提交成功后重复调用不会产生任何变更，并将返回 `200` 以及 `already_submitted: true` 和已存在的当事方。会话必须处于关键人员步骤。将每个人的 `kyc_session_url` 发送给他们，或将其嵌入。需要 `write:businesses` 权限。", "operationId": "post_v3_session_kyb_parties_submit", "x-didit-sdk": { "resource": "sessions", "method": "submit_kyb_parties", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "企业验证（KYB）会话的 UUID。它必须属于 API 密钥所属的应用。", "schema": { "type": "string", "format": "uuid", "example": "33333333-4444-5555-6666-777777777777" } }, { "name": "node_id", "in": "query", "required": false, "description": "KYB 步骤的工作流节点。仅在工作流具有多个 KYB 节点时需要；默认情况下，Didit 会使用会话自身的节点。", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "maxLength": 10, "description": "用于翻译会话推进至的步骤响应的区域设置。" } } }, "example": { "locale": "es" } } } }, "responses": { "200": { "description": "已声明（或此前已声明）的当事方。", "content": { "application/json": { "schema": { "type": "object", "properties": { "valid": { "type": "boolean" }, "next_step": { "type": "string", "nullable": true, "description": "会话当前所处的步骤。" }, "status": { "type": "string", "description": "企业会话的状态。" }, "advanced": { "type": "boolean", "description": "当此调用声明了相关方并推进了会话时为 `true`。" }, "already_submitted": { "type": "boolean", "description": "当相关方已在先前的调用中声明时为 `true`。" }, "kyb_key_people_status": { "type": "string" }, "parties": { "type": "array", "items": { "$ref": "#/components/schemas/KYBKeyPeopleParty" } } } }, "example": { "valid": true, "next_step": "FINISHED", "status": "In Progress", "advanced": true, "already_submitted": false, "kyb_key_people_status": "In Progress", "parties": [] } } } }, "402": { "description": "该组织已无可用额度用于子验证会话。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "detail": "Insufficient credits." } } } }, "401": { "description": "作用域 API 密钥已过期。这是唯一返回 `401` 的情况：缺失、无效或已吊销的密钥将返回 `403`。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Expired key": { "summary": "密钥的到期日期已过", "value": { "detail": "This API key has expired." } } } } } }, "403": { "description": "身份验证或授权失败。缺少密钥，以及属于其他应用的密钥、缺少该 endpoint 所需权限的限定作用域密钥和来自该密钥 IP 允许名单之外的请求均返回 `403`；错误、已撤销或已过期的密钥返回 `401`。可通过 `detail` 区分它们。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Missing or invalid credentials": { "summary": "缺少 x-api-key 请求头，或该密钥验证失败", "value": { "detail": "Authentication credentials were not provided or are invalid." } }, "Other application": { "summary": "属于与该会话不同应用的有效密钥", "value": { "detail": "You do not have permission to perform this action." } }, "Scoped key without decisions write": { "summary": "作用域密钥缺少 decisions: write 权限", "value": { "detail": "This API key has no write access to decisions." } }, "IP not allowed": { "summary": "来自密钥 IP 白名单之外的请求", "value": { "detail": "This API key can't be used from this IP address." } } } } } }, "404": { "description": "会话不存在、已被删除、属于另一个应用或超出了限定作用域密钥的限制；无法通过 detail 区分具体情况。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "example": { "detail": "Session not found." } } } }, "409": { "description": "`kyb_no_party_drafts`：没有可提交的内容。`kyb_parties_already_submitted`：在声明相关方后添加了草稿。`kyb_step_mismatch`：会话当前不处于关键人员步骤（`next_step` 指明其所在步骤）。`kyb_session_not_writable`：会话已结束。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" }, "code": { "type": "string" }, "next_step": { "type": "string" } } }, "example": { "detail": "There are no draft parties to submit.", "code": "kyb_no_party_drafts" } } } }, "429": { "description": "超出速率限制：每个 API 密钥每分钟 300 次写入（POST、PATCH、DELETE）请求。请等待 `Retry-After` 秒后再重试；`X-RateLimit-*` 响应头显示了额度。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的错误消息。" } } }, "examples": { "Rate limited": { "summary": "当前分钟的预算已耗尽", "value": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } } }, "headers": { "Retry-After": { "description": "重试前需要等待的秒数。", "schema": { "type": "integer", "minimum": 1, "example": 30 } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.submit_kyb_parties(\n \"33333333-4444-5555-6666-777777777777\",\n locale=\"es\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.submitKybParties(\"33333333-4444-5555-6666-777777777777\", {\n locale: \"es\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.SubmitKYBParties(ctx, \"33333333-4444-5555-6666-777777777777\", didit.SessionsSubmitKYBPartiesParams{\n\tLocale: didit.String(\"es\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.SessionsSubmitKybPartiesParams;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().submitKybParties(\"33333333-4444-5555-6666-777777777777\", SessionsSubmitKybPartiesParams.builder()\n .locale(\"es\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->submitKybParties('33333333-4444-5555-6666-777777777777', [\n 'locale' => 'es',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.submit_kyb_parties(\n \"33333333-4444-5555-6666-777777777777\",\n locale: \"es\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.SubmitKybPartiesAsync(\"33333333-4444-5555-6666-777777777777\", new SessionsSubmitKybPartiesParams\n{\n Locale = \"es\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } }, "/v3/session/{sessionId}/files-export/": { "post": { "summary": "导出某个会话的全部文件", "description": "开始准备一个包含用户验证（KYC）或企业验证（KYB）会话的所有图像、视频和证件的原始质量 ZIP 文件：文件按捕获时的原始状态存储在 ZIP 中，绝不二次压缩。响应 `202` 并返回导出信息；通过 `GET /v3/session/{sessionId}/files-export/{exportId}/` 轮询读取，直到 `status` 为 `READY`，然后下载 `download_url`。如果同一会话的导出仍在准备中，则返回该导出而不是创建新导出。\n\nZIP 文件在准备就绪 24 小时后删除，并在会话被删除时立即删除。已删除的会话无法导出。每次导出以及分发的每个下载链接都会记录到会话的审计日志中。具备作用域限制的 API 密钥需要 `media: read` 和 `decisions: read` 权限；控制台用户需要读取会话的权限。", "operationId": "post_v3_session_files_export", "x-didit-sdk": { "resource": "sessions", "method": "export_files", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "验证会话的 UUID（由 `POST /v3/session/` 返回的 `session_id`）。支持用户验证（KYC）和企业验证（KYB）会话 ID。已删除的会话返回 `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X POST 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/files-export/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.export_files(\n \"11111111-2222-3333-4444-555555555555\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.exportFiles(\"11111111-2222-3333-4444-555555555555\");\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.ExportFiles(ctx, \"11111111-2222-3333-4444-555555555555\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().exportFiles(\"11111111-2222-3333-4444-555555555555\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->exportFiles('11111111-2222-3333-4444-555555555555');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.export_files(\"11111111-2222-3333-4444-555555555555\")\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.ExportFilesAsync(\"11111111-2222-3333-4444-555555555555\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "202": { "description": "正在准备中的导出。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFilesExport" }, "example": { "export_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "session_id": "11111111-2222-3333-4444-555555555555", "status": "PENDING", "file_count": null, "size_bytes": null, "download_url": null, "expires_at": null, "error": null, "created_at": "2026-10-29T12:00:03Z", "completed_at": null } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/session/{sessionId}/files-export/{exportId}/": { "get": { "summary": "获取会话文件导出", "description": "通过 `POST /v3/session/{sessionId}/files-export/` 发起的导出进度。一旦 `status` 变为 `READY`，`download_url` 即为 ZIP 的签名 URL，在短时间内有效；若需获取新链接，请在 `expires_at` 之前再次读取该导出。每次分发下载链接的读取操作都会记录到该会话的审计日志中。对已删除会话的导出操作将返回 `404`。", "operationId": "get_v3_session_files_export", "x-didit-sdk": { "resource": "sessions", "method": "get_files_export", "auth": "api_key", "server": true }, "tags": [ "Sessions" ], "parameters": [ { "name": "sessionId", "in": "path", "required": true, "description": "验证会话的 UUID（由 `POST /v3/session/` 返回的 `session_id`）。支持用户验证（KYC）和企业验证（KYB）会话 ID。已删除的会话返回 `404`。", "schema": { "type": "string", "format": "uuid", "example": "11111111-2222-3333-4444-555555555555" } }, { "name": "exportId", "in": "path", "required": true, "description": "`POST /v3/session/{sessionId}/files-export/` 返回的 `export_id`。", "schema": { "type": "string", "format": "uuid", "example": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee" } } ], "x-codeSamples": [ { "lang": "curl", "label": "curl", "source": "curl -X GET 'https://verification.didit.me/v3/session/11111111-2222-3333-4444-555555555555/files-export/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/' \\\n -H 'x-api-key: YOUR_API_KEY'" }, { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.sessions.get_files_export(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.sessions.getFilesExport(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\",\n);\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.GetFilesExport(ctx, \"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\")\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.sessions().getFilesExport(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "sessions->getFilesExport('11111111-2222-3333-4444-555555555555', 'aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee');\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.sessions.get_files_export(\n \"11111111-2222-3333-4444-555555555555\",\n \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.Sessions.GetFilesExportAsync(\"11111111-2222-3333-4444-555555555555\", \"aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee\");\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ], "responses": { "200": { "description": "导出。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionFilesExport" }, "example": { "export_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee", "session_id": "11111111-2222-3333-4444-555555555555", "status": "READY", "file_count": 9, "size_bytes": 18734120, "download_url": "https://storage.example.com/session/11111111-2222-3333-4444-555555555555/files-export/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/session-42-files.zip?X-Amz-Signature=...", "expires_at": "2026-10-30T12:00:41Z", "error": null, "created_at": "2026-10-29T12:00:03Z", "completed_at": "2026-10-29T12:00:41Z" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [ { "ApiKeyAuth": [] } ] } }, "/v3/travel-rule/unmatched/": { "get": { "summary": "列出未匹配的 Travel Rule 充值", "description": "仍在等待汇款方 VASP 的 Travel Rule 数据的入站充值：其转账状态为 `AWAITING_COUNTERPARTY`、`NOT_ENOUGH_COUNTERPARTY_DATA` 或 `COUNTERPARTY_VASP_NOT_FOUND`，未配对任何已接收的消息，且无人手动进行匹配。数据行和过滤器与 `GET /v3/travel-rule/transfers/` 相同，按最新优先排序，使用 `limit`（默认 50）和 `offset` 进行分页。使用 `POST /v3/travel-rule/unmatched/{transaction_uuid}/match/` 将充值与汇款方 VASP 发送的消息配对。", "operationId": "listUnmatchedTravelRuleDeposits", "x-didit-sdk": { "resource": "travel_rule.unmatched_deposits", "method": "list", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "parameters": [ { "name": "direction", "in": "query", "required": false, "schema": { "type": "string" }, "description": "INBOUND、OUTBOUND 或两者以逗号分隔。区分大小写。" }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "一个或多个转账状态，以逗号分隔。" }, { "name": "rail", "in": "query", "required": false, "schema": { "type": "string" }, "description": "INTERNAL、TRP、GTR、TRUST、VERIFYVASP、SYGNA、EMAIL、TEST_VASP 中的一个或多个，以逗号分隔。" }, { "name": "kind", "in": "query", "required": false, "schema": { "type": "string" }, "description": "withdrawal、deposit 或 message，以逗号分隔。" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "交易的币种，不区分大小写。" }, { "name": "start_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "在此日期（UTC）或之后创建的转账，格式为 YYYY-MM-DD。" }, { "name": "end_date", "in": "query", "required": false, "schema": { "type": "string", "format": "date" }, "description": "在此日期（UTC）或之前创建的转账，格式为 YYYY-MM-DD。" }, { "name": "counterparty", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "来自 GET /v3/travel-rule/vasps/ 的名录条目或 Didit 网络成员的 `id`：用于获取您与该交易对手之间的转账。无效的 id 值将返回 400。" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "description": "页面大小，默认为 50。" }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 }, "description": "要跳过的行。" } ], "responses": { "200": { "description": "一页未匹配充值。", "content": { "application/json": { "schema": { "type": "object", "properties": { "count": { "type": "integer" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleTransferRow" } } } }, "example": { "count": 1, "next": null, "previous": null, "results": [ { "id": "7d3a1c55-0b9e-4d52-8a3c-1f6e2b9d4a08", "transaction_id": "c41f9b2e-5a8d-4e0c-9f17-3b6d8a2e5c91", "txn_id": "dep-2026-10-20-0007", "txn_date": "2026-10-19T08:41:12Z", "kind": "deposit", "direction": "INBOUND", "status": "AWAITING_COUNTERPARTY", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": null, "deadline_at": null, "created_at": "2026-10-19T08:41:13Z" } ] } } } }, "400": { "description": "过滤器值无效。", "content": { "application/json": { "example": { "start_date": [ "Use the YYYY-MM-DD format." ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nfor item in client.travel_rule.unmatched_deposits.list():\n print(item)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nfor await (const item of didit.travelRule.unmatchedDeposits.list()) {\n console.log(item);\n}" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\niter := client.TravelRule.UnmatchedDeposits.ListAutoPaging(ctx, didit.TravelRuleUnmatchedDepositsListParams{})\nfor iter.Next() {\n\tfmt.Printf(\"%+v\\n\", iter.Current())\n}\nif err := iter.Err(); err != nil {\n\tlog.Fatal(err)\n}" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nfor (var item : client.travelRule().unmatchedDeposits().list()) {\n System.out.println(item);\n}" }, { "lang": "php", "label": "PHP", "source": "travelRule->unmatchedDeposits->list() as $item) {\n print_r($item->toArray());\n}" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\ndidit.travel_rule.unmatched_deposits.list.auto_paging_each do |item|\n puts item.to_h\nend" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nawait foreach (var item in await client.TravelRule.UnmatchedDeposits.ListAsync())\n{\n Console.WriteLine(JsonSerializer.Serialize(item));\n}" } ] } }, "/v3/travel-rule/unmatched/{transaction_uuid}/match/": { "post": { "summary": "将 Travel Rule 充值与接收到的消息进行匹配", "operationId": "matchUnmatchedTravelRuleDeposit", "x-didit-sdk": { "resource": "travel_rule.unmatched_deposits", "method": "match", "auth": "api_key", "server": true }, "tags": [ "Travel Rule" ], "security": [ { "ApiKeyAuth": [] } ], "description": "将仍等待汇款人数据的入账充值与汇款方 VASP 为其发送的 Travel Rule 消息进行配对。该充值将采用该消息的汇款人数据、交易对手 VASP 和通道，且两笔转账均会在其时间线上记录该匹配。`transaction_uuid` 是来自 `GET /v3/travel-rule/unmatched/` 的充值 `transaction_id`。请求体中的 `transaction_id` 是接收到消息的 `transaction_id`，来自 `GET /v3/travel-rule/transfers/?kind=message` 的某一行；该转账自身的 `id` 未找到。该消息必须与充值针对相同的资产。从 Console 中删除的充值或消息将返回 `404`；已继续推进（已匹配或不再等待）的充值或消息将返回 `409`。", "parameters": [ { "name": "transaction_uuid", "in": "path", "required": true, "description": "未匹配充值的 `transaction_id`。", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleManualMatchRequest" }, "example": { "transaction_id": "e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24" } } } }, "responses": { "200": { "description": "匹配后的两笔转账。", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleManualMatchResponse" }, "example": { "deposit": { "id": "7d3a1c55-0b9e-4d52-8a3c-1f6e2b9d4a08", "transaction_id": "c41f9b2e-5a8d-4e0c-9f17-3b6d8a2e5c91", "txn_id": "dep-2026-10-20-0007", "txn_date": "2026-10-19T08:41:12Z", "kind": "deposit", "direction": "INBOUND", "status": "AWAITING_COUNTERPARTY", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "Example Counterparty VASP", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": "e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24", "deadline_at": null, "created_at": "2026-10-19T08:41:13Z" }, "message": { "id": "2b8e6f10-9c3a-47d1-b5e2-0a4c7d9f3e66", "transaction_id": "e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24", "txn_id": "msg-2026-10-20-0003", "txn_date": "2026-10-19T08:41:12Z", "kind": "message", "direction": "INBOUND", "status": "COMPLETED", "rail": "TRP", "asset": "ETH", "amount": "1.25", "originator_vasp": "Origin CASP SL", "beneficiary_vasp": "Example Counterparty VASP", "originator_wallet": "0x77ccff0cc624a53cd8b8d8703ced826710211ec7", "beneficiary_wallet": "0xede2d7e4f5b097e6391ab6bbcf2f47a53f4778cb", "originator_memo": "", "beneficiary_memo": "", "originator_wallet_type": "vasp", "beneficiary_wallet_type": "vasp", "matched_transaction_id": null, "deadline_at": "2026-10-21T08:41:13Z", "created_at": "2026-10-19T08:41:13Z" } } } } }, "400": { "description": "验证错误：`transaction_id` 缺失、为充值交易本身、不是已接收的 Travel Rule 消息，或者对应的资产与充值资产不同；或者路径中的交易不是入站充值。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Error": { "value": { "transaction_id": [ "The travel rule message is for a different asset than the deposit." ] } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "description": "未知的存款或消息，或者其中之一已被删除。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "example": { "detail": "No TravelRuleTransfer matches the given query." } } } }, "409": { "description": "充值不再等待汇款人数据，或者消息已与充值匹配。", "content": { "application/json": { "schema": { "type": "object", "properties": { "detail": { "type": "string" } } }, "examples": { "Error": { "value": { "detail": "This deposit is no longer waiting for originator data." } } } } } } }, "x-codeSamples": [ { "lang": "python", "label": "Python", "source": "from didit import Didit\n\n# Reads DIDIT_API_KEY.\nclient = Didit()\n\nresult = client.travel_rule.unmatched_deposits.match(\n \"11111111-2222-3333-4444-555555555555\",\n transaction_id=\"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n)\nprint(result)" }, { "lang": "javascript", "label": "Node.js", "source": "import Didit from \"@didit-protocol/sdk-node\";\n\n// Reads DIDIT_API_KEY.\nconst didit = new Didit();\n\nconst result = await didit.travelRule.unmatchedDeposits.match(\"11111111-2222-3333-4444-555555555555\", {\n transaction_id: \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n});\nconsole.log(result);" }, { "lang": "go", "label": "Go", "source": "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.TravelRule.UnmatchedDeposits.Match(ctx, \"11111111-2222-3333-4444-555555555555\", didit.TravelRuleManualMatchRequest{\n\tTransactionID: \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" }, { "lang": "java", "label": "Java", "source": "import me.didit.Didit;\nimport me.didit.types.TravelRuleManualMatchRequest;\n\n// Reads DIDIT_API_KEY.\nDidit client = new Didit();\n\nvar result = client.travelRule().unmatchedDeposits().match(\"11111111-2222-3333-4444-555555555555\", TravelRuleManualMatchRequest.builder()\n .transactionId(\"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\")\n .build());\nSystem.out.println(result);" }, { "lang": "php", "label": "PHP", "source": "travelRule->unmatchedDeposits->match('11111111-2222-3333-4444-555555555555', [\n 'transaction_id' => 'e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24',\n]);\nprint_r($result->toArray());" }, { "lang": "ruby", "label": "Ruby", "source": "require \"didit\"\n\n# Reads DIDIT_API_KEY.\ndidit = Didit::Client.new\n\nresult = didit.travel_rule.unmatched_deposits.match(\n \"11111111-2222-3333-4444-555555555555\",\n transaction_id: \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\"\n)\nputs result.to_h" }, { "lang": "csharp", "label": ".NET", "source": "using System;\nusing System.Text.Json;\nusing Didit;\n\n// Reads DIDIT_API_KEY.\nusing var client = new DiditClient();\n\nvar result = await client.TravelRule.UnmatchedDeposits.MatchAsync(\"11111111-2222-3333-4444-555555555555\", new TravelRuleManualMatchRequest\n{\n TransactionId = \"e90a4d7b-1c2f-4b83-a6d5-8f0e3c1b7a24\",\n});\nConsole.WriteLine(JsonSerializer.Serialize(result));" } ] } } }, "components": { "schemas": { "DocumentAIDetectedCode": { "type": "object", "required": [ "type", "page_number", "position", "x", "y", "width", "height", "page_width", "page_height", "raw_payload", "parsed_payload" ], "properties": { "type": { "type": "string", "description": "检测到的符号系统，例如 `QR_CODE`、`CODE_128`、`EAN_13`、`DATA_MATRIX` 或 `PDF_417`。" }, "page_number": { "type": "integer", "minimum": 1, "description": "从 1 开始的页码。" }, "position": { "type": "array", "nullable": true, "description": "在渲染页面的像素坐标中检测到的多边形。当没有可靠的位置可用时为 `null`。", "items": { "type": "array", "minItems": 2, "maxItems": 2, "items": { "type": "integer" } } }, "x": { "type": "integer", "nullable": true, "description": "边界框的左边缘（以渲染页面的像素为单位）。" }, "y": { "type": "integer", "nullable": true, "description": "边界框的顶部边缘（以渲染页面像素为单位）。" }, "width": { "type": "integer", "nullable": true, "description": "渲染页面像素中的边界框宽度。" }, "height": { "type": "integer", "nullable": true, "description": "渲染页面像素中的边界框高度。" }, "page_width": { "type": "integer", "description": "渲染页面的宽度（以像素为单位）。" }, "page_height": { "type": "integer", "description": "渲染页面的高度（以像素为单位）。" }, "raw_payload": { "type": "string", "description": "原始解码器 payload（base64 字符串形式，如可用）；否则为空字符串。" }, "parsed_payload": { "nullable": true, "description": "解码后的字符串或结构化值。当定位到代码但无法解码时为 `null`。" } } }, "SessionImportJob": { "type": "object", "required": [ "uuid", "status", "import_type", "source_format", "source_filename", "total_rows", "processed_rows", "created_count", "updated_count", "skipped_count", "failed_count" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "导入任务 ID。使用此值轮询进度并获取行级错误。" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED", "PAUSED", "CANCELLED", "READY" ] }, "import_type": { "type": "string", "enum": [ "user_verification", "business_verification", "status_rules", "transactions" ] }, "source_format": { "type": "string", "enum": [ "csv", "ndjson" ] }, "source_filename": { "type": "string" }, "total_rows": { "type": "integer", "format": "int64" }, "processed_rows": { "type": "integer", "format": "int64" }, "checkpoint_row": { "type": "integer", "format": "int64" }, "created_count": { "type": "integer", "format": "int64" }, "updated_count": { "type": "integer", "format": "int64" }, "skipped_count": { "type": "integer", "format": "int64" }, "failed_count": { "type": "integer", "format": "int64" }, "total_media_bytes": { "type": "integer", "format": "int64" }, "last_error": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "state": { "type": "string", "enum": [ "ready", "queued", "running", "paused", "completed", "errors", "failed", "cancelled" ], "description": "控制台显示的任务状态；`errors` 表示任务已完成但存在被拒绝的行。" }, "source": { "type": "string", "enum": [ "file", "api", "provider" ] }, "provider": { "type": "string", "description": "迁移来源；对于文件或 API 导入则为空。" }, "provider_options": { "type": "object" }, "credential_hint": { "type": "string", "description": "迁移所保存密钥的前几个字符。密钥本身永远不会返回。" }, "credentials_expires_at": { "type": "string", "format": "date-time", "nullable": true }, "resumes_at": { "type": "string", "format": "date-time", "nullable": true, "description": "因提供商速率限制而暂停的任务自行恢复的时间。" }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string" } }, "is_dry_run": { "type": "boolean" }, "dry_run_summary": { "type": "object", "description": "试运行发现的内容：`total`、`by_status`、`already_in_didit`、`same_person`、`not_finished`、`failed`、`unmapped_statuses`。" }, "face_templates_enabled": { "type": "boolean" }, "lawful_basis_confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "not_finished_count": { "type": "integer", "format": "int64" }, "same_person_count": { "type": "integer", "format": "int64" }, "face_templates_count": { "type": "integer", "format": "int64" }, "face_duplicates_count": { "type": "integer", "format": "int64" }, "face_blocklist_hits_count": { "type": "integer", "format": "int64" }, "created_by_name": { "type": "string", "nullable": true }, "created_by_email": { "type": "string", "nullable": true } } }, "SessionImportError": { "type": "object", "required": [ "uuid", "row_number", "error", "raw_row" ], "properties": { "uuid": { "type": "string", "format": "uuid" }, "row_number": { "type": "integer", "format": "int64" }, "external_id": { "type": "string", "nullable": true }, "error": { "type": "string" }, "raw_row": { "type": "object", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" } } }, "BrandingCustomizationUpdate": { "type": "object", "description": "品牌化部分更新请求体。仅提供您想要更改的字段。十六进制颜色支持 `#RRGGBB` 或 `#RRGGBBAA`。此处不接受自定义域名和白标邮箱。", "properties": { "color_primary": { "type": "string", "description": "标题/主要文本颜色。" }, "color_secondary": { "type": "string", "description": "段落 / 次要文本颜色。" }, "color_background": { "type": "string", "description": "页面背景颜色。" }, "color_panel": { "type": "string", "description": "面板 / 强调色。" }, "color_panel_10": { "type": "string", "description": "10% 不透明度的面板颜色。" }, "color_on_panel_1": { "type": "string", "description": "面板上的辅助文本颜色。" }, "color_on_panel_2": { "type": "string", "description": "面板上的标签/徽章颜色。" }, "color_on_background": { "type": "string", "description": "背景上的文本颜色。" }, "color_button_1": { "type": "string", "description": "主要按钮颜色。" }, "color_button_2": { "type": "string", "description": "次要按钮颜色。" }, "color_button_text_1": { "type": "string", "description": "主要按钮文本颜色。" }, "color_button_text_2": { "type": "string", "description": "次要按钮文本颜色。" }, "color_pill_text": { "type": "string", "description": "胶囊控件、输入框和选择器的文本颜色。" }, "border_radius_panel": { "type": "integer", "minimum": 0, "description": "面板圆角半径（像素）。" }, "border_radius_buttons": { "type": "integer", "minimum": 0, "description": "按钮圆角半径（以像素为单位）。" }, "font_family": { "type": "string", "description": "Google Font 字体系列名称（例如 `Inter`、`AR One Sans`）。" }, "font_weight": { "type": "string", "description": "所选字体族可用的字重（例如 `regular`、`500`、`700`）。" }, "app_public_name": { "type": "string", "nullable": true, "description": "验证流程中显示的公开名称。" }, "privacy_policy_url": { "type": "string", "nullable": true, "description": "向终端用户显示的隐私政策 URL。" }, "skip_welcome_screen": { "type": "boolean", "description": "跳过初始欢迎屏幕。" }, "disable_login_with_didit": { "type": "boolean", "description": "以访客身份继续，而非显示 Didit 登录界面。配置了自定义域名时无法设置回 `false`（400）。" }, "hide_progress_bar": { "type": "boolean", "description": "在流程中隐藏进度条。" }, "callback_seconds": { "type": "integer", "minimum": 0, "description": "重定向到回调 URL 前的延迟时间（秒）。" }, "delete_logo_square": { "type": "boolean", "description": "为 `true` 时，移除当前正方形 logo。" }, "delete_logo_rectangular": { "type": "boolean", "description": "为 `true` 时，移除当前长方形 logo。" }, "delete_logo_rectangular_dark": { "type": "boolean", "description": "为 `true` 时，移除当前的深色模式 logo，随后 `logo_rectangular_dark` 读取为 `null`。如果同一 multipart 请求中还上传了 `image_rectangular_dark`，则以上传内容为准。" }, "delete_favicon": { "type": "boolean", "description": "为 `true` 时，移除当前 favicon。" } } }, "BrandingCustomization": { "type": "object", "description": "应用的白标品牌化：颜色、字体、圆角半径、徽标 URL 和 UI/UX 选项。徽标 URL 为只读（通过上传图片进行设置）。不包含自定义域名和白标邮件。", "properties": { "color_primary": { "type": "string" }, "color_secondary": { "type": "string" }, "color_background": { "type": "string" }, "color_panel": { "type": "string" }, "color_panel_10": { "type": "string" }, "color_on_panel_1": { "type": "string" }, "color_on_panel_2": { "type": "string" }, "color_on_background": { "type": "string" }, "color_button_1": { "type": "string" }, "color_button_2": { "type": "string" }, "color_button_text_1": { "type": "string" }, "color_button_text_2": { "type": "string" }, "color_pill_text": { "type": "string" }, "border_radius_panel": { "type": "integer" }, "border_radius_buttons": { "type": "integer" }, "font_family": { "type": "string" }, "font_weight": { "type": "string" }, "font_url": { "type": "string", "nullable": true, "description": "只读。所选字体系列解析后的 Google Fonts 样式表 URL。" }, "logo_square": { "type": "string", "nullable": true, "description": "方形徽标的只读 URL。通过 `image_square` 上传。" }, "logo_rectangular": { "type": "string", "nullable": true, "description": "矩形徽标的只读 URL。通过 `image_rectangular` 上传。" }, "logo_rectangular_dark": { "type": "string", "format": "uri", "nullable": true, "description": "只读。暗色模式矩形徽标的临时签名 URL，显示在深色背景上。当未设置暗色徽标或您的账户不显示矩形徽标时为 `null`。通过 `image_rectangular_dark` 上传。" }, "favicon": { "type": "string", "nullable": true, "description": "网站图标的只读 URL。通过 `image_favicon` 上传。" }, "app_public_name": { "type": "string", "nullable": true }, "privacy_policy_url": { "type": "string", "nullable": true }, "skip_welcome_screen": { "type": "boolean" }, "disable_login_with_didit": { "type": "boolean" }, "hide_progress_bar": { "type": "boolean" }, "callback_seconds": { "type": "integer" } } }, "WebhookEvent": { "type": "string", "description": "支持的 Webhook 事件名称。请在 `subscribed_events` 中使用这些完全匹配的字符串；不支持的值将被拒绝。", "enum": [ "status.updated", "data.updated", "user.status.updated", "user.data.updated", "business.status.updated", "business.data.updated", "activity.created", "transaction.created", "transaction.status.updated", "travel_rule.status.updated", "workflow.compliance_changed", "transaction_rule_suggestions.created", "auth.signup", "auth.login", "auth.login_failed", "auth.password_reset_requested", "auth.password_reset_completed", "auth.mfa_changed", "auth.new_device", "auth.account_locked", "investigator.report.ready", "investigator.decision.automated", "investigator.decision.overridden", "investigator.decision.contested", "investigator.question.raised", "investigator.automation.paused", "investigator.rfi.answered", "investigator.rfi.overdue", "investigator.drift.detected", "investigator.sla.breached", "investigator.qa.failed", "investigator.external.report.ready" ] }, "WebhookSubscribedEvents": { "type": "array", "description": "此 Webhook 目标的事件过滤器。Didit 仅投递事件类型与这些值之一完全匹配的 Webhook，不支持通配符订阅。发送时，列表必须包含至少一个有效事件（显式传入 `[]` 将被拒绝并返回 400）；列表为空的目标（创建时省略该字段）不会接收任何内容。更新时，列表会被整体替换，绝不会进行合并。", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/components/schemas/WebhookEvent" }, "example": [ "status.updated", "data.updated" ] }, "PhoneVerificationSendResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "验证的会话 id。`Retry` 发送会返回与原始发送相同的 `request_id`。此 id 会显示在 Business Console 中，在已完成的 `POST /v3/phone/check/` 中再次返回，并可传递给 `GET /v3/session/{sessionId}/decision/`。" }, "status": { "type": "string", "enum": [ "Success", "Retry", "Blocked" ], "description": "`Success`：OTP 已发送至新的验证。`Retry`：为先前发送所创建的待处理验证重新发送了 OTP。`Blocked`：防欺诈层拒绝发送；验证立即以 `Declined` 终结，且不产生计费。" }, "reason": { "type": "string", "nullable": true, "description": "发送被 `Blocked` 的原因（例如 `repeated_attempts`、`suspicious`、`spam`）。在 `Success` 和 `Retry` 时为 `null`。" }, "vendor_data": { "type": "string", "nullable": true, "description": "存储在会话中的 `vendor_data` 回显（来自首次发送）。" }, "metadata": { "type": "object", "nullable": true, "description": "存储在会话中的 `metadata` 回显（来自首次发送）。" } } }, "PhoneVerificationCheckResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "状态为 `Approved`/`Declined` 时：匹配验证的会话 ID，与 `POST /v3/phone/send/` 返回的 `request_id` 相同。状态为 `Failed` 和 `Expired or Not Found` 时：一个随机的一次性 UUID，后续无法查询。" }, "status": { "type": "string", "enum": [ "Approved", "Declined", "Failed", "Expired or Not Found" ], "description": "`Approved` — 验证码正确，无拒绝风险。`Declined` — 最终状态：匹配到拒绝风险或尝试次数上限（3）已用尽。`Failed` — 验证码错误，仍有剩余尝试次数。`Expired or Not Found` — 过去 5 分钟内该号码没有待处理的验证。" }, "message": { "type": "string", "description": "结果的便于人类阅读的说明，包括输入错误验证码后的剩余尝试次数。" }, "phone": { "type": "object", "nullable": true, "description": "完整的电话报告。仅在已完成的结果（`Approved`/`Declined`）中出现（非 null）；状态为 `Failed` 时为 `null`，状态为 `Expired or Not Found` 时不存在。", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Not Finished", "Expired" ], "description": "电话验证的最终状态。对于已完成的检查，与顶级 `status` 一致。" }, "phone_number_prefix": { "type": "string", "description": "带前导 `+` 的国家/地区国际呼叫代码（例如 `+1`）。", "example": "+1" }, "phone_number": { "type": "string", "description": "不含国家/地区呼叫代码的国内号码。", "example": "4155552671" }, "full_number": { "type": "string", "description": "E.164 格式的完整号码。", "example": "+14155552671" }, "country_code": { "type": "string", "nullable": true, "description": "号码所在国家/地区的 ISO 3166-1 alpha-2 代码。", "example": "US" }, "country_name": { "type": "string", "description": "从 `country_code` 推导出的国家/地区全称。", "example": "United States" }, "carrier": { "type": "object", "description": "当前为该号码提供服务的网络，来自完成阶段运行的运营商查询。", "properties": { "name": { "type": "string", "description": "运营商名称。当查询无法识别时为空字符串。" }, "type": { "type": "string", "description": "查询报告的线路类型：`mobile`、`fixed_line`、`voip`、`isp`、`vpn`、`toll_free`、`premium_rate`、`pager`、`payphone`、`satellite`、`service`、`shared_cost`、`short_codes_commercial`、`calling_cards`、`local_rate`、`universal_access`、`voice_mail`、`other` 或 `unknown`。" } } }, "is_disposable": { "type": "boolean", "description": "当号码属于临时/一次性号码服务时为 `true`。" }, "is_virtual": { "type": "boolean", "description": "当线路类型为虚拟线路（`voip`、`isp` 或 `vpn`）时为 `true`。" }, "verification_method": { "type": "string", "description": "投递确认后实际投递 OTP 的渠道（例如 `whatsapp`、`sms`）；在此之前为请求的渠道。" }, "verification_attempts": { "type": "integer", "description": "此验证发送 OTP 的次数（1 次，重试后为 2 次）。" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "输入正确代码的时间。如果验证从未通过，则为 `null`。" }, "warnings": { "type": "array", "description": "验证期间记录的风险警告（重复、一次性、VoIP、超出尝试次数、黑名单等）。无任何警告时为空数组。", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "产生该警告的功能。在此处始终为 `PHONE`。" }, "risk": { "type": "string", "description": "机器可读的风险代码。" }, "additional_data": { "type": "object", "nullable": true, "description": "特定风险的上下文（例如重复风险对应的重复会话 id）。当风险不包含额外数据时为 `null`。" }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "严重程度。`error` 级别的风险会导致验证被拒绝，`warning` 会将其标记为待审核，`information` 仅作记录而不影响状态。" }, "short_description": { "type": "string", "description": "易于阅读的单行风险摘要。" }, "long_description": { "type": "string", "description": "风险的便于人类阅读的说明。" } } } }, "lifecycle": { "type": "array", "description": "验证的时间顺序审计记录。事件 `type` 为以下之一：`PHONE_VERIFICATION_MESSAGE_SENT`、`PHONE_VERIFICATION_RETRY_MESSAGE_SENT`、`PHONE_VERIFICATION_BLOCKED`、`PHONE_DELIVERY_DELIVERED`、`PHONE_DELIVERY_UNDELIVERABLE`、`VALID_CODE_ENTERED`、`INVALID_CODE_ENTERED`、`PHONE_VERIFICATION_APPROVED`、`PHONE_VERIFICATION_DECLINED`、`PHONE_VERIFICATION_IN_REVIEW`、`PHONE_VERIFICATION_EXPIRED`。", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "事件类型。" }, "timestamp": { "type": "string", "format": "date-time", "description": "事件发生的时间。" }, "details": { "type": "object", "nullable": true, "description": "特定事件的 payload。发送事件：`{status, reason, channel, actual_channel}`（确认投递后填充 `actual_channel`）。投递事件：`{channel, status}`。验证码输入事件：`{code_tried, status}`。最终状态事件：`null`，或在已拒绝或审核中时为 `{reason}`。" }, "fee": { "type": "number", "description": "此事件计费的美元金额。仅在发送事件（投递价格）时不为零；对于验证码输入、投递确认和状态事件为 0。" } } } }, "matches": { "type": "array", "description": "您应用中由不同用户（不同 `vendor_data`）使用相同电话号码的其他会话（KYC、KYB 或 API）。最多 5 条记录，存在合成列表条目黑名单匹配时优先排列（从会话派生的匹配保留查询顺序）。无匹配项时为空数组。", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "使用此电话号码的另一个验证的会话 id。" }, "session_number": { "type": "integer", "description": "该会话便于人类阅读的序号。" }, "vendor_data": { "type": "string", "nullable": true, "description": "该会话的 `vendor_data`。" }, "verification_date": { "type": "string", "description": "该会话的创建时间（`YYYY-MM-DDTHH:MM:SSZ`）。" }, "phone_number": { "type": "string", "description": "匹配的电话号码。" }, "status": { "type": "string", "description": "该会话的状态（例如 `Approved`、`Declined`、`In Progress`）。" }, "is_blocklisted": { "type": "boolean", "description": "电话号码是否在您应用的黑名单中。" }, "api_service": { "type": "string", "nullable": true, "description": "对于 API 类型的会话，为创建该会话的独立 API（例如 `PHONE_VERIFICATION`）；对于常规验证会话为 `null`。" }, "source": { "type": "string", "description": "发现匹配的位置。通常为 `session`；通过组织名单条目命中的黑名单会在前面附加一个合成的匹配项，其 `source: \"list_entry\"` 且 `session_id`/`session_number` 为 null。" } } } }, "phone_social": { "$ref": "#/components/schemas/PhoneSocialFootprint" }, "phone_intelligence": { "allOf": [ { "$ref": "#/components/schemas/PhoneIntelligence" } ], "description": "电话智能信号。仅在检查中 `enable_enrichment` 为 `true` 时存在。" } } }, "vendor_data": { "type": "string", "nullable": true, "description": "匹配验证会话的 `vendor_data`。若为 `Expired or Not Found` 则为 `null`。" }, "metadata": { "type": "object", "nullable": true, "description": "匹配验证会话的 `metadata`。在 `Expired or Not Found` 时为 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "此检查响应的时间戳。" } } }, "EmailVerificationSendResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "验证的会话 id。`Retry` 发送会返回与原始发送相同的 `request_id`。此 id 会显示在 Business Console 中，在已完成的 `POST /v3/email/check/` 中再次返回，并可传递给 `GET /v3/session/{sessionId}/decision/`。" }, "status": { "type": "string", "enum": [ "Success", "Retry", "Undeliverable" ], "description": "`Success`：OTP 已通过邮件发送至新的验证（计费）。`Retry`：为先前发送创建的待处理验证重新发送了新的 OTP（免费）。`Undeliverable`：地址未通过可达性核验或消息无法发送；验证立即以 `Declined` 终结，且不产生计费。" }, "reason": { "type": "string", "nullable": true, "enum": [ "email_can_not_be_delivered", null ], "description": "当 `status` 为 `Undeliverable` 时为 `email_can_not_be_delivered`；否则为 `null`。" }, "vendor_data": { "type": "string", "nullable": true, "description": "存储在会话中的 `vendor_data` 回显（来自首次发送）。" }, "metadata": { "type": "object", "nullable": true, "description": "存储在会话中的 `metadata` 回显（来自首次发送）。" } } }, "EmailVerificationCheckResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid", "description": "状态为 `Approved`/`Declined` 时：匹配验证的会话 ID，与 `POST /v3/email/send/` 返回的 `request_id` 相同。状态为 `Failed` 和 `Expired or Not Found` 时：一个随机的一次性 UUID，后续无法查询。" }, "status": { "type": "string", "enum": [ "Approved", "Declined", "Failed", "Expired or Not Found" ], "description": "`Approved` — 验证码正确，无拒绝风险。`Declined` — 最终状态：匹配到拒绝风险或尝试次数上限（3）已用尽。`Failed` — 验证码错误，仍有剩余尝试次数。`Expired or Not Found` — 在过去 5 分钟内该地址没有待处理的验证。" }, "message": { "type": "string", "description": "结果的便于人类阅读的说明，包括输入错误验证码后的剩余尝试次数。" }, "email": { "type": "object", "nullable": true, "description": "完整邮箱报告。仅在已完成的结果（`Approved`/`Declined`）中存在（非 null）；在 `Failed` 时为 `null`，在 `Expired or Not Found` 时不存在。", "properties": { "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Not Finished", "Expired" ], "description": "邮箱验证的最终状态。对于已完成的检查，与顶级 `status` 一致。" }, "email": { "type": "string", "format": "email", "description": "已验证的邮箱地址。", "example": "alice@example.com" }, "is_breached": { "type": "boolean", "description": "当该地址出现在已知数据泄露事件中时为 `true`（在最终确认时运行泄露情报查询）。" }, "breaches": { "type": "array", "description": "包含此地址的最多 5 次最近已知数据泄露事件。当 `is_breached` 为 `false` 时为空数组（或省略）。", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "数据泄露标识符。" }, "domain": { "type": "string", "description": "发生泄露的服务的域名。" }, "breach_date": { "type": "string", "format": "date", "description": "违规行为发生的日期。" }, "breach_emails_count": { "type": "integer", "description": "泄露事件中暴露的账户总数。" }, "description": { "type": "string", "description": "便于人类阅读的泄露事件描述（可能包含 HTML 标记）。" }, "logo_path": { "type": "string", "description": "发生数据泄露的服务徽标 URL。" }, "data_classes": { "type": "array", "items": { "type": "string" }, "description": "泄露的数据类别，采用 snake_case 格式（例如 `email_addresses`、`passwords`）。" }, "is_verified": { "type": "boolean", "description": "该泄露事件是否已被核实为真实存在。" } } } }, "is_disposable": { "type": "boolean", "description": "当域名属于已知的临时/一次性邮箱服务商时为 `true`。" }, "is_undeliverable": { "type": "boolean", "description": "当该地址无法接收邮件（语法或 DNS/MX 验证失败，或邮件被退回）时为 `true`。" }, "verification_attempts": { "type": "integer", "description": "此验证发送 OTP 的次数（1 次，重试后为 2 次）。" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "输入正确代码的时间。如果验证从未通过，则为 `null`。" }, "warnings": { "type": "array", "description": "验证期间记录的风险警告（重复、泄露、一次性、无法投递、超出尝试次数、黑名单等）。无任何警告时为空数组。", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "产生该警告的功能。在此处始终为 `EMAIL`。" }, "risk": { "type": "string", "description": "机器可读的风险代码。" }, "additional_data": { "type": "object", "nullable": true, "description": "特定风险的上下文（例如重复风险对应的重复会话 id）。当风险不包含额外数据时为 `null`。" }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "严重程度。`error` 级别的风险会导致验证被拒绝，`warning` 会将其标记为待审核，`information` 仅作记录而不影响状态。" }, "short_description": { "type": "string", "description": "易于阅读的单行风险摘要。" }, "long_description": { "type": "string", "description": "风险的便于人类阅读的说明。" } } } }, "lifecycle": { "type": "array", "description": "验证的时间顺序审计记录。事件 `type` 为以下之一：`EMAIL_VERIFICATION_MESSAGE_SENT`、`EMAIL_VERIFICATION_RETRY_MESSAGE_SENT`、`VALID_CODE_ENTERED`、`INVALID_CODE_ENTERED`、`EMAIL_VERIFICATION_APPROVED`、`EMAIL_VERIFICATION_DECLINED`、`EMAIL_VERIFICATION_IN_REVIEW`、`EMAIL_VERIFICATION_EXPIRED`。", "items": { "type": "object", "properties": { "type": { "type": "string", "description": "事件类型。" }, "timestamp": { "type": "string", "format": "date-time", "description": "事件发生的时间。" }, "details": { "type": "object", "nullable": true, "description": "特定事件的 payload。发送事件：`{status, reason}`。验证码输入事件：`{code_tried, status}`。最终状态事件：`null`，或在已拒绝或审核中时为 `{reason}`。" }, "fee": { "type": "number", "description": "此事件计费的美元金额。仅在首次成功发送时不为零；对于重试、验证码输入和状态事件为 0。" } } } }, "matches": { "type": "array", "description": "您的应用（KYC、KYB 或 API）中不同用户（不同的 `vendor_data`）使用相同邮箱地址的其他会话。最多 5 个条目；如果存在基于名单条目的黑名单匹配（且仅当不存在源自会话的黑名单邮箱时），该匹配项会置于开头，源自会话的匹配项保持 created_at 排序。无匹配项时为空数组。", "items": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "使用此邮箱地址的另一个验证的会话 id。" }, "session_number": { "type": "integer", "description": "该会话便于人类阅读的序号。" }, "vendor_data": { "type": "string", "nullable": true, "description": "该会话的 `vendor_data`。" }, "verification_date": { "type": "string", "description": "该会话的创建时间（`YYYY-MM-DDTHH:MM:SSZ`）。" }, "email": { "type": "string", "description": "匹配的邮箱地址。" }, "status": { "type": "string", "description": "该会话的状态（例如 `Approved`、`Declined`、`In Progress`）。" }, "is_blocklisted": { "type": "boolean", "description": "该邮箱地址是否在您应用的黑名单中。" }, "api_service": { "type": "string", "nullable": true, "description": "对于 API 类型的会话，为创建该会话的独立 API（例如 `PHONE_VERIFICATION`）；对于常规验证会话为 `null`。" }, "source": { "type": "string", "description": "发现匹配的位置。通常为 `session`；通过组织名单条目命中的黑名单会在前面附加一个合成的匹配项，其 `source: \"list_entry\"` 且 `session_id`/`session_number` 为 null。" } } } }, "email_social": { "$ref": "#/components/schemas/EmailSocialFootprint" }, "email_intelligence": { "allOf": [ { "$ref": "#/components/schemas/EmailIntelligence" } ], "description": "邮箱情报信号。仅在检查中 `enable_enrichment` 为 `true` 时存在。" } } }, "vendor_data": { "type": "string", "nullable": true, "description": "匹配验证会话的 `vendor_data`。若为 `Expired or Not Found` 则为 `null`。" }, "metadata": { "type": "object", "nullable": true, "description": "匹配验证会话的 `metadata`。在 `Expired or Not Found` 时为 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "此检查响应的时间戳。" } } }, "WorkflowListItem": { "type": "object", "description": "列表视图中的一个工作流版本。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "每个版本对应的 UUID。在获取/更新/删除时用作 `{settings_uuid}`，创建会话时用作 `workflow_id`。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "同一工作流的所有版本共享的稳定分组 ID。版本 1 时等于 `uuid`。" }, "workflow_label": { "type": "string", "description": "工作流的显示名称。" }, "workflow_type": { "type": "string", "nullable": true, "description": "简单工作流的基础类型：`kyc`、`kyb`、`adaptive_age_verification`、`biometric_authentication` 等。对于不含 KYB 功能的基于图谱的工作流为 `null`。" }, "is_default": { "type": "boolean", "description": "这是否为新会话的默认工作流。" }, "is_archived": { "type": "boolean" }, "is_white_label_enabled": { "type": "boolean", "description": "使用此工作流创建的会话是否应用白标自定义配置。" }, "total_price": { "type": "number", "description": "每次验证的固定价格（美元，JSON 数字，不包含按可变价格计费的功能，例如 DATABASE_VALIDATION 和 PHONE_VERIFICATION）。" }, "min_price": { "type": "number", "description": "工作流图谱各路径中的最低固定价格，以 USD 计。" }, "max_price": { "type": "number", "description": "工作流图谱各路径中最昂贵的固定价格，以 USD 计。" }, "features": { "type": "string", "description": "以 `\" + \"` 连接的单个字符串形式表示的已启用功能，例如 `\"OCR + LIVENESS + FACE_MATCH\"`。按 `\" + \"` 拆分即可获取列表。" }, "is_simple_workflow": { "type": "boolean", "description": "当工作流没有自定义工作流图谱时为 true。" }, "is_editable": { "type": "boolean", "description": "当此版本为 `draft` 时为 True（草稿可直接原地编辑；已发布版本在 Console 中不可更改）。" }, "workflow_url": { "type": "string", "format": "uri", "description": "此工作流的可共享公开验证 URL（`https://verify.didit.me/u/`）。" }, "max_retry_attempts": { "type": "integer", "description": "验证被拒绝后允许的最大重试次数（0-10）。" }, "retry_window_days": { "type": "integer", "nullable": true, "description": "用于计算重试次数的滑动时间窗口，以天为单位（1-365）。`null` = 历史累计限制。" }, "session_expiration_time": { "type": "integer", "description": "未完成会话过期前的秒数（3600-2419200）。" }, "version": { "type": "integer", "description": "`workflow_id` 分组内的版本号，从 1 开始。" }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "版本状态。新会话使用分组最新的 `published` 版本。" }, "has_draft": { "type": "boolean", "description": "当此 `workflow_id` 分组中的任何版本当前为草稿时为 true。" }, "created_by": { "type": "object", "nullable": true, "description": "创建此版本的主体：`{name, email, type}`，其中 `type` 为 `user`（控制台用户，已设置 `email`）或 `api_key`（`name` 为客户端 ID，`email` 为 null）。未记录创建者时为 `null`。", "properties": { "name": { "type": "string" }, "email": { "type": "string", "nullable": true }, "type": { "type": "string", "enum": [ "user", "api_key" ] } } }, "updated_at": { "type": "string", "format": "date-time" } } }, "SimpleWorkflowRequest": { "type": "object", "description": "创建简单的线性工作流。API 会在内部将此功能列表转换为基于节点的工作流图谱。严格的字段白名单：此处未列出的任何键（包括 `workflow_type`）都会被拒绝并返回 400。", "required": [ "features" ], "properties": { "workflow_label": { "type": "string", "maxLength": 50, "default": "ID Verification", "description": "工作流的显示名称（最多 50 个字符）。省略时默认为 `\"ID Verification\"`，请始终设置该值以使工作流保持可区分。", "example": "Standard KYC" }, "is_default": { "type": "boolean", "description": "将此工作流设为新会话的默认工作流。" }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "省略此字段可创建已发布且可用于会话的工作流。仅当您希望保存而不发布时才使用 `draft`。" }, "features": { "type": "array", "minItems": 1, "description": "按执行顺序排列的验证功能。API 会自动将每个项链接到下一个项，并自动添加一个最终的状态节点。", "items": { "$ref": "#/components/schemas/SimpleWorkflowFeature" } }, "is_white_label_enabled": { "type": "boolean", "description": "为使用此工作流创建的会话启用白标定制。", "default": false }, "is_desktop_allowed": { "type": "boolean", "description": "允许验证流程在桌面端浏览器上运行。", "default": false }, "max_retry_attempts": { "type": "integer", "minimum": 0, "maximum": 10, "default": 3, "description": "验证被拒绝后允许的最大重试次数。`0` 表示在首次拒绝后即阻止用户。" }, "retry_window_days": { "type": "integer", "minimum": 1, "maximum": 365, "nullable": true, "default": 7, "description": "用于计算重试次数的滑动时间窗口，以天为单位。`null` 执行历史累计限制。" }, "face_liveness_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "default": 3, "description": "每次会话允许的最大活体检测提交次数。默认值为 3：一次初始尝试加上两次重试。除非功能级配置覆盖，否则该值也会复制到生成的活体检测和年龄估算工作流节点中。" }, "face_match_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "default": 3, "description": "每次会话允许的最大人脸比对提交次数。默认值为 3：一次初始尝试加上两次重试。除非功能级配置覆盖，否则该值也会复制到生成的人脸比对工作流节点中。" }, "session_expiration_time": { "type": "integer", "minimum": 3600, "maximum": 2419200, "default": 604800, "description": "未完成会话过期前的秒数。最短 1 小时（3600），最长 4 周（2419200）。" } } }, "SimpleWorkflowUpdateRequest": { "type": "object", "description": "更新工作流元数据或替换完整的线性功能列表。严格的字段白名单：此处未列出的任何键都将被拒绝并返回 400。", "properties": { "workflow_label": { "type": "string", "maxLength": 50, "description": "工作流的显示名称（最多 50 个字符）。" }, "is_default": { "type": "boolean", "description": "将此工作流设为新会话的默认工作流。" }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "控制版本管理。省略此项将就地更新当前版本（草稿会自动发布）。对已发布的版本传入 `published` 将创建并返回新版本。`draft` 仅在当前版本仍为草稿时有效。" }, "features": { "type": "array", "minItems": 1, "description": "如果提供，将替换完整的功能顺序和配置。", "items": { "$ref": "#/components/schemas/SimpleWorkflowFeature" } }, "is_white_label_enabled": { "type": "boolean", "description": "为使用此工作流创建的会话启用白标定制。" }, "is_desktop_allowed": { "type": "boolean", "description": "允许验证流程在桌面端浏览器上运行。" }, "max_retry_attempts": { "type": "integer", "minimum": 0, "maximum": 10, "description": "验证被拒绝后允许的最大重试次数。`0` 表示在首次拒绝后即阻止用户。" }, "retry_window_days": { "type": "integer", "minimum": 1, "maximum": 365, "nullable": true, "description": "用于计算重试次数的滑动时间窗口，以天为单位。`null` 执行历史累计限制。" }, "face_liveness_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "每次会话允许的最大活体检测提交次数。除非功能级配置覆盖，否则该值也会复制到生成的活体检测和年龄估算工作流节点中。" }, "face_match_max_attempts": { "type": "integer", "minimum": 1, "maximum": 3, "description": "每次会话允许的最大人脸比对提交次数。除非功能级配置覆盖，否则该值也会复制到生成的人脸比对工作流节点中。" }, "session_expiration_time": { "type": "integer", "minimum": 3600, "maximum": 2419200, "description": "未完成会话过期前的秒数。最短 1 小时（3600），最长 4 周（2419200）。" } } }, "SimpleWorkflowFeature": { "type": "object", "required": [ "feature" ], "properties": { "feature": { "type": "string", "description": "要运行的功能。请使用此处显示的大写值。", "enum": [ "OCR", "NFC", "LIVENESS", "FACE_MATCH", "PROOF_OF_ADDRESS", "QUESTIONNAIRE", "DOCUMENT_AI", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "DATABASE_VALIDATION", "AML", "IP_ANALYSIS", "AGE_ESTIMATION", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "SIGNATURE" ] }, "config": { "type": "object", "description": "特定功能的设置。对于 `QUESTIONNAIRE`，请在 `questionnaire_uuid` 中传入问卷创建 endpoint 返回的 `questionnaire_id`。对于 `SIGNATURE`，上线的工​​作流需要待签署的证件：将 `signature_documents_source` 设置为 `session` 或 `both` 以便每次会话自带证件，或者发送 `status: \"draft\"` 并在发布前添加证件。当工作流上的 `signature_availability.aes` 为 `false` 时，`signature_level: \"aes\"` 会被拒绝并返回 `aes_not_available`。对于 `OCR`，`methods` 用于选择每个国家/地区可以使用的身份证件验证方法（证件采集、针对政府或其他权威来源的非证件查询，以及数字身份钱包）；如果省略，则所有国家/地区仅支持证件采集。对于 `SIGNATURE`，请参阅[电子签名设置](/zh/management-api/workflows/feature-configs#电子签名)：`signature_level` 目前接受 `simple`（默认值，无需身份证件验证、邮箱或电话）和 `aes`，工作流证件及其字段在控制台中管理，因此通过 API 请使用 `signature_documents_source: \"session\"` 按每次会话发送证件和字段。", "additionalProperties": true }, "label": { "type": "string", "description": "此工作流节点的可选内部标签。" } } }, "ReviewItem": { "type": "object", "description": "会话审核/活动动态中的一个条目。状态变更包含 `previous_status`、`new_status`、`previous_value`、`new_value` 和 `changed_fields`；评论包含 `comment` 以及（对于 Console 评论）`mentioned_emails`；其余字段若不适用于该活动类型，则为 `null` 或留空。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "此动态条目的唯一标识符。", "example": "de0561bc-5583-4409-9171-1a31a4c8a5f4" }, "activity_type": { "type": "string", "enum": [ "COMMENT", "STATUS_UPDATED", "KYC_DATA_UPDATED", "POA_DATA_UPDATED", "FILE_ADDED", "FILE_REMOVED", "AML_ONGOING_MATCH", "AML_STATUS_UPDATED", "AML_HIT_STATUS_UPDATED", "KYB_DATA_UPDATED", "KYB_DOCUMENT_UPLOADED", "TAG_ADDED", "TAG_REMOVED", "FEATURE_OVERRIDE_PENDING", "FEATURE_OVERRIDE_APPLIED", "FEATURE_OVERRIDE_CANCELLED" ], "description": "该条目记录的活动类型。`STATUS_UPDATED` 行来自人工决策（`PATCH /v3/session/{session_id}/update-status/`）以及通过 `POST …/reviews/` 添加的条目（即使未记录状态，也默认为此类型）。`COMMENT` 行来自 Console 审核员；Console 详情页查看也存储为标记有 `metadata.system_event = \"DETAIL_VIEWED\"` 的 `COMMENT` 行。其余类型用于跟踪数据编辑、文件变更、标签和 AML 监控活动。STATUS_UPDATED 行也可由系统主体写入（例如 actor_type 为 SYSTEM 的持续 AML 监控，以及自动功能状态更新），而不仅由 update-status endpoint 和人工审核提交写入。`FEATURE_OVERRIDE_PENDING`、`FEATURE_OVERRIDE_APPLIED` 和 `FEATURE_OVERRIDE_CANCELLED` 记录对单个检查状态的覆盖（`PATCH /v3/session/{session_id}/features/{node_id}/update-status/`）：已请求等待流程完成、已应用或已取消。它们在 `previous_value` / `new_value`（`{\"status\": ...}`）中携带该检查的状态，使 `previous_status` 和 `new_status` 保持为 `null`，并在 `metadata` 中指定覆盖信息（`feature_override_id`、`node_id`、`feature_model`、`forced`、`state`、`cancel_reason`）。请求对应的条目包含审核员的 `comment`；在流程完成时应用的覆盖所记录的 `actor_type` 为 `SYSTEM`。", "example": "STATUS_UPDATED" }, "actor_display": { "type": "string", "description": "便于人类阅读的操作者标签，按以下顺序解析：操作者姓名 → Console 账户标识符 → `actor_email` 的本地部分 → `\"API Client\"`（针对 `API_KEY` 操作者）→ `\"System\"`（针对 `SYSTEM` 操作者）→ `\"Unknown\"`。通过 `POST …/reviews/` 创建的条目始终显示 `\"Unknown\"`，因为该 endpoint 不记录操作者归属。", "example": "API Client" }, "actor_email": { "type": "string", "nullable": true, "description": "执行该操作的 Console 用户的邮箱。API 密钥和系统执行者为 `null`。", "example": null }, "actor_type": { "type": "string", "enum": [ "API_KEY", "CONSOLE_USER", "SYSTEM" ], "description": "执行该操作的主体：API 密钥、控制台用户或 Didit 本身（`SYSTEM`，例如 AML 持续监控）。无论调用方是谁，通过 `POST …/reviews/` 创建的条目均带有默认值 `CONSOLE_USER`。", "example": "API_KEY" }, "new_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "此条目记录的会话状态（用于状态更新）。对于评论和数据变更条目为 `null`。", "example": "Approved" }, "previous_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "变更前会话所处的状态。在更新状态 endpoint 写入的 `STATUS_UPDATED` 条目中填充；在通过 `POST …/reviews/` 添加的条目中为 `null`。系统写入的 STATUS_UPDATED 行中也会填充。", "example": "In Review" }, "comment": { "type": "string", "nullable": true, "description": "附加至该条目的自由文本备注，或为 `null`。", "example": "Document re-checked manually; address matches." }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "在评论中通过 `@email` 提及的 Console 用户。对于通过此 API 创建的条目，该项始终为空；提及处理仅为 Console 专有功能。", "example": [] }, "previous_value": { "type": "object", "nullable": true, "description": "操作前发生变更的数据快照，例如状态变更时的 `{\"status\": \"In Review\"}`。若未发生变更则为 `null`。", "example": { "status": "In Review" } }, "new_value": { "type": "object", "nullable": true, "description": "操作后发生变更的数据快照，例如 `{\"status\": \"Approved\"}`。若未发生变更则为 `null`。", "example": { "status": "Approved" } }, "changed_fields": { "type": "array", "items": { "type": "string" }, "description": "此活动修改的字段名称（例如 `[\"status\"]`）。对于评论以及通过 `POST …/reviews/` 添加的条目为空。", "example": [ "status" ] }, "metadata": { "type": "object", "nullable": true, "description": "系统生成条目的额外上下文。控制台详情页面浏览会包含 `{\"system_event\": \"DETAIL_VIEWED\", \"detail_type\": \"verification\"}`，以便在通知逻辑中过滤掉它们。其作者在控制台中编辑过的 `COMMENT` 会包含 `edited_at`，即最后一次编辑的 ISO 8601 时间（`comment` 和 `mentioned_emails` 随后保存编辑后的文本及其提及内容）。对于普通条目为 `null`。", "example": null }, "created_at": { "type": "string", "format": "date-time", "description": "条目写入的时间，ISO 8601 UTC 格式。", "example": "2026-06-12T00:19:31.918735Z" } } }, "QuestionnaireListItem": { "type": "object", "description": "列表视图中的一个问卷版本。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "每个版本对应的 UUID。在获取/更新/删除时用作 `{questionnaire_uuid}`，在工作流的 QUESTIONNAIRE 功能配置中用作 `questionnaire_uuid`。" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "is_active": { "type": "boolean" }, "is_simple_questionnaire": { "type": "boolean", "description": "对于通过此 API 创建的线性问卷为 true；对于在控制台中构建的基于图谱的问卷为 false。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "question_types": { "type": "array", "items": { "type": "string" }, "description": "可回答问题的大写元素类型，按创建顺序排列（例如 `SHORT_TEXT`、`MULTIPLE_CHOICE`、`FILE_UPLOAD`）。结构性的 `SECTION_HEADER` 和 `SEPARATOR` 元素不包含在内。每个问题对应一项，因此值可能会重复。" }, "workflow_names": { "type": "array", "items": { "type": "string" }, "description": "使用此问卷的工作流名称。当前在此 endpoint 上始终为 `[]`（仅在控制台列表中填充）。" }, "questionnaire_group_id": { "type": "string", "format": "uuid", "description": "用于将同一问卷的所有版本分组的稳定标识符。" }, "version": { "type": "integer", "description": "分组内的版本号，从 1 开始。" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "format": "date-time", "nullable": true, "description": "此版本发布的时间。草稿为 `null`。" }, "is_editable": { "type": "boolean", "description": "当此版本为 `draft` 时为 True。" } } }, "SimpleQuestionnaireRequest": { "type": "object", "description": "创建简单的线性问卷。API 会在内部将 `form_elements` 转换为内部问卷图谱。", "required": [ "title", "languages", "form_elements" ], "properties": { "title": { "type": "string", "description": "问卷的内部名称。" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "description": "每个标签中包含的语言。必须包含 `en`。", "items": { "type": "string" }, "example": [ "en" ] }, "default_language": { "type": "string", "description": "默认语言。必须包含在 `languages` 中。", "example": "en" }, "is_active": { "type": "boolean", "default": true }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "省略此字段可创建已发布且可用于工作流的问卷。" }, "form_elements": { "type": "array", "minItems": 1, "description": "用户应该看到的严格顺序的问题。不支持分支和条件字段。", "items": { "$ref": "#/components/schemas/SimpleQuestionnaireElement" } } } }, "SimpleQuestionnaireUpdateRequest": { "type": "object", "description": "更新问卷元数据或替换完整的线性 `form_elements` 列表。", "properties": { "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "is_active": { "type": "boolean" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "form_elements": { "type": "array", "minItems": 1, "description": "如果提供，将替换完整的线性问题列表。", "items": { "$ref": "#/components/schemas/SimpleQuestionnaireElement" } } } }, "SimpleQuestionnaireElement": { "type": "object", "required": [ "element_type", "label" ], "properties": { "id": { "type": "string", "description": "可选的稳定问题 ID。如果省略，API 将生成 `q1`、`q2` 等。为确保可读性，请使用小写字母、数字和下划线。", "example": "source_of_funds" }, "element_type": { "type": "string", "description": "问题类型。API 接受这些小写值及其对应的大写形式。", "enum": [ "short_text", "long_text", "dropdown", "single_choice", "multiple_choice", "number", "image", "file_upload", "time", "email", "address", "phone", "country", "date_picker", "consent", "section_header", "separator", "heading", "paragraph" ] }, "label": { "type": "object", "description": "按语言代码划分的问题标签，例如 `{ \"en\": \"Source of funds\" }`。", "additionalProperties": { "type": "string" } }, "description": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "placeholder": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" } }, "is_required": { "type": "boolean", "default": false }, "options": { "type": "array", "description": "用于 `dropdown`、`single_choice` 和 `multiple_choice`。如果省略 `value`，API 会根据选项标签生成一个值。", "items": { "type": "object", "required": [ "label" ], "properties": { "value": { "type": "string" }, "label": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "max_files": { "type": "integer", "minimum": 1, "maximum": 5, "description": "与 `file_upload` 或 `image` 一起使用。" }, "validation": { "type": "object", "nullable": true, "description": "针对 `short_text`、`long_text` 或 `number` 的可选格式验证。在用户填写字段时强制执行（验证通过后方可继续），并在提交时由 API 重新检查。", "properties": { "pattern": { "type": "string", "description": "该值必须完全匹配的正则表达式（ECMA-262 子集）。适用于 `short_text` 和 `long_text`。请勿添加 ^/$ 锚点；系统将对整个值进行匹配。" }, "min_length": { "type": "integer", "minimum": 0, "description": "最小字符数。适用于 `short_text` 和 `long_text`。" }, "max_length": { "type": "integer", "minimum": 0, "description": "最大字符数。适用于 `short_text` 和 `long_text`。" }, "min": { "type": "number", "description": "最小数值。适用于 `number`。" }, "max": { "type": "number", "description": "最大数值。适用于 `number`。" }, "error_message": { "type": "object", "description": "验证失败时显示的已翻译消息，以语言代码为键。", "additionalProperties": { "type": "string" } } } } } }, "QuestionnaireDetail": { "type": "object", "description": "从 GET、POST（创建）和 PATCH（更新）endpoint 返回的完整问卷详情。", "properties": { "questionnaire_id": { "type": "string", "format": "uuid", "description": "问卷的唯一标识符。在工作流中引用该问卷或在后续更新/删除请求中使用此 ID。" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "languages": { "type": "array", "items": { "type": "string" } }, "default_language": { "type": "string" }, "is_active": { "type": "boolean" }, "is_simple_questionnaire": { "type": "boolean" }, "graph": { "type": "object", "description": "包含 start_node 和 nodes 映射的图谱结构。" }, "sections": { "type": "array", "description": "分组到各节中的问卷内容（源自图谱）。", "items": { "type": "object" } }, "questionnaire_group_id": { "type": "string", "format": "uuid", "description": "用于将同一问卷的所有版本分组的稳定标识符。" }, "version": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": "string", "format": "date-time", "nullable": true }, "is_editable": { "type": "boolean", "description": "当问卷仍可就地编辑（草稿版本）时为 true。" } } }, "UserListItem": { "type": "object", "description": "已验证的用户。", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "Didit 为此用户分配的稳定内部 UUID。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您对此用户的唯一标识符（创建会话时传入）。未提供供应商标识符时可为 null。" }, "display_name": { "type": "string", "nullable": true, "description": "您设置的自定义显示名称" }, "full_name": { "type": "string", "nullable": true, "description": "从已验证证件中提取的姓名" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "effective_name": { "type": "string", "nullable": true, "description": "最佳可用名称：如果已设置则为 display_name，否则为 full_name" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "用户记录的生命周期状态（并非会话状态）。`ACTIVE` 为默认值，`FLAGGED` 标记该用户需要人工关注，`BLOCKED` 会阻止该 `vendor_data` 创建新会话。" }, "portrait_image_url": { "type": "string", "nullable": true, "description": "用户肖像照片的预签名 URL（数小时后过期）" }, "session_count": { "type": "integer", "description": "该用户的验证会话总数" }, "approved_count": { "type": "integer", "description": "已通过的会话数量" }, "declined_count": { "type": "integer", "description": "已拒绝的会话数量" }, "in_review_count": { "type": "integer", "description": "审核中的会话数量" }, "issuing_states": { "type": "array", "items": { "type": "string" }, "description": "此用户已通过的身份证件上显示的签发国家/地区的 ISO 3166-1 alpha-3 代码，例如 `[\"USA\", \"ESP\"]`。无时为空数组。" }, "approved_emails": { "type": "array", "items": { "type": "string" }, "description": "从该用户已通过的会话中收集的已验证邮箱地址，例如 `[\"john@example.com\"]`。" }, "approved_phones": { "type": "array", "items": { "type": "string" }, "description": "从该用户已通过的会话中收集的已验证电话号码，例如 `[\"+14155551234\"]`。" }, "features": { "type": "object", "description": "该用户所有会话的每项功能汇总状态。可选键：`ID_VERIFICATION`、`NFC`、`LIVENESS`、`FACE_MATCH`、`POA`、`QUESTIONNAIRE`、`EMAIL_VERIFICATION`、`PHONE`、`AML`、`IP_ANALYSIS`、`AGE_ESTIMATION`、`DATABASE_VALIDATION`。可选值：`Approved`、`Declined`、`In Review`、`Not Finished`、`Resub Requested`。" }, "features_list": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "status": { "type": "string" } } }, "description": "与 `features` 相同的数据，为 `{feature, status}` 对象的有序数组。" }, "last_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "最近一次会话的时间戳" }, "first_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "首次会话的时间戳" }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true, "description": "该用户最近一次活动的时间戳（会话、交易、状态变更、数据编辑等）。" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "description": "分配给该用户的标签" }, "created_at": { "type": "string", "format": "date-time" } } }, "BlocklistItem": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "face", "document", "phone", "email" ] }, "session_id": { "type": "string", "format": "uuid" }, "session_number": { "type": "integer" }, "blocklisted_at": { "type": "string", "format": "date-time" }, "face_image": { "type": "string", "nullable": true }, "document_type": { "type": "string", "nullable": true }, "document_number": { "type": "string", "nullable": true }, "phone_number": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "UserDetailItem": { "type": "object", "description": "完整的用户详情。在 UserListItem 基础上扩展了元数据、备注和 updated_at。", "allOf": [ { "$ref": "#/components/schemas/UserListItem" }, { "type": "object", "properties": { "metadata": { "type": "object", "description": "您附加到此用户的自定义元数据 JSON。默认为 `{}`。" }, "tags": { "type": "array", "description": "标签分配情况。注意：与列表响应中使用的扁平 `{uuid, name, color}` 结构不同，详情响应中的每个条目均为标签*链接*对象（`{uuid, tag: {...}, added_by_email, added_by_name, created_at}`）。", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "标签分配的 UUID（而非标签本身的 UUID）。" }, "tag": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ] }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "added_by_email": { "type": "string", "nullable": true }, "added_by_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } } }, "comments": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "comment_type": { "type": "string", "enum": [ "COMMENT", "STATUS_CHANGED", "METADATA_UPDATED", "TAG_ADDED", "TAG_REMOVED", "PROFILE_UPDATED" ] }, "comment": { "type": "string", "nullable": true }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "previous_status": { "type": "string", "nullable": true, "enum": [ "ACTIVE", "FLAGGED", "BLOCKED", null ] }, "new_status": { "type": "string", "nullable": true, "enum": [ "ACTIVE", "FLAGGED", "BLOCKED", null ] }, "previous_value": { "type": "object", "nullable": true, "description": "PROFILE_UPDATED 条目的先前字段值。" }, "new_value": { "type": "object", "nullable": true, "description": "PROFILE_UPDATED 条目的新字段值。" }, "changed_fields": { "type": "array", "items": { "type": "string" }, "description": "由 PROFILE_UPDATED 条目更改的字段名称。" }, "metadata": { "type": "object", "nullable": true }, "mentioned_emails": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "该用户的活动日志和评论（状态变更、资料修改、手动备注）。" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "BusinessListItem": { "type": "object", "description": "已验证的企业。", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "Didit 为此企业分配的稳定内部 UUID。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您对此企业的唯一标识符（创建会话时传入）。未提供供应商标识符时可为 null。" }, "display_name": { "type": "string", "nullable": true, "description": "您设置的自定义显示名称" }, "legal_name": { "type": "string", "nullable": true, "description": "来自登记处或手动输入的官方法定名称" }, "registration_number": { "type": "string", "nullable": true, "description": "企业注册号或成立号" }, "country_code": { "type": "string", "nullable": true, "description": "注册国家/地区（ISO 3166-1 alpha-2，例如 `GB`、`US`）。" }, "effective_name": { "type": "string", "nullable": true, "description": "最佳可用名称：如果已设置则为 display_name，否则为 legal_name" }, "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "企业记录的生命周期状态（并非会话状态）。`ACTIVE` 为默认值，`FLAGGED` 标记为需要人工关注，`BLOCKED` 会阻止该 `vendor_data` 创建新会话。" }, "session_count": { "type": "integer", "description": "该企业的验证会话总数" }, "approved_count": { "type": "integer", "description": "已通过的会话数量" }, "declined_count": { "type": "integer", "description": "已拒绝的会话数量" }, "in_review_count": { "type": "integer", "description": "审核中的会话数量" }, "features": { "type": "object", "description": "该企业所有 KYB 会话的每项功能汇总状态。目前唯一的键为 `KYB`（公司登记核验状态）。可选值：`Approved`、`Declined`、`In Review`、`Not Finished`、`Resub Requested`。" }, "features_list": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "status": { "type": "string" } } }, "description": "与 `features` 相同的数据，为 `{feature, status}` 对象的有序数组。" }, "last_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "最近一次会话的时间戳" }, "first_session_at": { "type": "string", "format": "date-time", "nullable": true, "description": "首次会话的时间戳" }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true, "description": "最近一次活动的时间戳（状态变更、会话更新等）" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" } } }, "description": "分配给该企业的标签" }, "created_at": { "type": "string", "format": "date-time" } } }, "BusinessDetailItem": { "type": "object", "description": "完整企业详情。在 BusinessListItem 基础上扩展了元数据和 updated_at。", "allOf": [ { "$ref": "#/components/schemas/BusinessListItem" }, { "type": "object", "properties": { "metadata": { "type": "object", "description": "您附加到此企业的自定义元数据 JSON。默认为 `{}`。" }, "updated_at": { "type": "string", "format": "date-time" } } } ] }, "TransactionDetail": { "type": "object", "description": "单个交易的完整监控记录，由 `GET /v3/transactions/{transaction_id}/` 和 `POST /v3/transactions/` 返回。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Didit 稳定的交易标识符。用作后续调用的 `{transaction_id}`。" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "拥有该交易的应用的环境。`sandbox` 交易会被存储，但绝不会被评估、筛查、通知或计费，因此其空的 `rule_runs` 表示“未评估”。" }, "transaction_number": { "type": "integer", "description": "控制台中显示的应用范围内连续交易序号（例如 `4123`）。" }, "txn_id": { "type": "string", "description": "您在创建时提供的 `transaction_id`（最多 128 个字符）。每个应用唯一。" }, "txn_date": { "type": "string", "format": "date-time", "description": "交易发生的时间（来自 `transaction_at`；默认为提交时间）。" }, "zone_id": { "type": "string", "nullable": true, "description": "创建时提供的 IANA 时区标识符。" }, "transaction_type": { "type": "string", "description": "存储的顶级类别：`finance`、`kyc`、`travelRule`、`userPlatformEvent`、`gamblingBet`、`gamblingLimitChange`、`gamblingBonusChange`、`auditTrailEvent`。请注意，即使以 snake_case 提交，包含多个单词的值也会以 camelCase 形式返回。" }, "action_type": { "type": "string", "description": "类别内的子类型（例如 `deposit`、`withdrawal`、`transfer`）。未提供时默认为该类别。" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "相对于主体的方向。无论提交时的大小写如何，均以大写形式存储（输入时接受 `in`/`out`/`inbound`/`outbound`）。" }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "当前监控裁决结果。创建交易时的状态为 `APPROVED`；规则可能会同步将其更改为 `IN_REVIEW`/`DECLINED`。" }, "source": { "type": "string", "enum": [ "LIVE", "IMPORTED" ], "description": "记录的生成来源：通过 API 或 SDK 提交的交易为 `LIVE`，通过控制台导入加载的交易为 `IMPORTED`。" }, "amount": { "type": "string", "description": "作为十进制字符串的交易金额，已去除末尾零（例如 `\"1500\"`、`\"0.5\"`、`\"0.123456789012345678\"`）。最多 18 位小数。" }, "currency": { "type": "string", "description": "`amount` 的货币代码。接受任何 ISO 4217 字母代码（例如 `EUR`、`USD`、`NGN`）以及加密资产符号（例如 `BTC`）。建议使用当前流通的代码。并非每个接受的代码都有汇率：当该代码没有可用汇率时（例如 ISO 会计单位 `XSU`，或 Didit 未定价的加密资产符号），自动换算将失败，并且 `preferred_currency_amount` 将返回 null，除非请求提供了预先换算的 `amount_in_default_currency`。" }, "currency_type": { "type": "string", "nullable": true, "description": "`fiat` 或 `crypto`，与在 `currency_kind` 中提交的内容一致。" }, "amount_in_default_currency": { "type": "string", "nullable": true, "description": "您提供的预先换算金额，为去除了末尾零的十进制数字符串。" }, "default_currency_code": { "type": "string", "nullable": true }, "preferred_currency_amount": { "type": "string", "nullable": true, "description": "`amount` 在可用时折算为应用的首选货币。" }, "preferred_currency_code": { "type": "string", "nullable": true }, "payment_details": { "type": "string", "nullable": true, "description": "提交内容中的自由文本付款参考号或附言。" }, "payment_txn_id": { "type": "string", "nullable": true, "description": "来自 `payment_reference_id` 的外部支付系统参考标识（例如区块链交易哈希）。" }, "score": { "type": "integer", "description": "规则累计的风险评分（通常为 0–100）。数值越高 = 风险越大。" }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "由规则/提供商设置的分类风险严重程度（`UNKNOWN`、`LOW`、`MEDIUM`、`HIGH`、`CRITICAL`）。在设置该值之前为 `null`。" }, "decision_reason_code": { "type": "string", "nullable": true, "description": "当前 `status` 的机器可读原因。" }, "decision_reason_label": { "type": "string", "nullable": true, "description": "`decision_reason_code` 的便于人类阅读的标签。" }, "vendor_data": { "type": "string", "nullable": true, "description": "申请人 `vendor_data` 的便捷副本。" }, "metadata": { "type": "object", "description": "创建时提交的 `subject` 和 `counterparty` payload 快照。" }, "props": { "type": "object", "description": "您在创建时提供的 `custom_properties`。每个键都可以在规则条件中通过 `custom_values.` 访问。" }, "tags": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "该标签是 Didit 预设还是自定义标签。" } } }, "description": "附加到交易的标签（手动或通过规则）。" }, "parties": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "role": { "type": "string", "enum": [ "APPLICANT", "REMITTER", "BENEFICIARY", "COUNTERPARTY" ], "description": "当事方角色。创建 endpoint 会分配 `APPLICANT`（主体）和 `COUNTERPARTY`。" }, "entity_type": { "type": "string", "enum": [ "individual", "company", "external", "unhostedWallet" ] }, "kind": { "type": "string", "enum": [ "USER", "BUSINESS", "EXTERNAL" ], "description": "`USER`/`BUSINESS` 当事方通过 `vendor_data` 关联回 Didit 拥有的实体。`EXTERNAL` 当事方背后没有 Didit 实体。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您的内部用户/企业标识符。" }, "full_name": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true, "description": "来自提交的 `address.country` 的国家/地区代码（通常为 ISO 3166-1 alpha-3）。" }, "dob": { "type": "string", "format": "date", "nullable": true, "description": "来自提交的 `date_of_birth` 的出生日期。" }, "address": { "type": "object", "description": "提交的地址对象。省略时为 `{}`。" }, "institution_info": { "type": "object", "description": "提交的机构详情。省略时为 `{}`。" }, "device": { "type": "object", "description": "归一化的设备上下文，在提供了 IP 时包含 network_context 下的服务端 IP 增强数据（地理位置、VPN/数据中心标志）。", "properties": { "fingerprint": { "type": "string", "description": "唯一设备指纹。" }, "persistent_device_id": { "type": "string", "description": "跨会话的稳定设备标识符（v2 指纹架构）。" }, "user_agent": { "type": "string", "description": "浏览器或应用的 user agent 字符串。" }, "browser_family": { "type": "string", "description": "浏览器家族（例如 Chrome、Firefox、Safari）。" }, "browser_version": { "type": "string", "description": "浏览器版本字符串。" }, "platform": { "type": "string", "description": "平台标识符（web、ios、android、macos、windows、linux）。" }, "os_family": { "type": "string", "description": "操作系统系列（例如 iOS、Android、Windows）。" }, "os_version": { "type": "string", "description": "操作系统版本字符串。" }, "accept_language": { "type": "string", "description": "Accept-Language 请求头的值。" }, "session_id": { "type": "string", "description": "会话标识符（存储在元数据中）。" }, "session_age_ms": { "type": "number", "description": "会话时长（毫秒）。" }, "network_context": { "type": "object", "description": "包含 IP 地址和地理位置的网络上下文。", "properties": { "ip_address": { "type": "string", "description": "客户端 IP 地址。" }, "ip_country_code": { "type": "string", "description": "基于地理位置解析的 IP 所在国家/地区（ISO 3166-1 alpha-3）。" }, "latitude": { "type": "number", "description": "该 IP 的地理纬度。" }, "longitude": { "type": "number", "description": "该 IP 的地理经度。" } } } } }, "external_party_snapshot": { "type": "object", "nullable": true, "description": "`EXTERNAL` 当事方数据的冻结副本。当该当事方关联到 Didit 用户或企业时为 `null`。" } } }, "description": "交易当事方（申请人、交易对手）。" }, "payment_methods": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "payment_method_type": { "type": "string", "enum": [ "bank_card", "bank_account", "e_wallet", "crypto_wallet", "unhosted_wallet", "other" ] }, "label": { "type": "string", "nullable": true }, "fingerprint": { "type": "string", "nullable": true, "description": "针对 `type:account_id:issuing_country` 的 SHA-256，用于关联同一工具重复使用情况的稳定标识符。" }, "account_id": { "type": "string", "nullable": true, "description": "账户标识符（IBAN、地址、银行卡 token 等）。" }, "issuing_country": { "type": "string", "nullable": true }, "owner_kind": { "type": "string", "enum": [ "USER", "BUSINESS", "EXTERNAL" ] }, "vendor_data": { "type": "string", "nullable": true, "description": "您对所属用户/企业的标识符。" }, "owner_name": { "type": "string", "nullable": true }, "institution_info": { "type": "object" }, "details": { "type": "object", "description": "提交的原始 `payment_method` 对象。" }, "external_owner_snapshot": { "type": "object", "nullable": true }, "role": { "type": "string", "enum": [ "SOURCE", "DESTINATION", "FUNDING", "BENEFICIARY" ], "description": "此方式在交易中的使用方式。创建 endpoint 会根据交易方向分配 `SOURCE`/`DESTINATION`（出向：主体 = SOURCE；入向：主体 = DESTINATION）。" } } }, "description": "关联至交易的支付方式。" }, "documents": { "type": "array", "description": "从控制台附加到交易的文件。若无则为 `[]`。", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "uploaded_by": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_url": { "type": "string", "format": "uri", "nullable": true, "description": "短期签名下载 URL；请在需要时获取，而不是直接存储。" }, "original_filename": { "type": "string", "nullable": true }, "file_size": { "type": "integer", "nullable": true } } } } } } }, "activities": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "activity_type": { "type": "string", "description": "例如 `TRANSACTION_CREATED`、`TRANSACTION_NOTE_ADDED`、`TRANSACTION_STATUS_CHANGED`。" }, "source": { "type": "string" }, "status": { "type": "string", "nullable": true }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object" }, "occurred_at": { "type": "string", "format": "date-time" } } }, "description": "活动日志条目（创建、备注、人工审核、状态变更）。" }, "alerts": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "severity": { "type": "string", "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ] }, "status": { "type": "string", "enum": [ "OPEN", "INVESTIGATING", "AWAITING_USER", "PENDING_SAR", "SAR_FILED", "RESOLVED", "DISMISSED" ] }, "source": { "type": "string", "enum": [ "RULE", "PROVIDER", "MANUAL" ] }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" }, "due_at": { "type": "string", "format": "date-time", "nullable": true } } }, "description": "当前始终为空。未结警报是指状态为 `IN_REVIEW` 或 `AWAITING_USER` 的交易。" }, "rule_runs": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "rule": { "type": "string", "format": "uuid", "description": "已运行规则的 UUID。" }, "rule_title": { "type": "string" }, "rule_description": { "type": "string", "nullable": true }, "rule_category": { "type": "string" }, "matched": { "type": "boolean", "description": "规则条件是否与该交易匹配。仅针对匹配的规则记录运行，因此生产环境中的评估结果始终为 `true`。" }, "is_test": { "type": "boolean", "description": "当规则在 TEST 模式下运行时为 true（对状态/评分无影响）。" }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ] }, "severity": { "type": "string", "nullable": true }, "score_delta": { "type": "integer", "description": "由该规则的 `add_score` 操作添加的分数。" }, "status_target": { "type": "string", "nullable": true, "description": "由 `change_status` 操作设置的状态（如果有）。" }, "action_summary": { "type": "string", "nullable": true, "description": "规则执行的操作摘要，以 `; ` 连接（例如 `score +30; change_status:IN_REVIEW; add_tag:high_risk_country`）。组成部分包括：`score +N`、`change_status:`、`add_tag:`、`add_note`、`add_to_list`、`open_case`。当规则未执行任何操作时为 `null`。" }, "metadata": { "type": "object", "description": "评估详情：`scope_match`、`conditions[]` 和 `aggregations[]`。每个条件条目包含 `field`、`operator`、`expected_value`、从交易中读取的 `current_value`、`matched`、`group_index` 和 `group_logic`。每个聚合条目（频次 / 计数 / 求和）包含 `metric`、`field`、`operator`、`expected_value`、聚合计算得出的 `computed_value`、`window`、`filters`、`matched` 和 `sample_references`；延迟的异步聚合其 `computed_value: null` 且 `deferred: true`。嵌套条件组是一个 `conditions[]` 条目，其 `operator` 为 `any_of` 或 `all_of`，`field` 为 null，且其成员的结果位于其自身的 `conditions` 下。" }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "逐条规则的执行结果：触发了哪条规则，以及产生了怎样的评分影响。" }, "provider_results": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "provider": { "type": "string" }, "result_type": { "type": "string", "enum": [ "FIAT_MONITORING", "WALLET_SCREENING", "TRANSACTION_SCREENING", "TRAVEL_RULE", "NETWORK_GRAPH", "CUSTOM" ] }, "status": { "type": "string" }, "severity": { "type": "string", "nullable": true }, "score": { "type": "integer" }, "summary": { "type": "string", "nullable": true }, "payload": { "type": "object", "description": "原始供应商响应 payload。" }, "created_at": { "type": "string", "format": "date-time" } } }, "description": "原始供应商 payload（AML 筛查、区块链分析等）。" }, "travel_rule": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TransactionTravelRule" } ], "description": "Travel Rule 转账或核验。在提交了 `travel_rule_details` 时填充，以及在启用了 Travel Rule 且创建交易时使用了 `transaction_category: travelRule` 时填充（即使没有 `travel_rule_details`，Didit 也会自行发起信息交换）。不存在转账或核验时为 `null`。在入账转账中，交易对手的 `originator_data` 和 `beneficiary_data` 保持掩码状态（`data_masked: true`），直到钱包所有权得到确认。" }, "network_snapshot": { "type": "object", "nullable": true, "description": "规则引擎使用的相关交易/关联方图谱快照。可以随交易提交的 `network_snapshot`，也可以是 Didit 从成功的 AML 钱包筛查中构建的图谱（会替换提交的快照）。两者均不存在时为 `null`。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "nodes": { "type": "array", "items": { "type": "object" } }, "edges": { "type": "array", "items": { "type": "object" } }, "metrics": { "type": "object" } } }, "remediation": { "type": "object", "nullable": true, "description": "需要重新验证时向用户提供的补救会话。已被规范字段 `action_required` 取代；保留以向后兼容。", "properties": { "session_id": { "type": "string" }, "session_token": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "status": { "type": "string" } } }, "action_required": { "type": "object", "nullable": true, "description": "完成此交易所需的待处理终端用户操作，若无则为 null。Didit SDK 默认会自动启动该操作，并在其完成时刷新交易。共有两种变体，通过 `type` 进行区分：`verification_session`（由规则操作创建的托管验证会话）和 `wallet_ownership`（为需要钱包控制权证明的 Travel Rule 转账自动生成的钱包所有权微件会话，受 `auto_wallet_verification` Travel Rule 设置管控）。当两者均适用时，`wallet_ownership` 具有更高优先级，因为它会阻断 Travel Rule 交互。", "oneOf": [ { "$ref": "#/components/schemas/TransactionVerificationSessionAction" }, { "$ref": "#/components/schemas/TransactionWalletOwnershipAction" } ], "discriminator": { "propertyName": "type", "mapping": { "verification_session": "#/components/schemas/TransactionVerificationSessionAction", "wallet_ownership": "#/components/schemas/TransactionWalletOwnershipAction" } } }, "cost_breakdown": { "type": "object", "nullable": true, "description": "此交易的费用：`total_price` 和 `items`，每项收费一条记录，均包含 `usage_type`、`price`、`details` 和 `created_at`。对同一笔交易重新筛查会产生一个新条目。" } } }, "TravelRuleSettingsDetail": { "type": "object", "properties": { "is_enabled": { "type": "boolean", "description": "此应用上出向 `travelRule` 交易的托管 Travel Rule 协商流程是否处于活动状态。" }, "jurisdiction": { "type": "string", "maxLength": 8, "description": "您的 VASP 运营管辖区代码。默认为 `\"EU\"`。Didit 会将其映射到标记在您 Travel Rule 交易上的规管机制 `travel_rule_regime`（例如 `EU` 或欧盟成员国代码将变为 `eu`），交易规则可据此进行匹配。一旦 Didit 网络列出您的资料，其他 Didit 客户将在 VASP 目录中将其视为您的管辖区。" }, "name_matching_strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "转账达到 COMPLETED 状态前，收款人姓名必须匹配的严格程度。`CONTAINS` 接受一个名称的所有词均出现在另一个名称中的情况。" }, "confirmation_timeout_hours": { "type": "integer", "minimum": 1, "description": "AWAITING_COUNTERPARTY 状态的转账在被定期清理程序过期前可保持未确认的小时数。默认为 48。" }, "timeout_outcome": { "type": "string", "enum": [ "HOLD", "REJECT", "PROCEED" ], "description": "转账过期时对底层交易的处理方式。默认值为 HOLD。当 sunrise_policy 和 non_responsive_policy 适用且已设置时，以它们为准。" }, "threshold_amount": { "type": "string", "description": "十进制字符串，以您应用的默认货币计。触发托管交换的最低转账金额；低于该金额的转账直接解析为 NOT_APPLICABLE。Didit 会比对换算为您默认货币后的交易金额，或您发送的 `amount_in_default_currency`；当无可用的换算金额时，该阈值不适用。默认为 \"0.00\"（欧盟 TFR 不适用最低金额限制）。" }, "ownership_validation_mode": { "type": "string", "enum": [ "FULL", "SIMPLIFIED", "AUTOMATED" ], "description": "钱包所有权所需的证明力度。`FULL` 始终需要证明（签名消息、测试存款或经过审核的截图），绝不单凭终端用户的陈述。`SIMPLIFIED` 在低于 `simplified_validation_threshold` 时接受自主声明，高于该阈值时需要证明。`AUTOMATED` 允许地址簿和先前的证明自行响应，当 `allow_self_declaration` 为 true 时包含自主声明。默认值为 `AUTOMATED`。" }, "simplified_validation_threshold": { "type": "string", "description": "十进制字符串，默认为 \"0.00\"。在 `SIMPLIFIED` 模式下，低于此金额（以阈值货币计）的转账接受自主申报。未标明该货币金额的转账视为高于该金额。" }, "data_sharing_fields": { "$ref": "#/components/schemas/TravelRuleDataSharingFields" }, "matching_rules": { "$ref": "#/components/schemas/TravelRuleMatchingRules" }, "legal_name": { "type": "string", "description": "您的 VASP 法定名称。将 is_enabled 设为 true 时必填（非空）。" }, "lei": { "type": "string", "description": "您的法人实体标识符（LEI），展示在 VASP 名录中。" }, "compliance_email": { "type": "string", "format": "email", "description": "您 VASP 档案的合规联系人邮箱。只有在通过邮件发送的链接（POST /v3/travel-rule/settings/compliance-email/confirmation/）确认该地址后，Didit 网络才会列出您的档案；更改此地址需要重新确认。" }, "is_discoverable": { "type": "boolean", "description": "您的 VASP 资料是否可以在 Didit 网络中被列出：可被其他 Didit 客户在 GET /v3/travel-rule/vasps/ 中检索到，并可通过 INTERNAL 轨道触达。列出还需要拥有已上线应用、开启 Travel Rule、提供法定名称以及经过确认的合规邮箱；didit_network 会指出缺少哪些项。默认值为 true。" }, "inbound_auto_accept": { "type": "boolean", "description": "为 true 时，如果入账 TRP 问询的收款人钱包是地址簿中经过验证且姓名匹配的条目，则该问询会自动获批。为 false 时，该问询将在 ON_HOLD 中等待您通过所有权 endpoint 进行批准或拒绝。INTERNAL 轨道和充值后转账不受影响。默认为 true。" }, "allow_self_declaration": { "type": "boolean", "description": "为 true 时，钱包所有权小组件提供自我声明作为备用证明方式。默认为 true。" }, "allow_screenshot_proof": { "type": "boolean", "description": "为 true 时，钱包所有权小组件提供屏幕截图上传作为所有权证明方式。默认为 true。" }, "auto_wallet_verification": { "type": "boolean", "description": "为 true 时，提交需要终端用户提供钱包控制证明的出账 Travel Rule 转账会自动生成绑定到该交易的钱包所有权小组件会话，并将其放入交易的 action_required 块中。默认为 true。" }, "vasp_attribution_enabled": { "type": "boolean", "description": "为 true 时，任何无法由任何轨道路由的出账 Travel Rule 转账都将通过区块链分析进行归因：目标钱包将解析为其所属的 VASP，该实体将记录在转账和 VASP 目录中，并且轨道将使用归因名称重新运行一次。默认为 true。" }, "counterparty_screening_enabled": { "type": "boolean", "description": "对交易对手 VASP 进行可选的制裁和负面新闻筛查，按企业 AML 筛查价格按次计费。开启后，Didit 会筛查出站交易所触达的交易对手（复用 30 天内的筛查结果），您也可以使用 POST /v3/travel-rule/vasps/{vasp_id}/screening/ 对其进行筛查。默认为 false：不进行任何筛查或计费。" }, "sunrise_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "当交易对手是 sunrise_jurisdictions 中尚未强制实施 Travel Rule 的司法管辖区目录条目时，过期转账对其交易的处理方式：HOLD 将其移至审核，REJECT 将其拒绝，PROCEED 保持其状态不变。留空（默认值）则遵循 timeout_outcome。在 non_responsive_policy 之前生效。" }, "sunrise_jurisdictions": { "type": "array", "items": { "type": "string" }, "readOnly": true, "description": "只读。Didit 视为处于 Travel Rule 日出期的国家/地区（ISO 3166 alpha-2），在此期间适用 sunrise_policy。目前包括 CO、KH 和 VN。任何其他司法管辖区，以及为空或未知的管辖区，均遵循 timeout_outcome。" }, "non_responsive_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "当交易对手是响应状态为 UNRESPONSIVE 的目录条目时，过期转账对其交易的处理方式：HOLD、REJECT 或 PROCEED（与 timeout_outcome 相同）。留空（默认值）则遵循 timeout_outcome。当两者均符合条件时，sunrise_policy 优先适用。" }, "travel_address": { "type": "string", "description": "只读。您所在 VASP 专属的 Travel Address，即其他 VASP 用于联系您的编码入站 TRP 查询 endpoint。当 `is_enabled` 为 false 时为空。" }, "disabled_networks": { "type": "array", "items": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "description": "已选择退出平台成员资格的网络。这不会停用您已关联的自有成员资格，也不会配置不可用的网络。", "default": [] }, "networks": { "type": "object", "readOnly": true, "description": "按网络列出：此应用将如何发送以及为何无法发送。默认不包含任何网络（包括 GTR）：网络可通过您自己已连接的成员资格访问，或者在 Didit 在该网络上的成员资格生效且您自己在该网络上的参与方处于活跃状态后，通过 Didit 的成员资格访问。非实时健康状态或投递检查。", "properties": { "gtr": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "trust": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "verifyvasp": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "sygna": { "$ref": "#/components/schemas/TravelRuleNetworkState" } } }, "didit_network": { "type": "object", "readOnly": true, "description": "Didit 网络是否收录了您的 VASP 资料（以便其他 Didit 客户能在名录中找到并能通过 INTERNAL 轨道联系到它），以及其目前仍欠缺的各项条件。", "properties": { "listed": { "type": "boolean" }, "missing": { "type": "array", "items": { "type": "string", "enum": [ "travel_rule_off", "sandbox_application", "not_discoverable", "legal_name_missing", "compliance_email_missing", "compliance_email_unconfirmed", "excluded_by_staff", "internal_organization" ] }, "description": "列出时为空。compliance_email_unconfirmed：使用 POST /v3/travel-rule/settings/compliance-email/confirmation/ 发送确认邮件并打开邮件中的链接。excluded_by_staff：Didit 已将该应用标记为测试、演示或内部应用。" }, "compliance_email_confirmed": { "type": "boolean", "description": "当前的 compliance_email 是否已通过邮件中的链接确认。" } } } } }, "TravelRuleSettingsUpdate": { "type": "object", "properties": { "is_enabled": { "type": "boolean" }, "legal_name": { "type": "string", "maxLength": 255 }, "lei": { "type": "string", "maxLength": 20 }, "jurisdiction": { "type": "string", "maxLength": 8 }, "name_matching_strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "`CONTAINS` 接受一个名字中的所有词语均出现在另一个名字中。" }, "confirmation_timeout_hours": { "type": "integer", "minimum": 1 }, "timeout_outcome": { "type": "string", "enum": [ "HOLD", "REJECT", "PROCEED" ] }, "compliance_email": { "type": "string", "format": "email", "description": "您 VASP 档案的合规联系人邮箱。只有在通过邮件发送的链接（POST /v3/travel-rule/settings/compliance-email/confirmation/）确认该地址后，Didit 网络才会列出您的档案；更改此地址需要重新确认。" }, "is_discoverable": { "type": "boolean", "description": "您的 VASP 资料是否可以在 Didit 网络中被列出：可被其他 Didit 客户在 GET /v3/travel-rule/vasps/ 中检索到，并可通过 INTERNAL 轨道触达。列出还需要拥有已上线应用、开启 Travel Rule、提供法定名称以及经过确认的合规邮箱；didit_network 会指出缺少哪些项。默认值为 true。" }, "threshold_amount": { "type": "string", "description": "十进制字符串，大于或等于零，以您应用的默认货币计。触发托管交换的最低转账金额。" }, "ownership_validation_mode": { "type": "string", "enum": [ "FULL", "SIMPLIFIED", "AUTOMATED" ], "description": "请参阅同名的响应字段。" }, "simplified_validation_threshold": { "type": "string", "description": "十进制字符串，0 或更大。" }, "data_sharing_fields": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleDataSharingFields" } ], "description": "按实体类型合并：省略的实体类型将保留其当前选项。如果所选选项无法满足您所在 `jurisdiction` 制度（欧盟 TFR 或 FATF 第 16 号建议）的汇款人义务（包括空列表），将被拒绝并返回 `400`。" }, "matching_rules": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleMatchingRules" } ], "description": "按主体类型以及其内部字段进行合并。若字段未被该主体类型进行比对（例如针对 `company` 的 `date_of_birth`），则会被拒绝并返回 `400`。" }, "inbound_auto_accept": { "type": "boolean" }, "allow_self_declaration": { "type": "boolean" }, "allow_screenshot_proof": { "type": "boolean", "description": "为 true 时，钱包所有权小组件提供屏幕截图上传作为所有权证明方式。默认为 true。" }, "auto_wallet_verification": { "type": "boolean" }, "vasp_attribution_enabled": { "type": "boolean" }, "counterparty_screening_enabled": { "type": "boolean", "description": "对交易对手 VASP 进行可选的制裁和负面新闻筛查，按企业 AML 筛查价格按次计费。开启后，Didit 会筛查出站交易所触达的交易对手（复用 30 天内的筛查结果），您也可以使用 POST /v3/travel-rule/vasps/{vasp_id}/screening/ 对其进行筛查。默认为 false：不进行任何筛查或计费。" }, "sunrise_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "HOLD、REJECT、PROCEED，或为空以遵循 timeout_outcome。参见同名的响应字段。" }, "non_responsive_policy": { "type": "string", "enum": [ "", "HOLD", "REJECT", "PROCEED" ], "description": "HOLD、REJECT、PROCEED，或为空以遵循 timeout_outcome。参见同名的响应字段。" }, "disabled_networks": { "type": "array", "items": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "description": "已选择退出平台成员资格的网络。这不会停用您已关联的自有成员资格，也不会配置不可用的网络。", "default": [] } }, "description": "所有字段均为可选；PUT 执行部分更新。" }, "WalletAddressEntry": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "address": { "type": "string", "description": "钱包地址；仅通过哈希导入的条目为 `\"\"`。在每个应用、链和 memo 维度内唯一，比对地址时不区分大小写。删除条目后，您可以再次注册相同的地址。" }, "chain": { "type": "string", "description": "地址的区块链网络 token，例如 `ETH` 或 `BTC`。当 Didit 路由或登记转账时，它会按钱包地址进行地址簿条目匹配；如果转账包含区块链网络，还会对此值进行不区分大小写的匹配。转账的区块链网络为 `beneficiary_data.chain`，如果您未发送，则从交易的加密区块链网络或货币符号（例如 `ETH`）中填充，或是存款后登记的 `chain`，因此请在所有地方使用相同的 token。区块链网络为空的条目可匹配任意网络。在比特币上登记的 Lightning 收款人（节点 ID 或 Lightning Address）以小写形式存储在 `LIGHTNING` 下，并在该处匹配 Lightning 转账。无论您发送何种拼写，已知区块链网络均存储在同一个标准标识符下：\"ethereum\"、\"Ethereum\" 和 \"ERC20\" 均存储为 ETH，\"BNB Smart Chain\" 和 \"BEP20\" 存储为 BNB，\"tron\" 存储为 TRX。未知区块链网络名称将按原样保留。" }, "holder_vendor_data": { "type": "string", "description": "您为持有者指定的内部标识符。" }, "holder_name": { "type": "string", "description": "钱包持有者姓名，用于收款人姓名比对。" }, "entity_type": { "type": "string", "description": "自由格式文本，默认为 \"individual\"。" }, "is_ownership_verified": { "type": "boolean", "description": "只读。此地址的所有权是否已得到证明。" }, "created_at": { "type": "string", "format": "date-time" }, "travel_address": { "type": "string", "description": "此钱包对应的交易对手 VASP 的 Travel Address（如果已知）。允许 Didit 针对 TRP 支持的资产（指定网络上的 BTC、ETH 和 USDC），通过 TRP 渠道路由此收款人的转账。" }, "address_hash": { "type": "string", "description": "只读。小写地址的 SHA-256，为小写十六进制格式。仅通过哈希导入的条目将基于此进行匹配。" }, "memo": { "type": "string", "description": "在 memo 网络（XRP、XLM、EOS、ATOM、HBAR）上作为钱包一部分的目标标签或 memo；整个地址为 `\"\"`。带有 memo 的条目仅匹配指定该 memo 的转账；不带 memo 的条目匹配整个地址。" }, "receiving_travel_address": { "type": "string", "readOnly": true, "description": "此钱包专属的 Travel Address：将其提供给发送方 VASP，以便其 TRP 查询能够指定此钱包。如果钱包被记录为另一个 VASP 的钱包、Travel Rule 未启用或在您的 VASP 资料保存之前，此字段为空。" } } }, "WalletAddressEntryCreate": { "type": "object", "required": [ "address" ], "properties": { "address": { "type": "string", "maxLength": 128, "description": "钱包地址。XRP X-address 会以其经典地址和标签的形式存储，因此可以匹配指定了任一形式的转账。" }, "chain": { "type": "string", "maxLength": 32, "description": "地址的链 token，例如 `ETH` 或 `BTC`。当 Didit 路由或登记转账时，会在地址上匹配地址簿条目；当转账附带链信息时，也会在此值上进行不区分大小写的匹配。转账的链为 `beneficiary_data.chain`，如果您未传入该值，则会根据交易的加密货币链或货币符号（例如 `ETH`）填充，或采用存款后登记的 `chain`，因此请在所有位置使用相同的 token。链为空的条目可匹配任意链。无论您传入何种拼写，已知链均按单一规范标识符存储：“ethereum”、“Ethereum”和“ERC20”均存储为 ETH，“BNB Smart Chain”和“BEP20”存储为 BNB，“tron”存储为 TRX。未知的链名称将按原样保留。" }, "holder_vendor_data": { "type": "string", "maxLength": 255 }, "holder_name": { "type": "string", "maxLength": 255 }, "entity_type": { "type": "string", "default": "individual", "maxLength": 16 }, "self_declared": { "type": "boolean", "default": false, "description": "仅可写入。当为 true 时，创建的条目已通过 SELF_DECLARATION 证明完成股权结构核验。在您的 Travel Rule 设置中 `allow_self_declaration` 未开启时返回 400。" }, "travel_address": { "type": "string", "description": "可选。交易对手 VASP 针对此钱包的 Travel Address，用于为 TRP 支持的资产（指定网络上的 BTC、ETH 和 USDC）启用 TRP 路由。无效的 Travel Address 将返回 400。", "maxLength": 512 }, "memo": { "type": "string", "maxLength": 256, "description": "可选。作为钱包一部分的目标标签（destination tag）或 memo。XRP：目标标签，0 到 4294967295 之间的整数（支持 JSON 数字格式）。XLM：最多 28 字节的文本 memo、64 位 id 或 32 字节的十六进制哈希。EOS：最多 256 字节。ATOM：最多 256 个字符。HBAR：最多 100 字节。Bitcoin、EVM、Solana、Tron、Litecoin、Bitcoin Cash、Dogecoin 和 Lightning 钱包不接受 memo：传入 memo 将返回 `400`。别名：`destinationTag` 或 `destination_tag`。" } } }, "WalletAddressEntryUpdate": { "type": "object", "properties": { "holder_name": { "type": "string", "maxLength": 255 }, "holder_vendor_data": { "type": "string", "maxLength": 255 }, "entity_type": { "type": "string", "maxLength": 16 }, "travel_address": { "type": "string", "maxLength": 512 } }, "description": "PATCH 为部分更新；响应仅回显 holder_name、holder_vendor_data、entity_type、travel_address、receiving_travel_address、label 和 owner_type。" }, "TravelRuleTransferDetail": { "type": "object", "description": "所有权确认以及完成/取消 endpoint 返回的完整转账对象。当入站转账的钱包所有权未确认时，交易对手的 `originator_data` 和 `beneficiary_data` 会被掩码返回（保留每个单词的首字母；钱包、链以及 VASP 路由保持可读），且 `data_masked` 为 true。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "AWAITING_COUNTERPARTY", "ON_HOLD", "COMPLETED", "FINISHED", "CANCELLED", "EXPIRED", "COUNTERPARTY_MISMATCHED_DATA", "COUNTERPARTY_VASP_NOT_FOUND", "COUNTERPARTY_VASP_NOT_REACHABLE", "UNCONFIRMED_OWNERSHIP", "COUNTERPARTY_VASP_GENERAL_DECLINE", "NOT_ENOUGH_COUNTERPARTY_DATA", "NOT_APPLICABLE" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "rail": { "type": "string", "nullable": true, "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "TEST_VASP", null ], "description": "转账路由所使用的通道，如果未选择通道（例如低于阈值、交易对手为自托管钱包、充值后登记或无触达的交易对手），则为 null。INTERNAL 表示双方均为 Didit 应用；EMAIL 表示通过电子邮件发送的提取链接触达交易对手。TEST_VASP 表示由 Didit Test VASP 响应沙盒转账。在 GTR、VERIFYVASP 和 SYGNA 上，Didit 会从网络响应中读取交易对手的回答，或每 5 分钟轮询一次。TRUST 仅支持发送，因此 TRUST 转账将一直保持 AWAITING_COUNTERPARTY 状态直至过期。网络通道仅在您已关联该网络自身会员资格时使用。它在交易创建返回后选定，因此在该响应中为 null。" }, "protocol": { "type": "string", "nullable": true }, "ivms_version": { "type": "string", "example": "ivms101.2023" }, "required": { "type": "boolean" }, "ownership_confirmed": { "type": "boolean", "nullable": true }, "deadline_at": { "type": "string", "format": "date-time", "nullable": true }, "timeline": { "type": "array", "items": { "type": "object", "properties": { "status": { "type": "string" }, "at": { "type": "string", "format": "date-time" }, "detail": { "type": "string" }, "name_match": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleNameMatch" } ], "nullable": true, "description": "该条目决定的姓名比对结果，位于 `detail` 旁边。未比对姓名的条目中不存在该字段。" }, "reason": { "type": "string", "description": "仅在投递失败导致的状态流转条目中存在：`email_undeliverable` 或 `delivery_failed`，即转账的 `reason` 所报告的值。" } } } }, "counterparty_vasp": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "lei": { "type": "string" }, "dd_score": { "type": "integer", "description": "尽职调查评分，范围为 0 到 100，分数越高越好。分值范围与 VASP 名录相同。" }, "dd_score_breakdown": { "type": "object", "description": "对 dd_score 的各组件贡献度，每个组件一个对象（对应 VASP 目录中的 jurisdiction、verification、protocol、lei、history、essentials、responsiveness），每个组件均包含 {points, max, reason, detail}。在交易对手完成评估前为 {}。", "additionalProperties": { "type": "object", "properties": { "points": { "type": "number", "description": "为该组件分配的点数。" }, "max": { "type": "integer", "description": "该组件可赋予的最大分值。" }, "reason": { "type": "string", "description": "组件判定结果的机器可读代码。" }, "detail": { "type": "string", "description": "易于阅读的积分授予原因。" } } } }, "dd_assessed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "尽职调查评估上次运行的时间。在对交易对手进行评估之前为 Null。" } } }, "originator_data": { "type": "object", "description": "汇款人方。对于入账转账，在所有权确认之前，交易对手的值将被掩码遮盖。" }, "beneficiary_data": { "type": "object", "description": "收款人方。对于入账转账，在确认所有权之前，交易对手的值将被遮蔽。" }, "name_match": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleNameMatch" } ], "nullable": true, "description": "决定转账的姓名比对结果，在运行比对前为 null。在当事方被脱敏期间，以及在 INTERNAL 交易另一方客户的副本上，`transfer_name`、`compared_name`、`matched_names` 和 `mismatched_names` 将被隐藏。`score` 和 `matched` 可能会不一致：`matched` 遵循严格程度规则，`score` 则是两个全名之间的相似度。" }, "data_match": { "$ref": "#/components/schemas/TravelRuleDataMatch" }, "mismatched_fields": { "type": "array", "items": { "type": "string" }, "description": "`data_match.mismatched_fields` 的快捷方式。无差异时为空。" }, "data_unmasked": { "$ref": "#/components/schemas/TravelRuleDataUnmasked" }, "data_masked": { "type": "boolean", "description": "在此响应中交易对手的个人数据被遮蔽时为 True。" }, "created_at": { "type": "string", "format": "date-time" }, "delivery": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TravelRuleDelivery" } ], "description": "此转账应发送给对方的最新消息所处的状态。当转账从未需要发送消息时（例如低于 `threshold_amount`、声明的自托管钱包或 sunrise 注册）为 null。" }, "discovery": { "type": "array", "description": "Didit 查找交易对手的方式，每个运行的步骤对应一个条目。未运行发现流程时为空，例如对于入站转账。", "items": { "$ref": "#/components/schemas/TravelRuleDiscoveryStep" } }, "reason": { "type": "string", "description": "`COUNTERPARTY_VASP_NOT_FOUND` 或 `COUNTERPARTY_VASP_NOT_REACHABLE` 转账受阻的原因；任何其他状态下为 `\"\"`。首先由失败的投递决定（仅适用于 `COUNTERPARTY_VASP_NOT_REACHABLE`）：`email_undeliverable`（邮件服务商拒绝了合规邮件，且没有可尝试的地址：发送时、发送提醒时或后续报告为永久退信）或 `delivery_failed`（负责投递的通道彻底失败：网络通道拒绝了消息或重试次数耗尽、`TRP` 身份主机未应答，或交易对手的 `TRP` 主机不接受查询）。否则由 `discovery` 追踪记录决定：`awaiting_end_user`（没有任何步骤指定 Didit 可触达的交易对手）、`directory_match_no_route`（某步骤指定了名录中的 VASP，但该 VASP 没有可用路由）、`picked_member_without_proven_wallet`（终端用户选择的 Didit 客户尚未证明对该钱包的控制权），或者在追踪记录未提供其他原因时的 `no_directory_match`。重新发送后转账会继续推进，因此该原因将被清除。参见[转账受阻的原因](/zh/transaction-monitoring/travel-rule#为什么转账会卡住)。" }, "next_actions": { "type": "array", "description": "推进转账的操作；除 `COUNTERPARTY_VASP_NOT_FOUND` 或 `COUNTERPARTY_VASP_NOT_REACHABLE` 之外的任何状态均返回 `[]`。`email_undeliverable` 提供 `update_compliance_email`，然后提供 `resend`。`delivery_failed` 提供 `resend`。发现原因提供 `select_counterparty_vasp`、`declare_self_hosted`、`add_vasp_hint` 和 `resend`。", "items": { "$ref": "#/components/schemas/TravelRuleNextAction" } }, "chain_details": { "$ref": "#/components/schemas/TravelRuleChainDetails" } } }, "TravelRuleOwnershipConfirmRequest": { "type": "object", "required": [ "confirmed" ], "properties": { "confirmed": { "type": "boolean", "description": "为 true 表示确认所有权，为 false 表示否认所有权。" }, "wallet_address": { "type": "string", "default": "", "description": "入站 TRP 转账：您批准时 Didit 返回给汇款方 VASP 的付款地址。默认优先使用匹配的地址簿条目中的地址，其次使用 beneficiary_data.wallet_address。对于未指明交易对手钱包的已申报自托管钱包转账，则为您已核实所有权的钱包；若缺少该钱包，请求将被拒绝并返回 400。对其他转账忽略此项。" } } }, "TravelRuleTransferPatchRequest": { "type": "object", "description": "请恰好提供以下之一：payment_txn_id（完成）、action=cancel、action=resend、带有 compliance_email 的 action=update_compliance_email、带有 wallet_address 的 action=update_originator_wallet，或带有 beneficiary_vasp 的 action=beneficiary_vasp。", "properties": { "payment_txn_id": { "type": "string", "description": "链上交易哈希。要求该转账为处于 COMPLETED 状态的出向转账。" }, "action": { "type": "string", "enum": [ "cancel", "resend", "update_compliance_email", "update_originator_wallet", "beneficiary_vasp" ], "description": "\"cancel\" 取消非终态转账。\"resend\" 对停留在 COUNTERPARTY_VASP_NOT_FOUND、COUNTERPARTY_VASP_NOT_REACHABLE 或 NOT_ENOUGH_COUNTERPARTY_DATA 状态的出向转账重新运行路由。\"update_compliance_email\" 替换该请求所发送到的合规邮箱（适用于处于这三种状态之一的出向转账）；之后发送 \"resend\"。\"update_originator_wallet\" 记录资金实际转出的钱包（`wallet_address`、`memo`）。\"beneficiary_vasp\" 由您自行指定处于上述状态之一的出向转账的交易对手 VASP（需要 `beneficiary_vasp`）：请求将被路由至该 VASP 并重新发送。" }, "compliance_email": { "type": "string", "format": "email", "maxLength": 254, "description": "当 `action: update_compliance_email` 时必填。保存为该笔转账的 `beneficiary_data.counterparty_vasp_email`：仅归属于该笔转账，不加入任何名录条目或联系人列表。" }, "wallet_address": { "type": "string", "maxLength": 128, "description": "配合 `action: update_originator_wallet`：资金流出的钱包。当转账的 UTXO 输入已知时，必须是其中之一。" }, "memo": { "type": "string", "maxLength": 256, "description": "配合 `action: update_originator_wallet`：该钱包在 memo 网络上的 memo 或 tag。可选。" }, "beneficiary_vasp": { "type": "string", "format": "uuid", "description": "当 action=beneficiary_vasp 时必填：来自 `GET /v3/travel-rule/vasps/` 的名录 VASP 的 `id`。您的选择优先于所有自动发现步骤，且绝不会被覆盖。" } } }, "VaspDirectoryEntry": { "type": "object", "description": "名录中的 VASP 或 Didit 网络的成员，包含您的应用与其建立的路由。仅当客户的应用处于生产环境、启用了 Travel Rule、其资料可被发现、拥有法定名称及已确认的合规邮箱，且 Didit 未将该应用标记为测试、演示或内部应用时，该客户才是 Didit 网络的成员。每一行还包含共享的尽职调查评估（dd_score、risk_level、responsiveness、essential_checks）以及您应用自身的决策、主体筛查和问卷，其他任何客户都无法查看这些内容。", "properties": { "id": { "type": "string", "format": "uuid", "description": "条目 ID，用于 GET /v3/travel-rule/vasps/{vasp_id}/。" }, "kind": { "type": "string", "enum": [ "directory", "didit" ], "description": "directory 表示共享目录条目；didit 表示 Didit 网络成员。" }, "name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string", "description": "数据源所提供的 ISO 3166 国家/地区代码。" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "VASP 的 Web 域名。对于 Didit 网络成员始终为空。" }, "reachable": { "type": "boolean", "description": "您的应用是否有通往该 VASP 或其某个品牌实体的可用路由。对于 Didit 网络成员始终为 true，但在沙盒应用中除外（沙盒应用中每行均为 false）。" }, "aliases": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "kind": { "type": "string", "enum": [ "trading_name", "other_legal_name", "network_name", "attribution", "merged", "staff" ], "description": "trading_name、other_legal_name（来自全球 LEI 登记簿）、network_name（Travel Rule 网络上的名称）、attribution（区块链分析机构为该 VASP 钱包标注的实体名称）、merged（合并到此项的重复条目的名称）或 staff。" } } }, "description": "用于查找该 VASP 的其他名称。" }, "networks": { "type": "array", "items": { "type": "object", "description": "该 VASP 在 Travel Rule 网络成员名录中的当前条目。TRISA 条目说明了该 VASP 在 TRISA 上的身份；Didit 没有 TRISA 渠道，因此它绝不是一个路由。", "properties": { "network": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA", "TRISA" ] }, "code": { "type": "string", "description": "该 VASP 在该网络上的标识符。" }, "listed_name": { "type": "string", "description": "网络列出该 VASP 所使用的名称。" }, "country": { "type": "string", "description": "网络列出的国家/地区（若有提供）。" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Didit 工作人员验证该条目的时间。对于从公共目录读取的条目，该值为 null。" }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true, "description": "数据源最后一次显示该收录信息的时间。数据源连续三周未显示的收录信息将被移除。" }, "source": { "type": "string", "enum": [ "trisa_directory", "staff" ], "description": "词条的来源：公开的 TRISA 目录，或 Didit 工作人员。" } } } }, "routes": { "type": "array", "items": { "type": "object", "description": "您的应用向该 VASP 传递 Travel Rule 数据的一种方式，按调度尝试的顺序排列。网络路由需要该网络上的成员资格：您自己的（在 Marketplace 中连接）或 Didit 拥有的（一旦 Didit 拥有）。如果没有它，该路由将被列为不可用并附带原因，绝不会作为联系该 VASP 的方式。", "properties": { "rail": { "type": "string", "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL" ] }, "status": { "type": "string", "enum": [ "available", "unavailable" ] }, "reason": { "type": "string", "enum": [ "", "no_membership", "network_switched_off", "sandbox_application" ], "description": "不可用路由无法使用的原因：no_membership（您和 Didit 均未加入该网络）、network_switched_off（您在设置中关闭了该网络）或 sandbox_application（沙盒应用仅发送至 Didit Test VASP，因此没有可用的路由）。路由可用时为空。" }, "via": { "type": "string", "enum": [ "", "own_membership", "didit_membership", "directory", "contact", "didit_network" ], "description": "可用路由的达成方式：网络轨道的 own_membership 或 didit_membership，经目录验证的 TRP endpoint 的 directory，EMAIL 轨道的 contact，Didit 网络成员的 didit_network。当路由不可用时为空。" } } } }, "umbrella": { "type": "object", "nullable": true, "description": "该条目所属受监管实体的品牌。不属于任何受监管实体时为 null。", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "entities": { "type": "array", "items": { "type": "object", "description": "品牌的受监管实体：接收转账的法定实体。", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string" }, "reachable": { "type": "boolean", "description": "您的应用是否有通往该目标的可用路由。" } } }, "description": "对于品牌，指接收其转账的受监管实体。指定该品牌的转账会路由至其声明管辖区内可达的实体（beneficiary_data.counterparty_vasp_jurisdiction），否则路由至与目标钱包关联的、由区块链分析归因确定的实体，未声明管辖区时则路由至唯一可达的实体。若两个实体匹配度相同，系统绝不会进行主观推测。" }, "contacts": { "type": "array", "items": { "type": "object", "description": "EMAIL 渠道可以写入的合规联系人。", "properties": { "id": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "source": { "type": "string", "enum": [ "staff", "application", "learned" ], "description": "staff：由 Didit 维护；application：由您的应用添加；learned：通过其响应链接回复了 Travel Rule 请求的地址。" }, "scope": { "type": "string", "enum": [ "platform", "application" ], "description": "平台联系人用于所有 Didit 客户的转账；应用联系人仅对您的应用私有，应用只能查看自己的联系人。" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "该地址的人员回复请求的时间。尚未回复时为 Null。" } } }, "description": "平台针对该 VASP 的联系方式以及您应用自身的联系方式。" }, "dd_status": { "type": "string", "enum": [ "NOT_STARTED", "IN_PROGRESS", "COMPLETED", "REJECTED" ], "description": "该条目的 Didit 验证状态，由 dd_score 的验证组件进行评分。对于 Didit 网络成员，始终为 COMPLETED。" }, "dd_score": { "type": "integer", "nullable": true, "minimum": 0, "maximum": 100, "description": "名录条目的共享尽职调查评分，范围为 0 到 100，分数越高越安全（参见 dd_score_semantic）：即 dd_score_breakdown 中各项分数的总和。Didit 网络成员不进行评分，该值为 null。尚未评估的条目（dd_assessed_at 为 null）显示为 0 且 risk_level 为空，因此请读取 risk_level 而不是原始分数。" }, "reachable_rails": { "type": "array", "items": { "type": "string", "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL" ] }, "description": "条目上记录的 Rails。请读取路由以了解您的应用当前可以使用的内容。" }, "is_didit_customer": { "type": "boolean", "description": "对于 Didit 网络的成员（其 dd_status 始终为 COMPLETED，dd_score 为 null 且 risk_level 为空）以及与 Didit 客户关联的目录条目，该值为 true。" }, "dd_score_breakdown": { "type": "object", "description": "dd_score 的每个组成部分对应一个对象。组成部分、其权重（最大值）及其原因代码：jurisdiction, 25 (jurisdiction_not_high_risk, jurisdiction_high_risk, jurisdiction_unknown)；verification, 15 (dd_status_completed, dd_status_in_progress, dd_status_not_started, dd_status_rejected)；protocol, 15 (native_rail, email_only, no_rail)；lei, 10 (lei_valid, lei_missing)；history, 10 (history, no_history)；essentials, 15 (essential_checks, no_essential_checks)；responsiveness, 10 (responsive, unresponsive, responsiveness_unknown)。对于 Didit 网络成员，该字段为空。", "additionalProperties": { "type": "object", "properties": { "points": { "type": "number", "description": "该组件贡献的点数，保留一位小数。" }, "max": { "type": "integer", "description": "组件的权重：其最多能贡献的分数。" }, "reason": { "type": "string", "description": "组件判定结果的机器可读代码。" }, "detail": { "type": "string", "description": "单行英文说明。" } } } }, "dd_assessed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "上次计算 dd_score、risk_level 和 responsiveness 的时间：在与该条目的交互完成、结束、过期、不匹配或被拒绝后，在 Didit 刷新或整理该条目时，以及在每周目录刷新时。对于 Didit 网络成员为 Null。" }, "dd_score_semantic": { "type": "string", "enum": [ "higher_is_safer" ], "description": "dd_score 的取向：始终为 higher_is_safer。" }, "risk_level": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH", "" ], "description": "dd_score 所在的区间：LOW（70 或以上）、MEDIUM（40 至 69）或 HIGH（低于 40）。对于 Didit 网络成员以及尚未评估的条目为空。可使用 risk 对其进行过滤。您自己标记的筛查绝不会更改此共享值：而是在您的规则中将 counterparty_risk_level 置为 HIGH。" }, "responsiveness": { "type": "object", "description": "该 VASP 是否响应 Travel Rule 请求：过去 90 天内 Didit 客户向其发起的请求中得到响应的比例。仅计入通过网络或协议轨道发送的请求，或通过电子邮件发送至共享地址（词条的合规邮箱或平台联系人）的请求；发送至客户手动输入的地址或客户私人联系人的请求一律不计入。过期的请求视为未响应；完成的交换、拒绝或数据不匹配均视为已响应；取消的请求或无法连通的轨道两者皆非。对于 Didit 网络成员，始终为 UNKNOWN 且计数为零。", "properties": { "status": { "type": "string", "enum": [ "RESPONSIVE", "UNRESPONSIVE", "UNKNOWN" ], "description": "在时间窗口内已决策请求少于 5 个时为 UNKNOWN；其中得到应答的请求少于百分之十时为 UNRESPONSIVE；否则为 RESPONSIVE。" }, "answered": { "type": "integer", "description": "窗口期内 VASP 已回复的已决策请求。" }, "total": { "type": "integer", "description": "窗口期内的已决策请求：已回复加上已过期。" }, "computed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "essential_checks": { "type": "object", "description": "目录条目的基本核验报告，仅根据平台验证的来源生成：注册（官方登记簿列出了该 VASP：欧盟临时 MiCA 登记簿、公共 TRISA 目录或全球 LEI 登记簿）、许可证（MiCA 授权已有记录且当前有效）、域名（条目的域名与其 TRP endpoint 或其登记簿提供的网站相匹配）和 LEI（其 LEI 记录处于活跃状态、已签发且与条目的名称和国家/地区一致）。dd_score 的基本核验部分是通过的已判定检查项所占的比例。在每周目录刷新首次检查该条目之前为空，并且对于 Didit 网络成员始终为空。", "properties": { "level": { "type": "string", "enum": [ "essential" ] }, "checked_at": { "type": "string", "format": "date-time" }, "checks": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "enum": [ "registration", "licence", "domain", "lei" ] }, "status": { "type": "string", "enum": [ "pass", "fail", "unknown" ], "description": "当记录中没有任何来源可以对该检查作出判定时为 unknown。" }, "reason": { "type": "string", "description": "判定结果的机器可读代码。" }, "detail": { "type": "string", "description": "单行英文说明。" } } } }, "passed": { "type": "integer" }, "failed": { "type": "integer" }, "unknown": { "type": "integer" }, "total": { "type": "integer" } } }, "decision": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyDecision" } ], "nullable": true, "description": "您的应用针对该 VASP 的决策，或者对于未单独设置决策的实体而言为其品牌的决策（inherited_from 会指明品牌名称）。无决策时为 null。仅对您的应用私有。" }, "entity_screening": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyScreening" } ], "nullable": true, "description": "您的应用针对该 VASP 最新的制裁与负面新闻筛查记录。若您从未筛查过该 VASP 则为 null。仅对您的应用私有。" }, "questionnaires": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaire" }, "description": "您的应用与该 VASP 之间的尽职调查问卷，按最新优先排序。仅对您的应用私有。" } }, "example": { "id": "0d6f3c2a-6a1e-4c55-9a39-1f2b0c7d8e91", "kind": "directory", "name": "Example Counterparty VASP", "lei": "529900EXAMPLECPTY001", "jurisdiction": "DE", "domains": [ "counterparty.example" ], "reachable": true, "aliases": [ { "name": "Example Counterparty", "kind": "trading_name" } ], "networks": [ { "network": "GTR", "code": "EXAMPLE01", "listed_name": "Example Counterparty VASP", "country": "DE", "verified_at": "2026-10-12T09:30:00Z", "last_seen_at": "2026-10-12T09:30:00Z", "source": "staff" } ], "routes": [ { "rail": "GTR", "status": "unavailable", "reason": "no_membership", "via": "" }, { "rail": "EMAIL", "status": "available", "reason": "", "via": "contact" } ], "umbrella": null, "entities": [], "contacts": [ { "id": "6c1f9b8e-2d4a-4f7e-8b3c-5a9d0e1f2a3b", "email": "travelrule@counterparty.example", "name": "Travel Rule desk", "source": "staff", "scope": "platform", "verified_at": null } ], "dd_status": "NOT_STARTED", "dd_score": 62, "dd_score_breakdown": { "jurisdiction": { "points": 25.0, "max": 25, "reason": "jurisdiction_not_high_risk", "detail": "DEU is not on the high-risk jurisdiction list" }, "verification": { "points": 3.8, "max": 15, "reason": "dd_status_not_started", "detail": "due diligence status NOT_STARTED" }, "protocol": { "points": 6.0, "max": 15, "reason": "email_only", "detail": "reachable over the email fallback only" }, "lei": { "points": 10.0, "max": 10, "reason": "lei_valid", "detail": "valid LEI on record" }, "history": { "points": 5.0, "max": 10, "reason": "no_history", "detail": "no exchange history" }, "essentials": { "points": 7.5, "max": 15, "reason": "no_essential_checks", "detail": "no decided essential check yet" }, "responsiveness": { "points": 5.0, "max": 10, "reason": "responsiveness_unknown", "detail": "0 decided recent requests, too few to judge" } }, "dd_assessed_at": "2026-10-12T09:30:00Z", "dd_score_semantic": "higher_is_safer", "risk_level": "MEDIUM", "responsiveness": { "status": "UNKNOWN", "answered": 0, "total": 0, "computed_at": "2026-10-12T09:30:00Z" }, "essential_checks": {}, "reachable_rails": [ "GTR", "EMAIL" ], "is_didit_customer": false, "decision": { "decision": "APPROVED", "reason": "Licensed in DE, questionnaire reviewed", "decided_by": "", "updated_at": "2026-10-14T10:05:00Z", "inherited_from": null }, "entity_screening": { "id": "7a1d2c3b-4e5f-4a6b-8c7d-9e0f1a2b3c4d", "status": "Approved", "total_hits": 0, "score": null, "screened_at": "2026-10-14T09:58:00Z", "fresh": true, "flagged": false }, "questionnaires": [ { "id": "8b7a6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "status": "ANSWERED", "form_version": "1", "sent_to": "travelrule@counterparty.example", "sent_at": "2026-09-02T08:00:00Z", "expires_at": "2026-10-02T08:00:00Z", "answered_at": "2026-09-04T15:20:00Z", "valid_until": "2027-09-04T15:20:00Z", "current": true, "answers": { "legal_name": "Example Counterparty VASP, incorporated in the example jurisdiction.", "licensing": "Crypto-asset service provider authorised under MiCA by its national regulator, licence active.", "jurisdictions": "EU and EEA. We do not serve the United States.", "aml_program": "Written AML/CFT policy, annual independent review, last completed in March 2026.", "compliance_officer": "Head of Compliance, reachable at compliance@counterparty.example.", "sanctions_screening": "Customers at onboarding and daily; counterparties on every transfer.", "transaction_monitoring": "Rule-based monitoring with analyst review; suspicious activity reports filed with the FIU.", "travel_rule": "TRP and email; we answer requests within one business day.", "custody": "Segregated customer wallets held with a qualified custodian, insured.", "ownership": "No shareholder holds 25 percent or more; parent company Example Holding Group.", "record_keeping": "Five-year record-keeping for Travel Rule and transaction data, as our regulator requires.", "data_protection": "Encrypted at rest and in transit, stored in the EU." } } ] } }, "TravelRuleCounterpartyDecision": { "type": "object", "description": "您的应用针对交易对手 VASP 的决策。仅对您的应用私有：绝不会修改共享的目录条目，其他客户也绝不会看到该决策。它仅通过您的交易规则生效（counterparty_dd_status 规则字段以及 travel-rule-counterparty-blocked 和 travel-rule-counterparty-restricted 预设）；绝不会更改转账的路由方式。", "properties": { "decision": { "type": "string", "enum": [ "APPROVED", "RESTRICTED", "BLOCKED" ], "description": "APPROVED：您的团队已放行该交易对手。RESTRICTED：审核后可继续向其转账。BLOCKED：您的团队已拒绝该交易对手。" }, "reason": { "type": "string", "maxLength": 255, "description": "您提供的自由文本原因，无原因时为空。" }, "decided_by": { "type": "string", "description": "做出或最后更改该决策的控制台用户。当由 API 密钥做出时为空。" }, "updated_at": { "type": "string", "format": "date-time" }, "inherited_from": { "type": "object", "nullable": true, "description": "由于您未对该实体本身做出决策，因此该实体遵循其决策的品牌。当决策为交易对手自身的决策时为 null。", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } }, "TravelRuleCounterpartyDecisionResponse": { "type": "object", "properties": { "decision": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyDecision" } ], "nullable": true, "description": "适用于您应用的交易对手的决策：其自身的决策，否则（对于品牌的实体）为该品牌的决策。不存在时为 null。" } } }, "TravelRuleCounterpartyDecisionRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "APPROVED", "RESTRICTED", "BLOCKED" ] }, "reason": { "type": "string", "maxLength": 255, "description": "可选。替换之前的原因；省略则将其清除。" } } }, "TravelRuleCounterpartyScreening": { "type": "object", "description": "针对交易对手实体进行的一次制裁和负面新闻筛查，为您的应用运行并向您的应用计费。仅对您的应用可见：其他客户绝不可见。", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "已通过：无需要注意的可能匹配项。审核中或已拒绝：存在可能的制裁或负面新闻匹配项。" }, "total_hits": { "type": "integer", "description": "筛查返回的可能匹配项数量。" }, "score": { "type": "number", "nullable": true, "description": "可能匹配项中的最高风险评分。未匹配到任何内容时为 Null。" }, "screened_at": { "type": "string", "format": "date-time" }, "fresh": { "type": "boolean", "description": "筛查时间是否短于 fresh_days（30 天）。处于有效期内的筛查会被复用，而不会再次计费。" }, "flagged": { "type": "boolean", "description": "当筛查是最新的且其状态为 In Review 或 Declined 时为 true。当您最新的筛查被标记且交易对手筛查保持开启时，在您的规则中 counterparty_risk_level 为 HIGH。" } } }, "TravelRuleCounterpartyScreeningStatus": { "type": "object", "properties": { "enabled": { "type": "boolean", "description": "您的 counterparty_screening_enabled Travel Rule 设置。默认关闭；处于关闭状态时不会进行任何筛查或计费。" }, "price": { "type": "string", "description": "十进制字符串，以 USD 计：贵组织单次筛查的费用，即企业 AML 筛查价格。" }, "fresh_days": { "type": "integer", "description": "筛查结果保持有效并被复用的天数。" }, "screening": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleCounterpartyScreening" } ], "nullable": true, "description": "您对该交易对手的最新筛查。如果您从未筛查过，则为 null。" } } }, "TravelRuleCounterpartyScreeningRequest": { "type": "object", "properties": { "refresh": { "type": "boolean", "default": false, "description": "即使存在最新的筛查，为 true 时也会重新进行筛查（并再次计费）。" } } }, "TravelRuleCounterpartyScreeningResult": { "type": "object", "properties": { "outcome": { "type": "string", "enum": [ "screened", "reused" ], "description": "screened：运行了新的筛查并已计费 (201)。reused：返回了最新的筛查且未计费 (200)。" }, "screening": { "$ref": "#/components/schemas/TravelRuleCounterpartyScreening" } } }, "TravelRuleCounterpartyQuestionnaire": { "type": "object", "description": "您的应用向交易对手发送的一份尽职调查问卷：Didit 的标准问卷，通过电子邮件发送至记录在案的合规地址，并附带一次性作答链接。仅对您的应用可见。", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "SENT", "ANSWERED", "EXPIRED" ], "description": "SENT：等待回答。ANSWERED：交易对手已回答所有问题。EXPIRED：回答链接在未回答的情况下已关闭（已过截止时间，或被较新的问卷替代），或者回答已超过 valid_until。" }, "form_version": { "type": "string", "description": "答案所属的 Didit 标准问卷版本。目前为 1。" }, "sent_to": { "type": "string", "format": "email" }, "sent_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "答复截止时间，为发送后 30 天。逾期后链接将失效。" }, "answered_at": { "type": "string", "format": "date-time", "nullable": true }, "valid_until": { "type": "string", "format": "date-time", "nullable": true, "description": "回答保持有效的时间：回答后 365 天。在回答之前为 null。" }, "current": { "type": "boolean", "description": "当问卷处于 ANSWERED 状态且 valid_until 尚未过期时为 true。" }, "answers": { "type": "object", "additionalProperties": { "type": "string" }, "description": "按问题 ID 索引的答案：legal_name、licensing、jurisdictions、aml_program、compliance_officer、sanctions_screening、transaction_monitoring、travel_rule、custody、ownership、record_keeping、data_protection。每个答案最多 2,000 个字符。作答前为空。" } } }, "TravelRuleCounterpartyQuestionnaireRequest": { "type": "object", "properties": { "sent_to": { "type": "string", "format": "email", "description": "可选。记录在案的交易对手合规地址：对于目录条目，为其合规地址或您的应用可见的联系方式；对于 Didit 网络成员，为其已确认的合规邮箱。默认值：发送给交易对手的 Travel Rule 邮件的目标地址（优先使用您自己的联系方式，其次是平台联系方式，最后是该条目的合规地址）。" } } }, "TravelRuleCounterpartyQuestionnaireList": { "type": "object", "properties": { "questionnaires": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleCounterpartyQuestionnaire" }, "description": "最新的排在前面。" } } }, "TravelRulePickupInfo": { "type": "object", "description": "通过电子邮件发送的提取链接背后的待处理兑换，与交易对手响应页面显示的一致。", "properties": { "reference": { "type": "string", "format": "uuid", "description": "转账的 uuid，与发送方 VASP 控制台显示的一致。" }, "requested_at": { "type": "string", "format": "date-time" }, "originator_vasp_name": { "type": "string" }, "originator_vasp_lei": { "type": "string" }, "recipient_vasp_name": { "type": "string", "description": "请求所发往的交易对手 VASP。" }, "language": { "type": "string", "description": "请求邮件和响应页面所使用的语言，根据交易对手所在的司法管辖区确定。" }, "amount": { "type": "string" }, "currency": { "type": "string" }, "fiat_amount": { "type": "string", "description": "发送方给出的折算价值，或为空。" }, "fiat_currency": { "type": "string" }, "chain": { "type": "string" }, "beneficiary_wallet": { "type": "string" }, "status": { "type": "string" }, "ivms_version": { "type": "string" }, "deadline_at": { "type": "string", "format": "date-time", "description": "链接停止响应的时间。" }, "reminders_sent": { "type": "integer" }, "contact": { "type": "string", "description": "回显链接中的 `?contact=` 值；如果链接中没有该参数，则为空。" }, "decline_reasons": { "type": "array", "items": { "type": "string", "enum": [ "data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other" ] }, "description": "`decline_reason` 接受的值。" }, "join_invitation": { "type": "object", "description": "交易对手是否持有免费加入 Didit 的有效邀请。邀请链接仅通过发送给受邀地址的电子邮件传递，因此此处的 `url` 为空。", "properties": { "eligible": { "type": "boolean" }, "url": { "type": "string" } } }, "originator_data": { "type": "object", "description": "发送方 VASP 共享的汇款人字段（`data_sharing_fields`）。姓名和钱包始终包含在内。" }, "beneficiary_data": { "type": "object" }, "ivms_request": { "type": "object", "description": "表现为 IVMS 101 对象的相同请求。当 `data_masked` 为 true 时省略。" }, "data_masked": { "type": "boolean", "description": "在此 endpoint 上始终为 false：邮件请求为出站请求，且发送方自身的用户绝不会被遮掩。" } } }, "TravelRulePickupRespondRequest": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "accept", "decline" ] }, "beneficiary_name": { "type": "string", "description": "您记录中保存的收款人姓名，已通过汇款方 VASP 的姓名规则处理。若 `ivms_response` 中指明了收款人，则以其为准。", "maxLength": 255 }, "decline_reason": { "type": "string", "enum": [ "", "data_mismatch", "not_our_customer", "wallet_not_hosted", "sanctions", "risk_appetite", "jurisdiction", "insufficient_data", "other" ], "description": "您拒绝的原因。记录在发送方 VASP 的转账时间线上。如果您未提供原因，则为空（默认值）。" }, "decline_detail": { "type": "string", "maxLength": 512, "description": "自由格式文本；当 `decision` 为 `decline` 且 `decline_reason` 为 `other` 时必填。" }, "ivms_response": { "type": "object", "description": "您完整的 IVMS 101 响应。其中的收款人姓名优先级高于 `beneficiary_name`。" }, "contact": { "type": "string", "format": "uuid", "description": "链接发送到的联系人，取自链接的 `?contact=` 值。当请求体中省略时，使用 `contact` 查询参数。" } } }, "TravelRuleInboundRequest": { "type": "object", "required": [ "chain", "txid", "wallet_address", "amount", "currency" ], "properties": { "chain": { "type": "string", "description": "存款结算所在的区块链网络，例如 `ETH`。以小写形式存储，并与您的钱包地址簿条目进行不区分大小写的比对，因此请在地址簿中使用相同的区块链网络 token。", "maxLength": 32 }, "txid": { "type": "string", "description": "链上交易哈希。与 wallet_address 一起去重。", "maxLength": 128 }, "wallet_address": { "type": "string", "description": "您接收充值的目标钱包。XRP X-address 会被拆分为其传统地址和标签。", "maxLength": 128 }, "amount": { "type": "string", "description": "充值金额，采用十进制字符串表示，大于或等于零，最多保留 18 位小数。" }, "currency": { "type": "string", "description": "充值资产，例如 \"USDC\"。", "maxLength": 16 }, "originator_data": { "type": "object", "description": "来自发送方 VASP 的汇款人详情（如果已知），为扁平对象，例如 `{\"name\": \"...\"}`。Didit 会从中读取 name（或 full_name）、first_name、last_name 和 vendor_data。", "additionalProperties": true }, "beneficiary_data": { "type": "object", "description": "收款人详情（您的客户），以扁平对象形式呈现，例如 `{\"name\": \"...\"}`。Didit 会将姓名与匹配的地址簿条目的 holder_name 进行比对，并根据请求设置 wallet_address 和 chain。", "additionalProperties": true }, "originating_vasp": { "type": "object", "description": "发送方 VASP 的可选描述。它仅保留在此笔转账中（`metadata.originating_vasp`，以及 GET /v3/travel-rule/transfers/ 中该转账的汇款人 VASP）；它绝不会创建、编辑或关联共享的 VASP 目录条目。", "properties": { "name": { "type": "string", "maxLength": 255 }, "lei": { "type": "string", "maxLength": 20, "description": "可选。有效的 20 个字符的 ISO 17442 LEI，或留空。" }, "travel_address": { "type": "string", "description": "发送方的 Travel Address，已记录在本次转账中。", "maxLength": 512 } } }, "memo": { "type": "string", "maxLength": 256, "description": "可选。充值在支持 memo 的网络上的目标标签（destination tag）或 memo：在共享充值地址上，它用于区分您的不同客户，并将匹配该 memo 对应的地址簿条目。XRP：目标标签，为 0 到 4294967295 之间的整数（接受 JSON 数字）。XLM：最多 28 字节的文本 memo、64 位 ID 或 32 字节的十六进制哈希。EOS：最多 256 字节。ATOM：最多 256 个字符。HBAR：最多 100 字节。Bitcoin、EVM、Solana、Tron、Litecoin、Bitcoin Cash、Dogecoin 和 Lightning 钱包不接受 memo：若传入将返回 `400`。别名：`destinationTag` 或 `destination_tag`。" }, "utxo": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleUtxo" } ], "description": "可选，仅限 UTXO 链。充值交易的输入和输出：发送方钱包为声明的 `originator_data.wallet_address`，否则取最大输入。" } } }, "TravelRuleInboundResponse": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "入账存款的 Didit 交易 UUID。" }, "txn_id": { "type": "string", "description": "入账交易的 txn_id：当由 Didit 创建该交易时为 Didit 生成的 ID，或者当复用未认领的入账交易时为您自己的 ID。" }, "created": { "type": "boolean", "description": "当本次调用注册了该转账时为 true (HTTP 201)；当相同 txid 和 wallet_address 的转账已存在时为 false (HTTP 200)。" }, "travel_rule": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } }, "TravelRuleTestVaspInboundRequest": { "type": "object", "required": [ "beneficiary_wallet_address" ], "properties": { "beneficiary_wallet_address": { "type": "string", "description": "目标钱包地址。Didit Test VASP 会向其发送资金，并根据资产所在链与您的钱包地址簿进行匹配。没有匹配条目的钱包也会被接受，入向交易将记为 ON_HOLD。" }, "scenario": { "type": "string", "enum": [ "accept", "name_mismatch" ], "default": "accept", "description": "Didit Test VASP 声明的收款人身份。`accept` 声明持有人本人的姓名；`name_mismatch` 声明任何持有人均不认可的姓名。决策本身始终由您做出。" }, "chain": { "type": "string", "default": "ETH", "description": "资产所在的区块链网络。" }, "amount": { "type": "string", "default": "1", "description": "以十进制字符串表示的金额。" }, "currency": { "type": "string", "default": "ETH", "description": "资产代码。" }, "reference": { "type": "string", "description": "可选的幂等性密钥。使用相同值重试将返回首次调用所创建的转账。" } } }, "TravelRuleTestVaspInboundResponse": { "type": "object", "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "入账转账的 Didit 交易 UUID。" }, "txn_id": { "type": "string", "description": "Didit 生成的 txn_id。" }, "scenario": { "type": "string", "description": "运行的场景。" }, "travel_rule_status": { "type": "string", "description": "您的应用自身决策解析出的状态。" }, "detail": { "type": "string", "description": "转账最终判定为该状态的原因。" }, "test_vasp": { "type": "boolean", "description": "始终为 true：发送方为 Didit Test VASP。" }, "travel_rule": { "$ref": "#/components/schemas/TravelRuleTransferDetail" } } }, "TravelRuleWidgetSessionCreate": { "type": "object", "properties": { "wallet_address": { "type": "string", "description": "待验证的钱包地址。可选；留空时，必须在启动证明时提供该地址。", "maxLength": 128 }, "chain": { "type": "string", "description": "地址的链 token，例如 `ETH`、`BTC` 或 `SOL`。请使用与您的钱包地址簿中相同的 token。消息签名和中本聪测试（Satoshi test）仅对受支持的链提供。证明所验证的地址簿条目将其存储在其规范标识符（ETH、BTC、SOL、TRX）下。", "maxLength": 32 }, "holder_name": { "type": "string", "description": "钱包持有者姓名，用于收款人姓名比对。", "maxLength": 255 }, "vendor_data": { "type": "string", "description": "您为持有者指定的内部标识符，将带入所创建的地址簿条目中。", "maxLength": 255 }, "transaction_id": { "type": "string", "format": "uuid", "description": "可选。当证明核验通过时需要推进的 Travel Rule 转账的 Didit 交易 UUID。", "nullable": true }, "satoshi_deposit_address": { "type": "string", "description": "可选。您控制的充值地址；提供该地址可启用 SATOSHI_TEST 证明方式。", "maxLength": 128 }, "callback_url": { "type": "string", "description": "可选。微件在完成后将客户重定向回的绝对 http(s) URL。", "maxLength": 512 }, "expires_in_minutes": { "type": "integer", "description": "可选。生成的链接的有效期（以分钟为单位）。当提供 SATOSHI_TEST 时，会自动延长以覆盖 Satoshi test 时间窗口。", "default": 60, "minimum": 5, "maximum": 10080 } } }, "TravelRuleWidgetSessionResponse": { "type": "object", "properties": { "widget_session_id": { "type": "string", "format": "uuid" }, "token": { "type": "string", "description": "嵌入在 widget URL 中的不透明会话 token。" }, "url": { "type": "string", "description": "托管的钱包所有权小部件 URL。请在系统浏览器中原样打开（切勿在移动端 SDK 的 webview 内打开）。" }, "expires_at": { "type": "string", "format": "date-time" } } }, "TravelRuleWidgetContext": { "type": "object", "properties": { "vasp_name": { "type": "string", "description": "来自您 VASP 资料的法定名称，会在小部件中向客户展示。不存在资料时为空。" }, "wallet_address": { "type": "string" }, "chain": { "type": "string", "description": "铸造会话所用的链，与您发送的一致。" }, "chain_family": { "type": "string", "nullable": true, "enum": [ "EVM", "BTC", "SOL", "TRON", null ], "description": "链背后的密钥族：EVM（Ethereum、BNB Chain、Polygon、Arbitrum、Base、Optimism、Avalanche、Linea 及其他 EVM 链）、BTC、SOL 或 TRON。一个 EVM 密钥控制每条 EVM 链上的同一地址。当无法在链上验证签名时为 Null。" }, "holder_name": { "type": "string" }, "allowed_methods": { "type": "array", "items": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SCREENSHOT", "SATOSHI_TEST", "SELF_DECLARATION" ] }, "description": "此会话可用的证明方式。MESSAGE_SIGNING 需要包含 chain_family 的链，SATOSHI_TEST 需要会话上存在 satoshi_deposit_address 且链的充值记录 Didit 可回读，SCREENSHOT 需要开启 allow_screenshot_proof 设置，SELF_DECLARATION 需要开启 allow_self_declaration 设置。" }, "transfer_status": { "type": "string", "nullable": true, "description": "关联的 Travel Rule 转账的状态。会话创建时未包含 transaction_id 则为 Null。" }, "callback_url": { "type": "string", "description": "组件完成后将客户返回到的位置。未设置时为空。" }, "expires_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "证明核验后为非空。" }, "proofs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleWidgetProofSummary" } }, "max_attempts": { "type": "integer", "description": "本次会话允许的已拒绝钱包证明。" }, "attempts_used": { "type": "integer", "description": "截至目前已拒绝的证明。" }, "attempts_remaining": { "type": "integer", "description": "为 0 时，启动另一个验证会返回 409，您需要生成一个新的小部件会话。" }, "customization": { "type": "object", "nullable": true, "description": "启用白标时该应用的白标定制信息（颜色、Logo、字体系列），组件将以与验证工作流相同的品牌标识进行渲染。否则为 null。" } } }, "TravelRuleWidgetProofSummary": { "type": "object", "properties": { "proof_id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ], "description": "PENDING：终端用户选择了此方式，证明尚未作出决策。签名失败或测试充值尚无法读取或确认会使证明保持 PENDING 状态并附带 failure_reason，以便终端用户重试；提交的 SATOSHI_TEST 充值会在其窗口关闭前自动重新检查，提交的 SCREENSHOT 等待您的审核。VERIFIED：所有权已证明。REJECTED：测试充值确实有误（发送方不符、转入充值地址的金额不符、早于挑战，或该交易已用于证明另一个钱包）或您的审核员拒绝了屏幕截图；failure_reason 会说明具体原因。被拒绝的证明为最终状态，并会消耗会话的一次尝试次数。EXPIRED：证明无法再作出决策（其窗口已关闭、终端用户切换了验证方式、小部件会话已失效，或钱包持有者已更改）；failure_reason 会说明具体原因。" }, "wallet_address": { "type": "string" }, "chain": { "type": "string", "description": "该证明所属地址簿条目的规范链标识符，例如 ETH、BTC、SOL、TRX。" }, "deposit_address": { "type": "string", "nullable": true, "description": "客户必须向其发送 Satoshi 测试金额的充值地址。仅存在于 SATOSHI_TEST 证明中。" }, "expected_amount": { "type": "string", "nullable": true, "description": "Satoshi 测试充值必须匹配的链上确切金额，以充值的原生货币计。仅在 SATOSHI_TEST 证明中存在。" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "该证明自身的聪测试（Satoshi test）窗口截止时间。仅在 SATOSHI_TEST 证明上提供；当提供 SATOSHI_TEST 时，挂件会话自身的 expires_at 会被延长以涵盖该窗口。" }, "challenge": { "type": "string", "nullable": true, "description": "Didit 签发并由客户使用其钱包签名的消息。仅存在于 MESSAGE_SIGNING 证明中。" }, "rejection_reason": { "type": "string", "description": "证明被拒绝的原因，作为面向终端用户的英文句子。仅当 `status` 为 REJECTED 时存在；当您的审核员拒绝屏幕截图时为空（您的备注保留在您方）。" }, "created_at": { "type": "string", "format": "date-time" }, "attempts": { "type": "integer", "description": "为此证明提交凭据的次数（签名、交易 ID、上传文件）。" }, "failure_reason": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "上次尝试未达标的原因，或证明关闭的原因。未发生失败时为空。" } } }, "CaseSubject": { "type": "object", "nullable": true, "description": "该案件所绑定的单个用户或企业。", "properties": { "type": { "type": "string", "enum": [ "user", "business" ] }, "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "external_id": { "type": "string", "nullable": true, "description": "主体的 vendor_data。" }, "country": { "type": "string", "nullable": true, "description": "主体的三位字母国家/地区代码（ISO 3166-1 alpha-3），若未知则为 null。对于企业，为其注册国家/地区。对于个人，为其验证中的身份证件的签发国家/地区；拥有多个国家/地区证件的个人将显示其中之一，并且可能会出现类似 `XXA` 的 ICAO 证件代码。", "example": "ESP" }, "portrait": { "type": "string", "format": "uri", "nullable": true, "description": "个人肖像图像的短期签名 URL。对于企业始终为 null，对于没有肖像的人员为 null。该 URL 会过期，因此读取案件时请下载图像，而不是直接存储 URL。" } } }, "CaseAssignee": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "full_name": { "type": "string" }, "email": { "type": "string", "format": "email" } } }, "CaseBlueprintSummary": { "type": "object", "nullable": true, "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 24 } } }, "CaseContentConfig": { "type": "object", "description": "控制案件页面上显示哪些标签页和字段的六个可切换板块。未知的板块或键将被拒绝。", "properties": { "checklist": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "optional": { "type": "boolean", "description": "为 true 时，可以在核对清单项未完成的情况下解决案件。" }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "order": { "type": "integer" } } } } } }, "aml_control": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "financial": { "type": "boolean" }, "identity": { "type": "boolean" } } }, "identity": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "personal_information": { "type": "boolean" }, "applicant_tags": { "type": "boolean" }, "contact_information": { "type": "boolean" }, "risk_overview": { "type": "boolean" }, "poi_documents": { "type": "boolean" }, "poa_documents": { "type": "boolean" } } }, "verifications": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "summary": { "type": "boolean" } } }, "reporting": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "fiu_reports": { "type": "boolean" } } }, "financial": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "payment_methods": { "type": "boolean" }, "transactions": { "type": "boolean" } } } } }, "CaseNote": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "comment": { "type": "string" }, "actor_email": { "type": "string", "format": "email", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" } }, "is_internal": { "type": "boolean" }, "attachments": { "type": "array", "items": { "type": "object", "properties": { "s3_key": { "type": "string" }, "filename": { "type": "string" }, "file_size": { "type": "integer" }, "url": { "type": "string", "format": "uri" } } } }, "tags": { "type": "array", "items": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" } } }, "CaseEvent": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "event_type": { "type": "string", "enum": [ "CREATED", "STATUS_CHANGED", "ASSIGNED", "UNASSIGNED", "RESOLVED", "REOPENED", "LINK_ADDED", "LINK_REMOVED", "NOTE_ADDED", "NOTE_PINNED", "NOTE_UNPINNED", "PRIORITY_CHANGED", "DUE_DATE_CHANGED", "TAG_ADDED", "TAG_REMOVED", "ESCALATED", "TRANSFERRED", "CHECKLIST_COMPLETED", "REPORT_CREATED", "REPORT_FINALIZED", "SUBMITTED_FOR_APPROVAL", "APPROVAL_GRANTED", "APPROVAL_REJECTED", "ENTITY_ACTION", "APPROVAL_INVALIDATED", "CUSTOMER_REQUEST", "STAGE_CHANGED", "TEAM_CHANGED", "CHECKER_ASSIGNED", "CHECKER_UNASSIGNED" ] }, "actor_email": { "type": "string", "format": "email", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "previous_status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ], "nullable": true }, "new_status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ], "nullable": true }, "metadata": { "type": "object" }, "created_at": { "type": "string", "format": "date-time" } } }, "CaseLink": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "linked_entity_type": { "type": "string", "enum": [ "session", "business_session", "transaction" ], "nullable": true }, "linked_entity_uuid": { "type": "string", "format": "uuid", "nullable": true }, "linked_entity_summary": { "type": "object", "nullable": true, "description": "对于 session 和 business_session 链接为 session_id/session_number/status；对于 transaction 链接为 uuid/txn_id/status。" }, "created_at": { "type": "string", "format": "date-time" } } }, "CaseChecklistItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string", "maxLength": 255 }, "is_completed": { "type": "boolean" }, "completed_by": { "type": "string", "format": "email", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "order": { "type": "integer" } } }, "CaseBlueprintListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "nullable": true }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "max_active_cases": { "type": "integer", "nullable": true }, "escalation_enabled": { "type": "boolean" }, "transfer_enabled": { "type": "boolean" }, "require_resolution_note": { "type": "boolean" }, "is_active": { "type": "boolean" }, "preset_key": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "readOnly": true }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760 } } }, "CaseBlueprintDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "nullable": true }, "assignment_method": { "type": "string", "enum": [ "MANUAL", "AUTOMATIC" ] }, "assignee_pool": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "max_active_cases": { "type": "integer", "nullable": true }, "escalation_enabled": { "type": "boolean" }, "transfer_enabled": { "type": "boolean" }, "require_resolution_note": { "type": "boolean" }, "is_active": { "type": "boolean" }, "preset_key": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "escalation_blueprint_name": { "type": "string", "nullable": true }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "four_eyes_checker_blueprint_name": { "type": "string", "nullable": true }, "content_config": { "type": "object", "description": "控制案件页面上显示哪些标签页和字段的六个可切换板块。未知的板块或键将被拒绝。", "properties": { "checklist": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "optional": { "type": "boolean", "description": "为 true 时，可以在核对清单项未完成的情况下解决案件。" }, "items": { "type": "array", "items": { "type": "object", "properties": { "label": { "type": "string", "maxLength": 255 }, "order": { "type": "integer" } } } } } }, "aml_control": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "financial": { "type": "boolean" }, "identity": { "type": "boolean" } } }, "identity": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "personal_information": { "type": "boolean" }, "applicant_tags": { "type": "boolean" }, "contact_information": { "type": "boolean" }, "risk_overview": { "type": "boolean" }, "poi_documents": { "type": "boolean" }, "poa_documents": { "type": "boolean" } } }, "verifications": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "summary": { "type": "boolean" } } }, "reporting": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "fiu_reports": { "type": "boolean" } } }, "financial": { "type": "object", "properties": { "enabled": { "type": "boolean" }, "payment_methods": { "type": "boolean" }, "transactions": { "type": "boolean" } } } } }, "creation_sources": { "type": "array", "description": "当前将新案件路由到此蓝图的连接器。", "items": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "aml", "rule", "workflow" ] }, "id": { "type": "string" }, "name": { "type": "string" } } } }, "receives_escalation_from": { "type": "array", "description": "升级目标指向此蓝图的其他蓝图。", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } }, "updated_at": { "type": "string", "format": "date-time" }, "version": { "type": "integer", "readOnly": true }, "default_deadline_hours": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 8760 } } }, "CaseListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true, "description": "自动分配，例如 CS-0001。" }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ], "nullable": true }, "pending_resolution": { "type": "object", "nullable": true, "description": "仅在双人复核（4-eyes）决议暂存于审核员蓝图、等待批准或拒绝批准时设置。", "properties": { "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ] }, "resolution_notes": { "type": "string", "nullable": true }, "maker_email": { "type": "string", "format": "email", "nullable": true, "description": "提交处置决议的合规官邮箱。由 API 密钥提交时为 Null：该处置决议没有记录的制定者，因此针对所有调用方，approve 和 reject-approval 均返回 403。" }, "maker_name": { "type": "string", "nullable": true }, "maker_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "提交处理决定的人员的成员用户 uuid。由 API 密钥提交时为 null。该成员不能被指定为 `checker`。" }, "maker_blueprint_id": { "type": "string", "format": "uuid" }, "staged_at": { "type": "string", "format": "date-time" } } }, "checker": { "$ref": "#/components/schemas/CaseChecker" }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "source": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "$ref": "#/components/schemas/CaseSubject" }, "assigned_to": { "$ref": "#/components/schemas/CaseAssignee" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true }, "team": { "$ref": "#/components/schemas/CaseTeamSummary" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by_email": { "type": "string", "nullable": true }, "created_by_name": { "type": "string", "nullable": true }, "blueprint": { "$ref": "#/components/schemas/CaseBlueprintSummary" }, "links_count": { "type": "integer" }, "notes_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "application_id": { "type": "string", "format": "uuid" }, "application_name": { "type": "string" }, "organization_id": { "type": "string", "format": "uuid" }, "organization_name": { "type": "string" } } }, "CaseDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true }, "title": { "type": "string" }, "status": { "type": "string", "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ] }, "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ], "nullable": true }, "resolution_notes": { "type": "string", "nullable": true }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ] }, "source": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "tags": { "type": "array", "items": { "type": "string" } }, "subject": { "$ref": "#/components/schemas/CaseSubject" }, "assigned_to": { "$ref": "#/components/schemas/CaseAssignee" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true }, "team": { "$ref": "#/components/schemas/CaseTeamSummary" }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true }, "resolved_by_email": { "type": "string", "nullable": true }, "pending_resolution": { "type": "object", "nullable": true, "description": "仅在双人复核（4-eyes）决议暂存于审核员蓝图、等待批准或拒绝批准时设置。", "properties": { "resolution": { "type": "string", "enum": [ "FALSE_POSITIVE", "VALID_THREAT", "INCONCLUSIVE", "REQUIREMENTS_NOT_MET", "REQUIREMENTS_SATISFIED" ] }, "resolution_notes": { "type": "string", "nullable": true }, "maker_email": { "type": "string", "format": "email", "nullable": true, "description": "提交处置决议的合规官邮箱。由 API 密钥提交时为 Null：该处置决议没有记录的制定者，因此针对所有调用方，approve 和 reject-approval 均返回 403。" }, "maker_name": { "type": "string", "nullable": true }, "maker_user_id": { "type": "string", "format": "uuid", "nullable": true, "description": "提交处理决定的人员的成员用户 uuid。由 API 密钥提交时为 null。该成员不能被指定为 `checker`。" }, "maker_blueprint_id": { "type": "string", "format": "uuid" }, "staged_at": { "type": "string", "format": "date-time" } } }, "checker": { "$ref": "#/components/schemas/CaseChecker" }, "metadata": { "type": "object" }, "blueprint": { "$ref": "#/components/schemas/CaseBlueprintDetail" }, "notes": { "type": "array", "items": { "$ref": "#/components/schemas/CaseNote" }, "description": "最新的 50 条备注。" }, "events": { "type": "array", "items": { "$ref": "#/components/schemas/CaseEvent" }, "description": "最新的 100 个事件。" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/CaseLink" } }, "links_count": { "type": "integer" }, "notes_count": { "type": "integer" }, "checklist_items": { "type": "array", "items": { "$ref": "#/components/schemas/CaseChecklistItem" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "ReportTemplateDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 国家/地区代码。" }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "report_type_display": { "type": "string" }, "field_config": { "type": "object", "description": "可复用的 goAML 请求头默认值。模板级别的必填字段：rentity_id、submission_code 和 currency_code_local（3 字母）。可选字段：enabled_fields（包含哪些可选报告块）以及 reporting_person、location、reason 和 action 默认值。每次申报的请求头字段（action、submission_date、transactions、jurisdiction）在报告通过核验或定稿时强制要求，而不是在模板上强制要求。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "RegulatoryReportDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "case_uuid": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ] }, "report_type_display": { "type": "string" }, "report_code": { "type": "string", "description": "从 report_type 派生的 goAML 报告代码，例如 STR、CTR、BCR。" }, "report_number": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "DRAFT", "VALIDATED", "FINALIZED" ] }, "status_display": { "type": "string" }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2 }, "rentity_id": { "type": "string", "nullable": true, "description": "FIU 签发的报告实体 ID。" }, "rentity_branch": { "type": "string", "nullable": true }, "submission_code": { "type": "string", "enum": [ "E", "M" ] }, "entity_reference": { "type": "string", "nullable": true }, "fiu_ref_number": { "type": "string", "nullable": true }, "currency_code_local": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "submission_date": { "type": "string", "format": "date-time", "nullable": true }, "reporting_person": { "type": "object" }, "location": { "type": "object" }, "reason": { "type": "string", "nullable": true }, "action": { "type": "string", "nullable": true }, "activity": { "type": "string", "nullable": true }, "narrative": { "type": "object", "description": "5W 叙述部分。", "properties": { "who": { "type": "string" }, "what": { "type": "string" }, "when": { "type": "string" }, "where": { "type": "string" }, "why": { "type": "string" }, "how": { "type": "string" } } }, "report_indicators": { "type": "array", "items": { "type": "string" } }, "included_fields": { "type": "array", "items": { "type": "string" } }, "transactions": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "validation_errors": { "type": "array", "description": "最近一次验证的结果；每个条目均为一个 {field, message} 对象。", "items": { "type": "object", "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } }, "validated_at": { "type": "string", "format": "date-time", "nullable": true }, "finalized_at": { "type": "string", "format": "date-time", "nullable": true }, "created_by_email": { "type": "string", "nullable": true }, "created_by_name": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TransactionRuleCondition": { "type": "object", "required": [ "field", "operator" ], "properties": { "field": { "type": "string", "description": "要评估的交易字段路径。核心字段：amount、currency、direction、action_type、score、severity、transaction_type、payment_details、preferred_currency_amount（回退到 amount_in_default_currency）、default_currency_code、subject_country、counterparty_country、subject_vendor_data、counterparty_vendor_data、subject_device_fingerprint、counterparty_device_fingerprint、subject_browser_family、subject_browser_version、subject_platform、subject_accept_language、subject_session_age_ms、subject_ip_country、counterparty_ip_country、subject_ip_address、counterparty_ip_address、subject_payment_method_type、subject_payment_method_country、subject_payment_method_fingerprint、subject_payment_method_account_id（以及 counterparty_payment_method_* 等效字段）、travel_rule_status、travel_rule_required、travel_rule_obligations_count、counterparty_dd_status（您对 Travel Rule 交易对手的决策：APPROVED、RESTRICTED 或 BLOCKED，实体遵循其品牌决策）、counterparty_risk_level（LOW、MEDIUM 或 HIGH；在您自己的交易对手筛查被标记时为 HIGH）、counterparty_jurisdiction（交易对手 VASP 的国家/地区）、counterparty_responsiveness（RESPONSIVE、UNRESPONSIVE 或 UNKNOWN）、subject_days_since_previous_transaction、tags，以及在创建交易时通过 custom_properties 提交的任何键的 custom_values.。国家/地区代码字段接受 ISO-2 或 ISO-3；比对前双方均会归一化为 ISO-3。" }, "operator": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte", "in", "not_in", "contains", "not_contains", "contains_any", "regex", "fuzzy_match", "exists", "is_not_empty", "is_not_null", "not_exists", "is_empty", "is_null" ], "description": "比较运算符。in/not_in 测试成员资格（值可以是一个列表或单个标量）。contains/not_contains 是针对字符串值的大小写不敏感子字符串检查。contains_any 接受一个字符串列表，并在其中任意一项是字段值的大小写不敏感子字符串时匹配。regex 将值模式与字段进行正则匹配。fuzzy_match 使用所需的 `score` 阈值（0-100）与值字符串进行模糊比对。当任意一侧缺失时，gt/gte/lt/lte 绝不会匹配。exists/is_not_empty/is_not_null（别名）和 not_exists/is_empty/is_null（别名）是忽略 `value` 的存在性检查。" }, "value": { "description": "比较值。其结构取决于运算符和 value_type；对于存在性检查运算符，请将其省略。其他所有运算符都需要一个既不是 `null` 也不是空列表的值，否则规则将被拒绝并返回 `400`。`contains_any` 需要一个字符串列表，而 `contains`、`not_contains` 和 `regex` 需要单个字符串。" }, "value_type": { "type": "string", "enum": [ "list", "field", "relative_date" ], "description": "可选的值解释方式。`list`：值为 List UUID，该列表中的条目将作为比对值。`field`：值为另一个字段路径，进行字段之间的比对。`relative_date`：值为相对日期对象，例如 {\"direction\": \"past\", \"unit\": \"days\", \"amount\": 30}。" }, "score": { "type": "number", "minimum": 0, "maximum": 100, "description": "当 operator 为 fuzzy_match 时必填：0-100 的相似度阈值。" }, "group_index": { "type": "integer", "description": "可选的分组逻辑。当任何条件带有 group_index 时，共享同一索引的条件将组成一个组，并由分组求值取代 evaluation_mode。" }, "group_logic": { "type": "string", "enum": [ "AND", "OR" ], "default": "AND", "description": "组内条件的组合方式。" }, "groups_logic": { "type": "string", "enum": [ "AND", "OR" ], "default": "OR", "description": "跨组的组结果组合方式。从第一个条件读取。" } }, "description": "条件仅读取正在被评估的交易，绝不筛选聚合窗口。" }, "TransactionRuleAggregation": { "type": "object", "required": [ "value" ], "properties": { "metric": { "type": "string", "enum": [ "count", "sum", "max", "min", "avg", "distinct_count" ], "default": "count", "description": "匹配的历史交易的聚合方式。unique_count 可作为 distinct_count 的别名接受。" }, "field": { "type": "string", "default": "amount", "description": "按 sum/max/min/avg/distinct_count 聚合的字段。对于 count 则忽略。" }, "operator": { "type": "string", "enum": [ "eq", "ne", "gt", "gte", "lt", "lte" ], "default": "eq", "description": "应用于计算指标的比对条件。" }, "value": { "type": "number", "description": "与计算出的指标进行比对的阈值。" }, "window": { "type": "string", "pattern": "^\\d+(m|h|d)$", "default": "1d", "description": "截至交易 txn_date 的回溯窗口：m（分钟，非月份）、h（小时）或 d（天），例如 30m、24h、7d、30d。" }, "filters": { "type": "object", "additionalProperties": true, "description": "限制聚合的历史交易范围。键是来自条件字段目录的字段路径；值为 \"__current__\" 表示解析为正在评估的交易上相同字段的值（例如 {\"subject_vendor_data\": \"__current__\"} 将时间窗口限定为同一主体），列表值表示成员关系。没有分组值的记录绝不会被分组在一起：当正在评估的交易没有 \"__current__\" 字段的值（无交易对手、无设备指纹）时，无论其运算符是什么，聚合都不会匹配。过滤器仅通过相等性或成员关系进行比较：没有 lt/gte 过滤器，因此无法在此处表达诸如“10,000 以下的历史交易”之类的范围。请改为在指标上设置范围（运算符为 lt 的 metric max 会将时间窗口内的每笔交易保持在阈值以下）。" } }, "description": "在时间窗口内对应用的历次交易执行频次检查。无论 evaluation_mode 为何，每个聚合条目都必须匹配，该规则才算匹配。聚合仅约束时间窗口；被评估的交易受范围和条件约束，因此当规则要求时，需在两部分上重复 direction、currency 或 transaction_type。" }, "TransactionRuleScope": { "type": "object", "properties": { "transaction_types": { "type": "array", "items": { "type": "string" }, "description": "限制交易类型，例如 finance、kyc、travel_rule、user_event。为空或缺失 = 无限制。" }, "directions": { "type": "array", "items": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "description": "限制交易方向（写入时不区分大小写）。" }, "action_types": { "type": "array", "items": { "type": "string" }, "description": "限制为您定义的 action_type 值，例如 withdrawal、deposit。" } }, "description": "该规则适用于哪些交易。仅接受这三个键。" }, "TransactionRuleAction": { "oneOf": [ { "$ref": "#/components/schemas/TransactionRuleActionAddScore" }, { "$ref": "#/components/schemas/TransactionRuleActionChangeStatus" }, { "$ref": "#/components/schemas/TransactionRuleActionAddTags" }, { "$ref": "#/components/schemas/TransactionRuleActionAddNote" }, { "$ref": "#/components/schemas/TransactionRuleActionAddToList" }, { "$ref": "#/components/schemas/TransactionRuleActionOpenCase" } ], "discriminator": { "propertyName": "type", "mapping": { "add_score": "#/components/schemas/TransactionRuleActionAddScore", "change_status": "#/components/schemas/TransactionRuleActionChangeStatus", "add_tags": "#/components/schemas/TransactionRuleActionAddTags", "add_note": "#/components/schemas/TransactionRuleActionAddNote", "add_to_list": "#/components/schemas/TransactionRuleActionAddToList", "open_case": "#/components/schemas/TransactionRuleActionOpenCase" } }, "description": "一个规则操作。一条规则可包含多个操作；命中时将一并应用。处于 TEST 模式的规则会记录本应执行的操作，而不会实际应用任何操作。" }, "TransactionRuleCreateRequest": { "type": "object", "required": [ "title", "category", "mode" ], "properties": { "title": { "type": "string", "description": "规则名称。在每个应用未删除的规则中必须唯一；重复将返回 400。" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "用于分组和报告的风险主题，例如 finance、aml_ctf、anomaly_detection、fatf、device_intelligence、crypto_monitoring、travel_rule、responsible_gaming、e_commerce。" }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ], "description": "ACTIVE 会进行实时评估。TEST 会评估并记录规则运行情况，但绝不会影响评分或状态，这是推荐的初始模式。DISABLED 则会被跳过。" }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL", "description": "是否必须满足所有条件（ALL）还是至少满足一个条件（ANY）。当条件使用 group_index 时忽略此项。" }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object", "description": "存储在规则中的自由格式元数据。" } }, "description": "创建一条 CUSTOM 规则。处于 ACTIVE 模式的规则会立即对新交易生效，请先在 TEST 模式下创建并进行回测。" }, "TransactionRuleUpdateRequest": { "type": "object", "properties": { "title": { "type": "string", "description": "规则名称。在每个应用未删除的规则中必须唯一；重复将返回 400。" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "用于分组和报告的风险主题，例如 finance、aml_ctf、anomaly_detection、fatf、device_intelligence、crypto_monitoring、travel_rule、responsible_gaming、e_commerce。" }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ], "description": "ACTIVE 会进行实时评估。TEST 会评估并记录规则运行情况，但绝不会影响评分或状态，这是推荐的初始模式。DISABLED 则会被跳过。" }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL", "description": "是否必须满足所有条件（ALL）还是至少满足一个条件（ANY）。当条件使用 group_index 时忽略此项。" }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object", "description": "存储在规则中的自由格式元数据。" } }, "description": "部分更新。自定义规则接受所有字段；库（PRESET）规则仅接受 mode，传入任何其他内容均返回 400。" }, "TransactionRuleDetail": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "title": { "type": "string", "description": "规则名称。在每个应用未删除的规则中必须唯一；重复将返回 400。" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string", "description": "用于分组和报告的风险主题，例如 finance、aml_ctf、anomaly_detection、fatf、device_intelligence、crypto_monitoring、travel_rule、responsible_gaming、e_commerce。" }, "mode": { "type": "string", "enum": [ "ACTIVE", "DISABLED", "TEST" ], "description": "ACTIVE 会进行实时评估。TEST 会评估并记录规则运行情况，但绝不会影响评分或状态，这是推荐的初始模式。DISABLED 则会被跳过。" }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL", "description": "是否必须满足所有条件（ALL）还是至少满足一个条件（ANY）。当条件使用 group_index 时忽略此项。" }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object", "description": "存储在规则中的自由格式元数据。" }, "severity": { "type": "string", "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "nullable": true, "description": "规则库规则携带的信息性严重程度；不可在自定义规则上设置。" }, "source": { "type": "string", "enum": [ "PRESET", "CUSTOM" ], "description": "PRESET 规则来自规则库（安装/卸载，仅限模式编辑）；CUSTOM 规则完全由您自定义。" }, "library_key": { "type": "string", "nullable": true, "description": "稳定的库标识符；自定义规则为 null。" }, "latest_triggered_at": { "type": "string", "format": "date-time", "nullable": true }, "run_count": { "type": "integer", "description": "匹配此规则的交易数量。" }, "approved_count": { "type": "integer" }, "reviewed_count": { "type": "integer" }, "declined_count": { "type": "integer" }, "awaiting_user_count": { "type": "integer" }, "approved_pct": { "type": "number" }, "reviewed_pct": { "type": "number" }, "declined_pct": { "type": "number" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "TransactionRuleBacktestRequest": { "type": "object", "properties": { "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" }, "default": [] }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" }, "default": [] }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ], "default": "ALL" }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "period_days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 90 } }, "description": "用于对照近期交易进行评估的假设规则配置。只读且免费：不会创建或修改任何内容。请发送与您打算激活的规则相同的 conditions、aggregation、evaluation_mode 以及 scope。省略 conditions、aggregation 和 scope 不会添加其自身的限制约束；省略 scope 可能会包含已保存规则所跳过的流向或交易类型。省略 evaluation_mode 默认设为 ALL（对于 ANY 规则这可能会减少匹配项），省略 period_days 默认设为 90 天，而非无限制的历史记录。" }, "TransactionRuleBacktestResult": { "type": "object", "properties": { "evaluated": { "type": "integer", "description": "已评估的交易（最近优先，有数量上限）。" }, "matched": { "type": "integer", "description": "该配置本应匹配的交易。" }, "affected_entities": { "type": "integer", "description": "匹配项中不同的主体（按 vendor_data 区分）。" }, "period_days": { "type": "integer" } } }, "TransactionRuleLibraryEntry": { "type": "object", "properties": { "library_key": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string", "nullable": true }, "category": { "type": "string" }, "evaluation_mode": { "type": "string", "enum": [ "ALL", "ANY" ] }, "scope": { "$ref": "#/components/schemas/TransactionRuleScope" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleCondition" } }, "aggregation": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAggregation" } }, "actions": { "type": "array", "items": { "$ref": "#/components/schemas/TransactionRuleAction" } }, "metadata": { "type": "object" }, "bundle": { "type": "string", "nullable": true, "description": "功能类别，例如 finance、aml_ctf、crypto_monitoring、travel_rule、responsible_gaming。" }, "tags": { "type": "array", "items": { "type": "string" } }, "industries": { "type": "array", "items": { "type": "string" } }, "source": { "type": "string" }, "is_installed": { "type": "boolean", "description": "该预设当前是否已安装在应用中。" } } }, "TransactionRuleInstallRequest": { "type": "object", "properties": { "library_keys": { "type": "array", "items": { "type": "string" }, "description": "要安装或卸载的特定预设。" }, "bundle": { "type": "string", "description": "改为安装或卸载此 bundle 中的所有预设。" } }, "description": "提供 library_keys 或 bundle。" }, "TransactionRuleInstallResult": { "type": "object", "properties": { "installed_library_keys": { "type": "array", "items": { "type": "string" }, "description": "仅限 POST（安装）：通过此调用安装的预设。" }, "installed_count": { "type": "integer", "description": "仅限 POST（安装）。" }, "uninstalled_count": { "type": "integer", "description": "仅限 DELETE（卸载）：通过此调用移除的预设。" } } }, "WalletScreeningResult": { "type": "object", "properties": { "provider": { "type": "string", "description": "执行筛查的提供商（例如 `merklescience`、`crystal`）。" }, "screening_type": { "type": "string", "enum": [ "WALLET_SCREENING" ], "description": "对于此 endpoint 始终为 `WALLET_SCREENING`。" }, "risk_score": { "type": "integer", "description": "归一化的 0-100 风险评分。分值越高表示对高风险实体的暴露越大。Merkle Science 将地址评为 0-5 级，分别对应 0、15、35、55、75 或 95。" }, "severity": { "type": "string", "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL" ], "description": "根据 `risk_score` 派生的风险区间：`0-9` 为 UNKNOWN，`10-39` 为 LOW，`40-69` 为 MEDIUM，`70-89` 为 HIGH，`90-100` 为 CRITICAL。`UNKNOWN` 是最低区间，并非单独的无数据状态：`risk_score` 为 0（常见的无风险地址情况）表示无负面评估，而 1-9 范围内的非零分数是真实存在但低于 LOW 的信号，请读取 `risk_score`，而不仅仅是查看区间。切勿将 `UNKNOWN` 视为明确的低风险或通过评级；请勿将其显示为通过。" }, "status": { "type": "string", "enum": [ "SCREENED", "PENDING", "ERROR" ], "description": "筛查结果状态。" }, "summary": { "type": "string", "description": "易于阅读的筛查结果摘要。" }, "wallet_address": { "type": "string", "description": "已筛查的地址，原样回显。" }, "transaction_hash": { "type": "string", "nullable": true, "description": "交易筛查字段，与结果结构共用。在钱包筛查结果中始终为 `null`。" }, "blockchain": { "type": "string", "description": "已进行筛查的区块链。" }, "block_timestamp": { "type": "string", "nullable": true, "description": "交易筛查字段，与结果结构共用。在钱包筛查结果中始终为 `null`。" }, "total_value_usd": { "type": "number", "nullable": true, "description": "交易筛查字段，与结果结构共用。在钱包筛查结果中始终为 `null`。" }, "fee_usd": { "type": "number", "nullable": true, "description": "交易筛查字段，与结果结构共用。在钱包筛查结果中始终为 `null`。" }, "sender_rows": { "type": "array", "items": { "type": "object" }, "description": "交易筛查字段，与结果结构共用。在钱包筛查结果中始终为空。" }, "receiver_rows": { "type": "array", "items": { "type": "object" }, "description": "交易筛查字段，与结果结构共用。在钱包筛查结果中始终为空。" }, "transaction_flows": { "type": "array", "items": { "type": "object" }, "description": "交易筛查字段，与结果结构共用。在钱包筛查结果中始终为空。" }, "transaction_flows_status": { "type": "string", "nullable": true, "description": "交易筛查字段，与结果结构共用。在钱包筛查结果中始终为 `null`。" }, "transaction_flows_error": { "type": "string", "nullable": true, "description": "交易筛查字段，与结果结构共用。在钱包筛查结果中始终为 `null`。" }, "source_of_funds": { "type": "array", "description": "该地址从何处接收资金，按实体归因。每个条目都是一个风险敞口明细。", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "归一化的风险类别，例如 `exchange_licensed`、`dex`、`defi`、`payment_processor`、`mixer`、`darknet_market`、`sanctioned`、`stolen_funds`、`high_risk_exchange`。" }, "percentage": { "type": "number", "description": "该方向总风险敞口的占比，0-100。" }, "amount_usd": { "type": "number", "nullable": true, "description": "归属于该实体的美元价值。" }, "entity_name": { "type": "string", "nullable": true, "description": "归属实体的名称，例如交易所、混币器或受制裁群体。" }, "entity_type": { "type": "string", "nullable": true, "description": "提供商实体类型（例如 `Exchange`、`DeFi`、`Sanctions`、`Theft`）。" }, "entity_subtype": { "type": "string", "nullable": true, "description": "更细粒度的子类型（例如 `Mandatory KYC and AML`、`OFAC`、`Yield Aggregator`）。" }, "hops": { "type": "integer", "nullable": true, "description": "当提供商报告跳数时，到实体的跳数（直接交易对手为 1）。Merkle Science 始终为 `null`，因为它仅报告暴露是直接还是间接：请使用 `exposure_type`。" }, "description": { "type": "string", "nullable": true, "description": "`entity_type / entity_subtype`，按提供商对主体的标注。" }, "is_direct": { "type": "boolean", "description": "当 `exposure_type` 为 `direct` 时为 true。" }, "exposure_direction": { "type": "string", "enum": [ "incoming", "outgoing", "connected" ], "description": "资金是来自该实体（`incoming`）还是流向该实体（`outgoing`）。" }, "exposure_type": { "type": "string", "enum": [ "direct", "indirect" ], "description": "`direct`（1 跳）或 `indirect`（多跳）风险敞口。" }, "provider_entity_id": { "type": "string", "nullable": true, "description": "服务商自身针对该实体的标识符。" }, "provider_entity_type_id": { "type": "string", "nullable": true, "description": "服务商自身针对 `entity_type` 的标识符。" }, "provider_entity_subtype_id": { "type": "string", "nullable": true, "description": "服务商自身针对 `entity_subtype` 的标识符。" }, "country": { "type": "string", "nullable": true, "description": "实体的首要 ISO 3166-1 alpha-2 国家/地区。提供商未知时为空或 `null`。" }, "raw_amount": { "type": "number", "nullable": true, "description": "以资产自身单位表示的金额（当提供商报告时）。" }, "raw_currency": { "type": "string", "nullable": true, "description": "`raw_amount` 的单位，在提供商报告该单位时提供。" } } } }, "destination_of_funds": { "type": "array", "description": "该地址向何处发送资金，按实体归因。条目格式与 `exposure_direction` = `outgoing` 的 `source_of_funds` 相同。", "items": { "type": "object", "properties": { "category": { "type": "string", "description": "归一化的风险类别，例如 `exchange_licensed`、`dex`、`defi`、`payment_processor`、`mixer`、`darknet_market`、`sanctioned`、`stolen_funds`、`high_risk_exchange`。" }, "percentage": { "type": "number", "description": "该方向总风险敞口的占比，0-100。" }, "amount_usd": { "type": "number", "nullable": true, "description": "归属于该实体的美元价值。" }, "entity_name": { "type": "string", "nullable": true, "description": "归属实体的名称，例如交易所、混币器或受制裁群体。" }, "entity_type": { "type": "string", "nullable": true, "description": "提供商实体类型（例如 `Exchange`、`DeFi`、`Sanctions`、`Theft`）。" }, "entity_subtype": { "type": "string", "nullable": true, "description": "更细粒度的子类型（例如 `Mandatory KYC and AML`、`OFAC`、`Yield Aggregator`）。" }, "hops": { "type": "integer", "nullable": true, "description": "当提供商报告跳数时，到实体的跳数（直接交易对手为 1）。Merkle Science 始终为 `null`，因为它仅报告暴露是直接还是间接：请使用 `exposure_type`。" }, "description": { "type": "string", "nullable": true, "description": "`entity_type / entity_subtype`，按提供商对主体的标注。" }, "is_direct": { "type": "boolean", "description": "当 `exposure_type` 为 `direct` 时为 true。" }, "exposure_direction": { "type": "string", "enum": [ "incoming", "outgoing", "connected" ], "description": "资金是来自该实体（`incoming`）还是流向该实体（`outgoing`）。" }, "exposure_type": { "type": "string", "enum": [ "direct", "indirect" ], "description": "`direct`（1 跳）或 `indirect`（多跳）风险敞口。" }, "provider_entity_id": { "type": "string", "nullable": true, "description": "服务商自身针对该实体的标识符。" }, "provider_entity_type_id": { "type": "string", "nullable": true, "description": "服务商自身针对 `entity_type` 的标识符。" }, "provider_entity_subtype_id": { "type": "string", "nullable": true, "description": "服务商自身针对 `entity_subtype` 的标识符。" }, "country": { "type": "string", "nullable": true, "description": "实体的首要 ISO 3166-1 alpha-2 国家/地区。提供商未知时为空或 `null`。" }, "raw_amount": { "type": "number", "nullable": true, "description": "以资产自身单位表示的金额（当提供商报告时）。" }, "raw_currency": { "type": "string", "nullable": true, "description": "`raw_amount` 的单位，在提供商报告该单位时提供。" } } } }, "counterparty_connections": { "type": "array", "description": "提供商将筛查地址归属到的实体。对于 Merkle Science，这些信息来自地址自身的所有者和用户标签，因此同一实体可能会出现两次，并且它们不携带资金流：`received_usd`、`sent_usd`、`received_hops` 和 `sent_hops` 均为 `null`，且 `percentage` 为 0。请勿在此根据 `risk_level` 或 `is_direct` 进行路由：请使用 `sanctions_hit`、`dominant_risk_category` 和 `risk_factors[].is_high_risk` 获取判定结果，并在 `source_of_funds`/`destination_of_funds` 中使用 `exposure_type` 判断直接性。", "items": { "type": "object", "properties": { "entity_name": { "type": "string", "nullable": true, "description": "归属实体名称。" }, "entity_type": { "type": "string", "nullable": true, "description": "提供商实体类型。" }, "entity_subtype": { "type": "string", "nullable": true, "description": "提供商实体子类型。" }, "risk_level": { "type": "string", "description": "小写且取决于提供商。对于 Merkle Science，它是地址自身的 0-5 级风险评级（`no_risk`、`low`、`medium_low`、`medium`、`high`、`critical`），当实体的类别为高风险时，该评级提升为 `high`；这不是该实体的独立评级。" }, "categories": { "type": "array", "items": { "type": "string" }, "description": "实体的归一化风险类别。" }, "received_usd": { "type": "number", "nullable": true, "description": "从实体收到的美元金额（服务商报告时）。" }, "sent_usd": { "type": "number", "nullable": true, "description": "发送给实体的美元金额（服务商报告时）。" }, "received_hops": { "type": "integer", "nullable": true, "description": "至接收方实体的跳数（当服务商报告时）。" }, "sent_hops": { "type": "integer", "nullable": true, "description": "至发送方实体的跳数（当服务商报告时）。" }, "percentage": { "type": "number", "description": "该地址的风险敞口占比（当提供商报告时）；否则为 0。" }, "is_direct": { "type": "boolean", "description": "对于 Merkle Science 始终为 `true`，其关联属于归属标识而非交易对手。" }, "country": { "type": "string", "nullable": true, "description": "实体所在的国家/地区（若已知）。" }, "provider_entity_id": { "type": "string", "nullable": true, "description": "服务商自身针对该实体的标识符。" } } } }, "network_nodes": { "type": "array", "items": { "type": "object" }, "description": "用于交易筛查的暴露图谱节点。在钱包筛查结果中为空。" }, "network_edges": { "type": "array", "items": { "type": "object" }, "description": "用于交易筛查的暴露图谱边。在钱包筛查结果中为空。" }, "sanctions_hit": { "type": "boolean", "description": "如果该地址存在直接或间接的制裁敞口，则为 true。" }, "pep_counterparty": { "type": "boolean", "description": "政治公众人物暴露情况。当无可用的 PEP 发现结果时为 `null`（由于目前没有任何提供商报告此项，今天的所有结果均为该值）；仅在筛查结果明确为阴性时为 `false`。切勿将 `null` 视为已完成的 PEP 检查。", "nullable": true }, "dominant_risk_category": { "type": "string", "nullable": true, "description": "权重最高的高风险类别，若无主导类别则为 `null`（例如 `sanctioned`、`mixer`、`stolen_funds`）。" }, "risk_factors": { "type": "array", "description": "`risk_score` 的排序解释：导致该判定的原因。数据源会根据自身模型对地址进行评分，且仅返回判定结果（Merkle Science 返回 0-5 的整数），因此仅凭该分数无法采取操作。按高风险优先排序，随后按流经各驱动因素的价值排序，最多保留五个影响最大的因素；`source_of_funds` 和 `destination_of_funds` 始终包含完整的明细。若 `risk_score` 较高但没有 `is_high_risk` 条目，则表示数据源未报告任何制裁或归属实体匹配，纯粹根据其自身的风险敞口模型对该地址进行了评级，`summary` 会对此进行明确说明。", "items": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "attribution", "exposure" ], "description": "`attribution` 是提供商对该地址本身的归属判定（其专属标签或集群）；`exposure` 则是其资金实际流向的位置。" }, "category": { "type": "string", "description": "归一化的风险类别，词汇表与暴露明细相同。" }, "label": { "type": "string", "description": "服务商自身针对动因的表述（例如 `Gambling / Crypto only`），这也是您在服务商控制台中看到的内容。" }, "entity_name": { "type": "string", "nullable": true, "description": "该驱动因素对应的归属实体，例如博彩网站或交易所。" }, "direction": { "type": "string", "enum": [ "incoming", "outgoing", "connected", "unknown", "attribution" ], "description": "资金流向，当驱动因素是地址自身的标签时为 `attribution`，或者当提供商未报告方向时为 `unknown`。" }, "exposure_type": { "type": "string", "enum": [ "direct", "indirect", "unknown", "attribution" ], "description": "`direct`（1 跳）或 `indirect`（多跳），`attribution` 表示地址自身的标签，当提供商未说明交易对手相距多少跳时为 `unknown`。将 `unknown` 视为未分类，而非 `direct`。" }, "amount_usd": { "type": "number", "format": "float", "nullable": true, "description": "归属于该驱动因素的美元价值。" }, "percentage": { "type": "number", "format": "float", "description": "该地址经筛查的总量占比（双向合计），不同于 `source_of_funds`/`destination_of_funds` 内部按方向归一化的 `percentage`。在整个列表中可比且可累加。" }, "is_high_risk": { "type": "boolean", "description": "该类别是否属于 Didit 认定为高风险的类别（`sanctioned`、`mixer`、`stolen_funds`、`ransomware`、`scam`、`darknet_market`、`terrorist_financing`、`child_exploitation`、`hacked_exchange`、`high_risk_exchange`、`seized_funds`）。" }, "description": { "type": "string", "description": "动因的单行展示，例如 `9.01% indirect outgoing exposure to Gambling / Crypto only (Example Gambling)`。" } } } }, "raw_response": { "type": "object", "additionalProperties": true, "description": "服务商自身的 payload。其格式因服务商而异，且可能随时更改：请读取规范化字段，而不是直接解析它。" }, "report_signature": { "type": "string", "description": "针对此确切结果的不透明 HMAC-SHA256 签名，作用域限定于您的应用。该字段本身无单独意义，请将未经修改且包含此字段的完整响应体重新发送至 `POST /v3/wallet-screening/pdf/` 以将其渲染为 PDF。如果缺失 `report_signature` 或在重新发送前修改了任何已签名字段（例如 `risk_score`、`severity`、`sanctions_hit`），PDF endpoint 将拒绝请求并返回 `400`。" } }, "required": [ "provider", "screening_type", "risk_score", "severity", "status", "summary", "wallet_address", "blockchain", "sanctions_hit", "dominant_risk_category", "source_of_funds", "destination_of_funds", "counterparty_connections", "report_signature" ] }, "NetworkRiskDisplay": { "type": "object", "properties": { "score": { "type": "integer", "description": "风险评分，0-100。" }, "band": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "分数所属的等级：高等级 >= 70，中等级 >= 40，否则为低等级。" }, "bar": { "type": "number", "format": "float", "description": "用于渲染风险条的 0-1 归一化值。" } } }, "NetworkNodeTag": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "color": { "type": "string", "nullable": true, "description": "对于 guard 标签为 null，其颜色 token 由渲染器控制。" }, "source": { "type": "string", "enum": [ "subject_tag", "session_tag", "transaction_tag", "signal_guard" ], "description": "标签的来源：用户/企业上的标签、此网络中会话上的标签、当事方所属交易上的标签，或信号防护条件（例如集线器、数据中心 IP）。" }, "category": { "type": "string", "enum": [ "customer", "quality" ], "nullable": true, "description": "customer 表示客户自定义标签，quality 表示信号质量防护标签。不适用时为 null。" } } }, "NetworkListItem": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "network_id": { "type": "string", "description": "易于阅读的组织内顺序 ID，例如 N-0001。" }, "name": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "active", "in_review", "resolved", "dismissed" ], "description": "网络生命周期状态。与网络内每个申请人的 outcome_status（approved/in_review/declined/not_completed）不同。" }, "risk": { "$ref": "#/components/schemas/NetworkRiskDisplay" }, "pattern_types": { "type": "array", "items": { "type": "string", "enum": [ "exact_same_device", "similar_device", "same_ip_address", "same_address", "similar_selfie_backgrounds", "similar_poa_documents", "same_document_number", "same_phone_number", "same_email" ] }, "description": "在此网络中检测到的聚集模式。" }, "signal_types": { "type": "array", "items": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] }, "description": "此网络中存在的不同信号类型。" }, "member_counts": { "type": "object", "description": "按类别统计的成员数量（例如总计、按 outcome_status 统计）。" }, "member_status": { "type": "object", "description": "按 outcome_status 细分的成员明细。" }, "signal_coverage": { "type": "object", "description": "该网络成员各 signal_type 的覆盖率。" }, "first_activity_at": { "type": "string", "format": "date-time", "nullable": true }, "last_activity_at": { "type": "string", "format": "date-time", "nullable": true } } }, "NetworkDetail": { "allOf": [ { "$ref": "#/components/schemas/NetworkListItem" }, { "type": "object", "properties": { "stats": { "type": "object", "description": "网络汇总统计信息（例如成员总数）。" }, "fraud_tags": { "type": "array", "items": { "type": "object" }, "description": "在网络上发现的欺诈模式标签。" }, "risk_signals": { "type": "object", "description": "风险信号摘要：residential_proxy_reuse、email_intelligence、phone_intelligence。" }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_by": { "type": "string", "nullable": true }, "review_reason": { "type": "string", "nullable": true } } } ], "properties": { "notes_count": { "type": "integer", "minimum": 0, "readOnly": true, "description": "本次调查中分析师私人备注的数量。" } } }, "NetworkGraphNode": { "type": "object", "description": "主体节点或信号节点，按类型区分。主体节点（kind: vendor_user | vendor_business | transaction_party）包含 id、kind、subject、node_status（approved | in_review | declined | not_completed）和 tags。信号节点（kind: signal）包含 id、kind、uuid、signal_type、subject_count、coverage、is_hub、is_datacenter_ip、is_high_collision_device、node_status（signal_active | signal_guarded）、tags、risk_evidence、first_seen_at 和 last_seen_at。", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "vendor_user", "vendor_business", "transaction_party", "signal" ] } } }, "NetworkGraphEdge": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "source": { "type": "string", "description": "主体节点 ID。" }, "target": { "type": "string", "description": "信号节点 ID。" }, "subject_kind": { "type": "string", "enum": [ "vendor_user", "vendor_business", "transaction_party" ] }, "signal_type": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] }, "confidence": { "type": "number", "format": "float", "description": "完全匹配为 1.0。" }, "observation_count": { "type": "integer" }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "NetworkGraph": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/NetworkDetail" }, "depth": { "type": "integer", "nullable": true, "description": "已应用的有效深度，无限制（depth=all）时为 null。" }, "truncated": { "type": "boolean", "description": "如果邻域因深度限制而被截断，则为 true。" }, "nodes": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkGraphNode" } }, "edges": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkGraphEdge" } }, "metrics": { "type": "object", "properties": { "node_count": { "type": "integer" }, "edge_count": { "type": "integer" }, "hub_signal_count": { "type": "integer" } } } } }, "NetworkMember": { "type": "object", "properties": { "subject": { "type": "object", "description": "该成员所代表的 vendor_user、vendor_business 或 transaction_party。" }, "outcome_status": { "type": "string", "description": "主体的验证/决策结果。" }, "node_status": { "type": "string", "enum": [ "approved", "in_review", "declined", "not_completed", "signal_active", "signal_guarded" ], "description": "对于成员行，此字段始终为以下主体结果值之一：approved、in_review、declined 或 not_completed。" }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkNodeTag" } }, "risk": { "$ref": "#/components/schemas/NetworkRiskDisplay" }, "signal_coverage": { "type": "object" }, "shared_infrastructure": { "type": "object" }, "joined_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "provenance": { "type": "object", "properties": { "session_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "business_session_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "transaction_ids": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } }, "NetworkSignal": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "signal_type": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] }, "subject_count": { "type": "integer" }, "coverage": { "type": "number", "format": "float" }, "is_hub": { "type": "boolean", "description": "当此信号关联了异常大量的当事方时为 True。" }, "is_datacenter_ip": { "type": "boolean" }, "is_high_collision_device": { "type": "boolean" }, "node_status": { "type": "string", "enum": [ "signal_active", "signal_guarded" ] }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkNodeTag" } }, "risk_evidence": { "type": "object" }, "first_seen_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "NetworkTimelineEvent": { "type": "object", "properties": { "event_type": { "type": "string", "description": "例如 network_detected、signal_observed、network_in_review、network_resolved、network_dismissed。" }, "occurred_at": { "type": "string", "format": "date-time", "nullable": true }, "label": { "type": "string" }, "metadata": { "type": "object" } } }, "NetworkMap": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/NetworkDetail" }, "convergence_count": { "type": "integer", "description": "成员汇聚的不同地址/位置点数量。" }, "countries": { "type": "array", "items": { "type": "string" } }, "points": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "country": { "type": "string", "nullable": true }, "country_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "latitude": { "type": "number", "format": "float", "nullable": true }, "longitude": { "type": "number", "format": "float", "nullable": true }, "observed_at": { "type": "string", "format": "date-time", "nullable": true } } } } } }, "EntityNetworkMembership": { "type": "object", "properties": { "network": { "$ref": "#/components/schemas/NetworkListItem" }, "subject": { "type": "object" }, "signal_types": { "type": "array", "items": { "type": "string", "enum": [ "ip_address", "device", "face", "document_number", "phone", "email", "address" ] } }, "signal_count": { "type": "integer" }, "joined_at": { "type": "string", "format": "date-time", "nullable": true }, "last_seen_at": { "type": "string", "format": "date-time", "nullable": true } } }, "RiskSignals": { "type": "object", "description": "您的应用所观测到的可选设备和网络上下文。所有字段均为可选。传入这些字段有助于为 Networks 中的跨会话匹配检测提供数据。", "properties": { "ip": { "type": "string", "format": "ip", "description": "观察到的终端用户的 IPv4 或 IPv6 地址。", "example": "192.0.2.1" }, "device_id": { "type": "string", "maxLength": 255, "description": "应用收集的稳定设备标识符（Android 为 `ANDROID_ID`，iOS 为 `identifierForVendor`）。" }, "device_platform": { "type": "string", "enum": [ "android", "ios", "ipados", "tvos", "web" ], "description": "终端用户设备的平台。" }, "device_model": { "type": "string", "maxLength": 255, "description": "您的应用报告的设备型号。" }, "os_version": { "type": "string", "maxLength": 64, "description": "操作系统版本。" }, "app_version": { "type": "string", "maxLength": 64, "description": "您的应用版本。" }, "user_agent": { "type": "string", "maxLength": 512, "description": "浏览器或应用的 user agent。" } } }, "PhoneRiskRequest": { "type": "object", "required": [ "phone_number" ], "properties": { "phone_number": { "type": "string", "maxLength": 20, "description": "待评分的电话号码。它将被验证并规范化为 E.164 格式。", "example": "+14155552671" }, "country_code": { "type": "string", "maxLength": 3, "description": "用于情报覆盖范围的可选 ISO 3166-1 alpha-2 或 alpha-3 国家/地区提示。", "example": "US" }, "signals": { "$ref": "#/components/schemas/RiskSignals" }, "vendor_data": { "type": "string", "description": "您为此请求提供的稳定引用。存储在 API 会话中并在响应中返回。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您的非敏感 JSON 元数据。存储在 API 会话中并在响应中原样返回。" }, "enable_social": { "type": "boolean", "default": false, "description": "为 true 时，还会查找该号码的社交足迹，即其注册所在的消息、社交、电子商务和职业平台。除此 endpoint 本身的价格外，每次请求按一个 `phone_social` 计费。", "example": true } } }, "EmailRiskRequest": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email", "description": "要进行评分的邮箱地址。", "example": "alice@example.com" }, "country_code": { "type": "string", "maxLength": 3, "description": "用于情报覆盖范围的可选 ISO 3166-1 alpha-2 或 alpha-3 国家/地区提示。", "example": "US" }, "signals": { "$ref": "#/components/schemas/RiskSignals" }, "vendor_data": { "type": "string", "description": "您为此请求提供的稳定引用。存储在 API 会话中并在响应中返回。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您的非敏感 JSON 元数据。存储在 API 会话中并在响应中原样返回。" }, "enable_social": { "type": "boolean", "default": false, "description": "为 true 时，还会查找该地址的社交足迹，即其注册所在的邮箱、社交、职业、电子商务和娱乐平台。除此 endpoint 本身的价格外，每次请求按一个 `email_social` 单位计费。", "example": true } } }, "IPRiskRequest": { "type": "object", "required": [ "ip_address" ], "properties": { "ip_address": { "type": "string", "format": "ip", "description": "要评分的 IPv4 或 IPv6 地址。", "example": "8.8.8.8" }, "claimed_country": { "type": "string", "maxLength": 3, "description": "用户或会话声明的可选 ISO 3166-1 alpha-2 或 alpha-3 国家/地区。用于计算 `country_mismatch`。", "example": "ESP" }, "user_agent": { "type": "string", "maxLength": 512, "description": "后端检测到的 User-Agent。作为请求上下文存储；不提供设备指纹功能。" }, "vendor_data": { "type": "string", "description": "您为此请求提供的稳定引用。存储在 API 会话中并在响应中返回。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您的非敏感 JSON 元数据。存储在 API 会话中并在响应中原样返回。" } } }, "RiskWarning": { "type": "object", "required": [ "feature", "risk", "log_type", "short_description", "long_description" ], "properties": { "feature": { "type": "string", "description": "产生该警告的功能。" }, "risk": { "type": "string", "description": "机器可读的风险代码。后续可能会随着时间推移添加新值。" }, "additional_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "特定风险的上下文，或 `null`。" }, "log_type": { "type": "string", "enum": [ "error", "warning", "information" ], "description": "决策规则所使用的严重程度。" }, "short_description": { "type": "string", "description": "易于阅读的单行摘要。" }, "long_description": { "type": "string", "description": "便于人类阅读的说明。" } } }, "RiskLifecycleEvent": { "type": "object", "required": [ "type", "timestamp", "details", "fee" ], "properties": { "type": { "type": "string", "description": "机器可读的事件类型。新值可能会随着时间推移而添加。" }, "timestamp": { "type": "string", "format": "date-time", "description": "事件发生的时间。" }, "details": { "type": "object", "nullable": true, "additionalProperties": true, "description": "特定事件的 payload，或为 `null`。" }, "fee": { "type": "number", "description": "此事件计费的美元金额。" } } }, "PhoneMatchItem": { "type": "object", "description": "您应用中使用了相同电话号码但具有不同 `vendor_data` 的另一个会话。", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "使用此电话号码的另一个验证的会话 id。" }, "session_number": { "type": "integer", "description": "该会话便于人类阅读的序号。" }, "vendor_data": { "type": "string", "nullable": true, "description": "该会话的 `vendor_data`。" }, "verification_date": { "type": "string", "description": "该会话的创建时间（`YYYY-MM-DDTHH:MM:SSZ`）。" }, "phone_number": { "type": "string", "description": "匹配的电话号码。" }, "status": { "type": "string", "description": "该会话的状态（例如 `Approved`、`Declined`、`In Progress`）。" }, "is_blocklisted": { "type": "boolean", "description": "电话号码是否在您应用的黑名单中。" }, "api_service": { "type": "string", "nullable": true, "description": "对于 API 类型的会话，为创建该会话的独立 API；对于常规验证会话为 `null`。" }, "source": { "type": "string", "description": "发现匹配的位置。通常为 `session`；通过组织名单条目命中的黑名单使用 `list_entry`。" } } }, "EmailMatchItem": { "type": "object", "description": "您应用中使用了相同邮箱地址但具有不同 `vendor_data` 的另一个会话。", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "使用此邮箱地址的另一个验证的会话 id。" }, "session_number": { "type": "integer", "description": "该会话便于人类阅读的序号。" }, "vendor_data": { "type": "string", "nullable": true, "description": "该会话的 `vendor_data`。" }, "verification_date": { "type": "string", "description": "该会话的创建时间（`YYYY-MM-DDTHH:MM:SSZ`）。" }, "email": { "type": "string", "description": "匹配的邮箱地址。" }, "status": { "type": "string", "description": "该会话的状态（例如 `Approved`、`Declined`、`In Progress`）。" }, "is_blocklisted": { "type": "boolean", "description": "该邮箱地址是否在您应用的黑名单中。" }, "api_service": { "type": "string", "nullable": true, "description": "对于 API 类型的会话，为创建该会话的独立 API；对于常规验证会话为 `null`。" }, "source": { "type": "string", "description": "发现匹配的位置。通常为 `session`；通过组织名单条目命中的黑名单使用 `list_entry`。" } } }, "PhoneIntelligence": { "type": "object", "description": "归一化的电话情报区块。仅在本次查询运行了情报附加组件时存在；存在时还会以相同值的 `enrichment` 别名提供。", "properties": { "score": { "type": "number", "nullable": true, "description": "归一化的 0-100 风险评分。分值越高风险越大。" }, "phone_type_risk": { "type": "string", "nullable": true, "description": "由评分推导出的 `Low`、`Medium` 或 `High`。" }, "phone_trust_index": { "type": "number", "nullable": true, "description": "分数的反向值，适用于偏好数值越高越好的仪表板。" }, "network_stability_index": { "type": "number", "nullable": true, "description": "线路网络的稳定性。" }, "is_disposable": { "type": "boolean", "nullable": true, "description": "当号码疑似一次性号码或虚拟号码时为 `true`。" }, "is_ported": { "type": "boolean", "nullable": true, "description": "当号码已更换运营商时为 `true`。" }, "is_recently_ported": { "type": "boolean", "nullable": true, "description": "当转网发生在近期时为 `true`。" }, "carrier_type": { "type": "string", "nullable": true, "description": "查询报告的线路分类（例如 `mobile`）。" }, "reason_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "信号的稳定 Didit 标识符，例如 `IR-5AC67A32`。不透明标识：可据此分组和过滤，请勿解析其内容。" }, "value": { "nullable": true, "description": "对于风险标记（例如 `voip`、`leaked`、`disposable`、`spam_trap`），为其对应的值：布尔值、等级或日期。对于计分原因代码则为 null。" }, "direction": { "type": "string", "enum": [ "risk", "trust" ], "description": "该信号是增加了风险还是提升了信任度。" }, "message": { "type": "string", "description": "信号的便于人类阅读的说明（英文）。" }, "impact_level": { "type": "string", "nullable": true, "description": "该信号对评分的影响强度，例如 `low`、`medium` 或 `high`。" } } }, "description": "解释评分的信号，每个信号包含一个固定的 Didit 代码、一个方向、一条消息和一个影响级别。新代码可能会随着时间推移而出现，因此请勿拒绝未知代码。" } } }, "EmailIntelligence": { "type": "object", "description": "归一化的邮箱情报区块。仅在该邮箱运行了情报附加组件时存在；存在时还会以相同值的 `enrichment` 别名提供。", "properties": { "score": { "type": "number", "nullable": true, "description": "归一化的 0-100 风险评分。分值越高风险越大。" }, "deliverable": { "type": "string", "nullable": true, "description": "可投递性等级（例如 `high`）。" }, "breach_risk_level": { "type": "string", "nullable": true, "description": "`Low`、`Medium` 或 `High`。" }, "breach_risk_index": { "type": "number", "nullable": true, "description": "泄露风险数值指数。" }, "is_recent_breach": { "type": "boolean", "nullable": true, "description": "当该地址出现在近期泄露事件中时为 `true`。" }, "is_frequent_breached": { "type": "boolean", "nullable": true, "description": "当该地址出现在多次泄露事件中时为 `true`。" }, "is_disposable": { "type": "boolean", "nullable": true, "description": "当域名属于一次性邮箱服务商时为 `true`。" }, "is_free_domain": { "type": "boolean", "nullable": true, "description": "当域名属于免费邮箱服务商时为 `true`。" }, "is_breached": { "type": "boolean", "nullable": true, "description": "当该地址出现在已知泄露事件中时为 `true`。" }, "no_of_breaches": { "type": "number", "nullable": true, "description": "包含该地址的已知泄露事件数量。" }, "reason_codes": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "description": "信号的稳定 Didit 标识符，例如 `IR-5AC67A32`。不透明标识：可据此分组和过滤，请勿解析其内容。" }, "value": { "nullable": true, "description": "对于风险标记（例如 `voip`、`leaked`、`disposable`、`spam_trap`），为其对应的值：布尔值、等级或日期。对于计分原因代码则为 null。" }, "direction": { "type": "string", "enum": [ "risk", "trust" ], "description": "该信号是增加了风险还是提升了信任度。" }, "message": { "type": "string", "description": "信号的便于人类阅读的说明（英文）。" }, "impact_level": { "type": "string", "nullable": true, "description": "该信号对评分的影响强度，例如 `low`、`medium` 或 `high`。" } } }, "description": "解释评分的信号，每个信号包含一个固定的 Didit 代码、一个方向、一条消息和一个影响级别。新代码可能会随着时间推移而出现，因此请勿拒绝未知代码。" } } }, "IPRiskResult": { "type": "object", "description": "IP 风险结果。如果查询未返回可用数据，各个丰富信息字段可为 `null`。", "required": [ "status", "threat" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review" ], "description": "当解析出的国家/地区与 `claimed_country` 冲突，或当地址与 VPN、Tor 或数据中心基础设施相关联时为 `In Review`。否则为 `Approved`。" }, "ip_address": { "type": "string", "nullable": true, "description": "已评分的地址。当没有丰富化数据源返回可用数据时为 `null`。" }, "ip_country": { "type": "string", "nullable": true, "description": "解析出的国家/地区名称。" }, "ip_country_code": { "type": "string", "nullable": true, "description": "解析出的国家/地区代码。请通过 `country_mismatch` 比较国家/地区，而不是自行比较原始国家/地区字符串。" }, "ip_state": { "type": "string", "nullable": true, "description": "解析出的州或地区。" }, "ip_city": { "type": "string", "nullable": true, "description": "解析出的城市。" }, "latitude": { "type": "number", "nullable": true, "description": "大致的网络地理位置，并非精确的设备位置。" }, "longitude": { "type": "number", "nullable": true, "description": "大致的网络地理位置，并非精确的设备位置。" }, "isp": { "type": "string", "nullable": true, "description": "为该地址提供服务的互联网服务提供商。" }, "organization": { "type": "string", "nullable": true, "description": "拥有该地址块的组织。" }, "is_vpn_or_tor": { "type": "boolean", "nullable": true, "description": "当该地址与 VPN 或 Tor 基础设施关联时为 `true`。" }, "is_data_center": { "type": "boolean", "nullable": true, "description": "当该地址属于主机托管或数据中心网络时为 `true`。" }, "time_zone": { "type": "string", "nullable": true, "description": "解析出的位置对应的时区。" }, "time_zone_offset": { "type": "string", "nullable": true, "description": "解析位置的 UTC 偏移量。" }, "asn_number": { "type": "number", "nullable": true, "description": "自治系统编号（ASN）。" }, "asn_organization": { "type": "string", "nullable": true, "description": "运营自治系统的组织。" }, "connection_type": { "type": "string", "nullable": true, "description": "连接分类（例如 `cellular`、`hosting`）。" }, "carrier": { "type": "string", "nullable": true, "description": "当地址位于移动网络上时的移动运营商。" }, "proxy_type": { "type": "string", "nullable": true, "description": "地址位于代理之后时的代理分类。" }, "claimed_country": { "type": "string", "nullable": true, "description": "您发送的 `claimed_country` 回显。" }, "country_mismatch": { "type": "boolean", "nullable": true, "description": "当解析出的国家/地区与 `claimed_country` 不一致时为 `true`。当无可用补充数据或未提供声明的国家/地区时为 `null`。" }, "threat": { "type": "object", "additionalProperties": true, "description": "来自数据增强源的自由格式网络威胁证据（例如 `is_proxy`、`is_tor`）。当没有可用的增强数据时为空对象。请将其视为诊断细节，而非稳定的接口约定。" } } }, "PhoneRiskResponse": { "type": "object", "required": [ "request_id", "status", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "为此请求创建的 API 会话 ID。如果您需要将结果与后续的 Webhook 或控制台活动关联，请将其与 `vendor_data` 一同存储。" }, "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "此 API 会话的最终决策。通常为 `Approved`；风险评估可能会产生 `In Review` 或 `Declined`。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，若未发送则为 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 回显，若未发送则为 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "此响应的时间戳。" }, "phone": { "type": "object", "description": "归一化的电话报告，与电话验证响应所使用的区块相同。", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "针对此电话号码的决策。对应顶级的 `status`。" }, "phone_number_prefix": { "type": "string", "description": "带前导 `+` 的国家/地区国际呼叫代码（例如 `+1`）。", "example": "+1" }, "phone_number": { "type": "string", "description": "不含国家/地区呼叫代码的国内号码。", "example": "4155552671" }, "full_number": { "type": "string", "description": "E.164 格式的完整号码。", "example": "+14155552671" }, "country_code": { "type": "string", "nullable": true, "description": "号码所在国家/地区的 ISO 3166-1 alpha-2 代码。", "example": "US" }, "country_name": { "type": "string", "description": "从 `country_code` 推导出的国家/地区全称。", "example": "United States" }, "carrier": { "type": "object", "nullable": true, "description": "当前为该号码提供服务的网络。当查询无法解析运营商时为 `null`。", "properties": { "name": { "type": "string", "description": "运营商名称。当查询无法识别时为空字符串。" }, "type": { "type": "string", "description": "查询报告的线路类型：`mobile`、`fixed_line`、`voip`、`isp`、`vpn`、`toll_free`、`premium_rate` 或类似类型。" } } }, "is_disposable": { "type": "boolean", "description": "当号码属于临时或一次性号码服务时为 `true`。" }, "is_virtual": { "type": "boolean", "description": "当线路类型为虚拟线路（`voip`、`isp` 或 `vpn`）时为 `true`。" }, "verification_method": { "type": "string", "nullable": true, "description": "底层验证的 OTP 渠道。对于绝不发送验证码的风险查询为 `null`。" }, "verification_attempts": { "type": "integer", "description": "此号码的一次性验证码发送次数。风险查询为 `0`。" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "该号码最后一次通过一次性验证码验证的时间。对于风险查询为 `null`。" }, "warnings": { "type": "array", "description": "为此请求记录的风险警告。无任何警告时为空数组。", "items": { "$ref": "#/components/schemas/RiskWarning" } }, "lifecycle": { "type": "array", "description": "请求的时间顺序审计记录。对于没有发送事件的风险查询，此项为空数组。", "items": { "$ref": "#/components/schemas/RiskLifecycleEvent" } }, "matches": { "type": "array", "description": "您应用中由不同用户（不同 `vendor_data`）使用相同电话号码的其他会话。最多 5 条记录。无匹配项时为空数组。", "items": { "$ref": "#/components/schemas/PhoneMatchItem" } }, "phone_intelligence": { "$ref": "#/components/schemas/PhoneIntelligence" }, "enrichment": { "$ref": "#/components/schemas/PhoneIntelligence" }, "phone_social": { "$ref": "#/components/schemas/PhoneSocialFootprint" } } } } }, "EmailRiskResponse": { "type": "object", "required": [ "request_id", "status", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "为此请求创建的 API 会话 ID。如果您需要将结果与后续的 Webhook 或控制台活动关联，请将其与 `vendor_data` 一同存储。" }, "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "此 API 会话的最终决策。通常为 `Approved`；风险评估可能会产生 `In Review` 或 `Declined`。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，若未发送则为 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 回显，若未发送则为 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "此响应的时间戳。" }, "email": { "type": "object", "description": "归一化的邮箱报告，与邮箱验证响应所使用的区块相同。", "required": [ "status", "email", "is_breached", "breaches", "is_disposable", "is_undeliverable" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review", "Declined" ], "description": "针对此邮箱地址的决策。对应顶级的 `status`。" }, "email": { "type": "string", "description": "已评分的地址。", "example": "alice@example.com" }, "is_breached": { "type": "boolean", "description": "该地址是否出现在已知的凭据泄露事件中。" }, "breaches": { "type": "array", "description": "包含此地址的最多 5 次最近已知数据泄露事件。当 `is_breached` 为 `false` 时为空数组。", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "数据泄露标识符。" }, "domain": { "type": "string", "description": "发生泄露的服务的域名。" }, "breach_date": { "type": "string", "format": "date", "description": "违规行为发生的日期。" }, "breach_emails_count": { "type": "integer", "description": "泄露事件中暴露的账户总数。" }, "description": { "type": "string", "description": "便于人类阅读的泄露事件描述（可能包含 HTML 标记）。" }, "logo_path": { "type": "string", "description": "发生数据泄露的服务徽标 URL。" }, "data_classes": { "type": "array", "items": { "type": "string" }, "description": "泄露的数据类别，采用 snake_case 格式（例如 `email_addresses`、`passwords`）。" }, "is_verified": { "type": "boolean", "description": "该泄露事件是否已被核实为真实存在。" } } } }, "is_disposable": { "type": "boolean", "description": "该域名是否属于一次性邮箱提供商。" }, "is_undeliverable": { "type": "boolean", "description": "该地址是否被判定为无法投递。" }, "verification_attempts": { "type": "integer", "description": "此地址的一次性验证码发送次数。风险查询为 `0`。" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "该地址上次通过一次性验证码验证的时间。对于风险查询为 `null`。" }, "warnings": { "type": "array", "description": "为此请求记录的风险警告。无任何警告时为空数组。", "items": { "$ref": "#/components/schemas/RiskWarning" } }, "lifecycle": { "type": "array", "description": "请求的时间顺序审计记录。对于没有发送操作的风险查询，此项为空数组。", "items": { "$ref": "#/components/schemas/RiskLifecycleEvent" } }, "matches": { "type": "array", "description": "您应用中由不同用户（不同 `vendor_data`）使用相同邮箱地址的其他会话。最多 5 条记录。无匹配项时为空数组。", "items": { "$ref": "#/components/schemas/EmailMatchItem" } }, "email_intelligence": { "$ref": "#/components/schemas/EmailIntelligence" }, "enrichment": { "$ref": "#/components/schemas/EmailIntelligence" }, "email_social": { "$ref": "#/components/schemas/EmailSocialFootprint" } } } } }, "IPRiskResponse": { "type": "object", "required": [ "request_id", "status", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "为此请求创建的 API 会话 ID。如果您需要将结果与后续的 Webhook 或控制台活动关联，请将其与 `vendor_data` 一同存储。" }, "status": { "type": "string", "enum": [ "Approved", "In Review" ], "description": "此 API 会话的决策：存在网络或国家/地区不匹配风险时为 `In Review`，否则为 `Approved`。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您发送的 `vendor_data` 回显，若未发送则为 `null`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 回显，若未发送则为 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "此响应的时间戳。" }, "ip": { "type": "object", "description": "IP 风险结果。如果查询未返回可用数据，各个丰富信息字段可为 `null`。", "required": [ "status", "threat" ], "properties": { "status": { "type": "string", "enum": [ "Approved", "In Review" ], "description": "当解析出的国家/地区与 `claimed_country` 冲突，或当地址与 VPN、Tor 或数据中心基础设施相关联时为 `In Review`。否则为 `Approved`。" }, "ip_address": { "type": "string", "nullable": true, "description": "已评分的地址。当没有丰富化数据源返回可用数据时为 `null`。" }, "ip_country": { "type": "string", "nullable": true, "description": "解析出的国家/地区名称。" }, "ip_country_code": { "type": "string", "nullable": true, "description": "解析出的国家/地区代码。请通过 `country_mismatch` 比较国家/地区，而不是自行比较原始国家/地区字符串。" }, "ip_state": { "type": "string", "nullable": true, "description": "解析出的州或地区。" }, "ip_city": { "type": "string", "nullable": true, "description": "解析出的城市。" }, "latitude": { "type": "number", "nullable": true, "description": "大致的网络地理位置，并非精确的设备位置。" }, "longitude": { "type": "number", "nullable": true, "description": "大致的网络地理位置，并非精确的设备位置。" }, "isp": { "type": "string", "nullable": true, "description": "为该地址提供服务的互联网服务提供商。" }, "organization": { "type": "string", "nullable": true, "description": "拥有该地址块的组织。" }, "is_vpn_or_tor": { "type": "boolean", "nullable": true, "description": "当该地址与 VPN 或 Tor 基础设施关联时为 `true`。" }, "is_data_center": { "type": "boolean", "nullable": true, "description": "当该地址属于主机托管或数据中心网络时为 `true`。" }, "time_zone": { "type": "string", "nullable": true, "description": "解析出的位置对应的时区。" }, "time_zone_offset": { "type": "string", "nullable": true, "description": "解析位置的 UTC 偏移量。" }, "asn_number": { "type": "number", "nullable": true, "description": "自治系统编号（ASN）。" }, "asn_organization": { "type": "string", "nullable": true, "description": "运营自治系统的组织。" }, "connection_type": { "type": "string", "nullable": true, "description": "连接分类（例如 `cellular`、`hosting`）。" }, "carrier": { "type": "string", "nullable": true, "description": "当地址位于移动网络上时的移动运营商。" }, "proxy_type": { "type": "string", "nullable": true, "description": "地址位于代理之后时的代理分类。" }, "claimed_country": { "type": "string", "nullable": true, "description": "您发送的 `claimed_country` 回显。" }, "country_mismatch": { "type": "boolean", "nullable": true, "description": "当解析出的国家/地区与 `claimed_country` 不一致时为 `true`。当无可用补充数据或未提供声明的国家/地区时为 `null`。" }, "threat": { "type": "object", "additionalProperties": true, "description": "来自数据增强源的自由格式网络威胁证据（例如 `is_proxy`、`is_tor`）。当没有可用的增强数据时为空对象。请将其视为诊断细节，而非稳定的接口约定。" } } } } }, "SocialFootprintPlatform": { "type": "object", "properties": { "platform": { "type": "string", "description": "平台标识符。", "example": "whatsapp" }, "category": { "type": "string", "description": "平台类别，例如 MESSAGING、SOCIAL_MEDIA、ECOMMERCE、PROFESSIONAL、EMAIL_PROVIDER。", "example": "MESSAGING" }, "scope": { "type": "string", "enum": [ "global", "local" ], "description": "全球平台为 `global`，特定区域平台为 `local`。", "example": "global" } } }, "SocialFootprintCategorySummary": { "type": "object", "properties": { "registered": { "type": "integer", "nullable": true, "description": "该类别中已确认注册的平台。", "example": 2 }, "ratio": { "type": "number", "format": "float", "nullable": true, "description": "该类别已检查平台中已注册的比例，0.0-1.0。", "example": 0.6667 } } }, "SocialFootprintProfile": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "个人资料名称（若平台公开）。" }, "photo": { "type": "string", "nullable": true, "description": "个人资料照片 URL（若平台公开）。" }, "about": { "type": "string", "nullable": true, "description": "个人资料简介/生平文本（若平台公开）。" }, "privacy_status": { "type": "string", "nullable": true, "enum": [ "PUBLIC", "PRIVATE", null ], "description": "个人资料公开范围（若平台公开）。" }, "business_account": { "type": "boolean", "nullable": true, "description": "该资料是否为企业账户（若平台提供该信息）。" } } }, "PhoneSocialFootprint": { "type": "object", "nullable": true, "description": "电话号码的社交足迹：其注册的在线平台。仅当设置了 `enable_social` 且检查完成时才会出现。若未返回对应数据，各计数项可能为 null。`profiles_registered: 0` 表示已检查相关平台且未在任何平台上发现该电话号码，这是一个有效的计费结果，也是合成身份的常见信号。", "properties": { "profiles_registered": { "type": "integer", "nullable": true, "description": "已确认该电话号码已注册的平台。", "example": 5 }, "profiles_checked": { "type": "integer", "nullable": true, "description": "已评估注册情况的平台。", "example": 14 }, "names_found": { "type": "integer", "nullable": true, "description": "返回了关联姓名的平台。", "example": 0 }, "photos_found": { "type": "integer", "nullable": true, "description": "返回了个人资料头像的平台。", "example": 0 }, "communication_breadth": { "type": "integer", "nullable": true, "description": "检测到存在活动的通信平台。", "example": 2 }, "digital_footprint_diversity": { "type": "integer", "nullable": true, "description": "检测到存在记录的不同平台类别。", "example": 5 }, "digital_sophistication_index": { "type": "integer", "nullable": true, "description": "综合数字成熟度指标，0-10。", "example": 5 }, "engagement_depth_index": { "type": "integer", "nullable": true, "description": "个人资料丰富度指标，0-10。", "example": 3 }, "subscription_affordability_index": { "type": "integer", "nullable": true, "description": "免费与付费平台混合比例，0-10。", "example": 2 }, "free_platforms": { "type": "integer", "nullable": true, "description": "在免费平台上的注册数。", "example": 4 }, "full_paid_platforms": { "type": "integer", "nullable": true, "description": "在完全付费平台上的注册数。", "example": 0 }, "partial_paid_platforms": { "type": "integer", "nullable": true, "description": "在免费增值平台上的注册数。", "example": 1 }, "whatsapp_profile_completeness": { "type": "string", "nullable": true, "enum": [ "Basic", "Partial", "Complete", "Not Present", null ], "description": "WhatsApp 资料的完整性。仅限电话；邮箱为 null。", "example": "Partial" }, "registered_platforms": { "type": "array", "description": "已确认注册的平台。", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "not_registered_platforms": { "type": "array", "description": "检查结果为阴性的平台。", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "categories": { "type": "object", "description": "每个平台类别的注册数量和比例。", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintCategorySummary" } }, "profiles": { "type": "object", "description": "各平台个人资料详情，以平台为键（在平台公开这些信息时返回）。", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintProfile" } } } }, "EmailSocialFootprint": { "type": "object", "nullable": true, "description": "邮箱地址的社交足迹：其注册的在线平台。仅当设置了 `enable_social` 且检查完成时才会出现。若未返回对应数据，各计数项可能为 null。`profiles_registered: 0` 表示已检查相关平台且未在任何平台上发现该邮箱地址，这是一个有效的计费结果，也是合成身份的常见信号。", "properties": { "profiles_registered": { "type": "integer", "nullable": true, "description": "已确认该邮箱地址已注册的平台。", "example": 5 }, "profiles_checked": { "type": "integer", "nullable": true, "description": "已评估注册情况的平台。", "example": 14 }, "names_found": { "type": "integer", "nullable": true, "description": "返回了关联姓名的平台。", "example": 0 }, "photos_found": { "type": "integer", "nullable": true, "description": "返回了个人资料头像的平台。", "example": 0 }, "communication_breadth": { "type": "integer", "nullable": true, "description": "检测到存在活动的通信平台。", "example": 2 }, "digital_footprint_diversity": { "type": "integer", "nullable": true, "description": "检测到存在记录的不同平台类别。", "example": 5 }, "digital_sophistication_index": { "type": "integer", "nullable": true, "description": "综合数字成熟度指标，0-10。", "example": 5 }, "engagement_depth_index": { "type": "integer", "nullable": true, "description": "个人资料丰富度指标，0-10。", "example": 3 }, "subscription_affordability_index": { "type": "integer", "nullable": true, "description": "免费与付费平台混合比例，0-10。", "example": 2 }, "free_platforms": { "type": "integer", "nullable": true, "description": "在免费平台上的注册数。", "example": 4 }, "full_paid_platforms": { "type": "integer", "nullable": true, "description": "在完全付费平台上的注册数。", "example": 0 }, "partial_paid_platforms": { "type": "integer", "nullable": true, "description": "在免费增值平台上的注册数。", "example": 1 }, "whatsapp_profile_completeness": { "type": "string", "nullable": true, "enum": [ "Basic", "Partial", "Complete", "Not Present", null ], "description": "WhatsApp 资料的完整性。仅限电话；邮箱为 null。", "example": "Partial" }, "registered_platforms": { "type": "array", "description": "已确认注册的平台。", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "not_registered_platforms": { "type": "array", "description": "检查结果为阴性的平台。", "items": { "$ref": "#/components/schemas/SocialFootprintPlatform" } }, "categories": { "type": "object", "description": "每个平台类别的注册数量和比例。", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintCategorySummary" } }, "profiles": { "type": "object", "description": "各平台个人资料详情，以平台为键（在平台公开这些信息时返回）。", "additionalProperties": { "$ref": "#/components/schemas/SocialFootprintProfile" } } } }, "KYBRegistryAddress": { "type": "object", "description": "登记机构声明的地址，对于每个国家/地区和登记来源均采用相同格式。每个键始终存在；登记机构未公布的部分为 null。", "properties": { "type": { "type": "string", "nullable": true, "description": "小写形式的地址类型：注册办事处为 `registered`；其他类型按登记处的命名方式（例如 `postal`、`office`）。当登记处未说明该地址是什么类型时为 `null`。" }, "address": { "type": "string", "description": "单行格式的完整地址。每个地址中始终都提供该完整地址。" }, "street": { "type": "string", "nullable": true, "description": "街道与门牌号。" }, "city": { "type": "string", "nullable": true, "description": "城市或地区。" }, "postal_code": { "type": "string", "nullable": true, "description": "邮政编码。" }, "region": { "type": "string", "nullable": true, "description": "地区、州或省。" }, "country_code": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 国家/地区代码。" }, "description": { "type": "string", "nullable": true, "description": "登记处针对该地址自有的标签（如有）。" } }, "required": [ "type", "address", "street", "city", "postal_code", "region", "country_code", "description" ] }, "KYBRegistryIndustry": { "type": "object", "description": "登记机构对企业进行分类的经营活动，对于每个国家/地区和登记来源均采用相同格式。", "properties": { "code": { "type": "string", "nullable": true, "description": "公司登记载明的活动代码（例如 `73110`）。" }, "description": { "type": "string", "nullable": true, "description": "活动标签（若公司登记已发布）。" }, "scheme": { "type": "string", "nullable": true, "description": "分类体系，无论哪个来源报告，每个体系对应一个名称：`UK SIC 2007`、`US SIC`、`NACE Rev. 2`、`NACE Rev. 2.1`、`NAF Rev. 2`、`CNAE`、`SBI`、`NOGA 2008`、`CAE Rev. 4`、`Canada SIC 1977`；其他国家体系保留登记机构自身的名称。当登记机构未指明体系名称时为 Null。" }, "is_primary": { "type": "boolean", "description": "如果是公司的主要业务活动，则为 true。列表非空时恰好有一项为主活动。" } }, "required": [ "code", "description", "scheme", "is_primary" ] }, "KYBRegistryShareholding": { "type": "object", "nullable": true, "description": "所有人持有的权益，对所有国家/地区和登记来源采用相同的结构。当登记来源未声明持股时为 Null。区间（例如英国 PSC 的 25-50%）不属于持股权益：`percentage` 为 null，区间保留在 `ownership_min_shares` / `ownership_max_shares` 中。", "properties": { "share_class": { "type": "string", "nullable": true, "description": "登记机构命名的股份类别或类型。" }, "number_of_shares": { "type": "number", "nullable": true, "description": "持有的股份数量。" }, "currency": { "type": "string", "nullable": true, "description": "以下数值对应的 ISO 4217 货币。" }, "nominal_value": { "type": "number", "nullable": true, "description": "每股面值。" }, "total_value": { "type": "number", "nullable": true, "description": "持仓总价值。" }, "percentage": { "type": "number", "nullable": true, "description": "以百分比表示的精确持股比例，精确到小数点后四位。" } }, "required": [ "share_class", "number_of_shares", "currency", "nominal_value", "total_value", "percentage" ] }, "KYBRegistryOwnership": { "type": "object", "description": "股权结构（股东 / UBO）等级的结果，对所有国家/地区和登记册来源采用相同的结构。", "properties": { "status": { "type": "string", "nullable": true, "enum": [ "not_requested", "pending", "delivered", "not_held", "unavailable", null ], "description": "当登记处发布股权结构时为 `delivered`；当股权登记处已响应且完全未列出该企业时为 `not_held`（参见 `unavailable_reason`）；当由于任何其他原因未提供股权结构数据时为 `unavailable`（参见 `unavailable_reason`）；当登记处仍在获取数据时为 `pending`；对于 Basic 等级为 `not_requested`。" }, "tier_requested": { "type": "string", "nullable": true, "enum": [ "basic", "shareholders", "ubo", null ], "description": "工作流订购的等级。" }, "tier_delivered": { "type": "string", "nullable": true, "enum": [ "basic", "shareholders", "ubo", null ], "description": "登记机构交付（且计费）的等级。仅返回直接股东的 UBO 请求为 `shareholders`。" }, "unavailable_reason": { "type": "string", "nullable": true, "enum": [ "no_owners_on_record", "no_natural_person_owner", "ownership_section_unavailable", "company_not_found", "ambiguous_company_match", "missing_registration_number", "entity_type_not_covered", "provider_unavailable", "other", null ], "description": "所请求的股权结构等级未能交付的原因。除非 `status` 为 `unavailable` 或 `pending`，否则为 null。" }, "direct_ownership_complete": { "type": "boolean", "nullable": true, "description": "当直接股东申报的持股比例总和等于 100%（允许 1 个百分点的四舍五入误差）时为 true；否则为 false；未提供股权结构或未申报持股比例时为 null。" }, "unresolved": { "type": "array", "description": "登记处无法解析的股权链部分，例如记录中直接所有者之上不存在集团架构。", "items": { "type": "object", "properties": { "reason": { "type": "string" }, "section": { "type": "string", "nullable": true } } } } }, "required": [ "status", "tier_requested", "tier_delivered", "unavailable_reason", "direct_ownership_complete", "unresolved" ] }, "KYBRegistryData": { "type": "object", "nullable": true, "description": "Didit 为该企业标准化的公司登记详情：股权结构结果（`ownership_error`、`section_errors`、`ubo_resolution`、`lite_enrichment`）、使用 update-data 所做的更正，以及没有专属字段的公司登记事实。它绝不会携带登记来源自身的记录。每个键均为可选，且仅在企业具有相应值时才存在；可能会添加新键。对于规范字段（`addresses`、`industries`、`ownership`、`beneficial_owners[].shareholding`）涵盖的任何内容，请直接读取这些规范字段。", "properties": { "company_name": { "type": "string", "description": "在控制台中更正后的企业名称。" }, "registration_number": { "type": "string", "description": "公司登记或控制台更正注明的注册号。" }, "country_code": { "type": "string", "description": "登记处或控制台更正所声明的注册国家/地区。" }, "region": { "type": "string", "description": "注册的地区或州/省。" }, "incorporation_date": { "type": "string", "description": "注册成立日期（ISO 8601）。" }, "registration_date": { "type": "string", "description": "公司登记注明的注册日期（ISO 8601，独立于成立日期时提供）。" }, "dissolution_date": { "type": "string", "description": "注销日期（ISO 8601），由登记机构提供时包含。" }, "tax_number": { "type": "string", "description": "税号。" }, "vat_number": { "type": "string", "description": "增值税号。" }, "legal_address": { "type": "string", "description": "在控制台中更正后的法定地址。" }, "registered_address": { "type": "string", "description": "登记机构列明的注册地址。" }, "company_type": { "type": "string", "description": "法律形式。" }, "registry_status": { "type": "string", "description": "企业在公司登记的状态。" }, "verification_status": { "type": "string", "description": "验证状态。" }, "alternative_names": { "type": "string", "description": "该公司当前或曾经使用的其他商业名称。" }, "nature_of_business": { "type": "string", "description": "活动描述。" }, "registered_capital": { "type": "string", "description": "印示的注册资本。" }, "registered_capital_amount": { "type": "string", "description": "注册资本金额，以十进制字符串表示。" }, "registered_capital_currency": { "type": "string", "description": "注册资本货币（ISO 4217）。" }, "website": { "type": "string", "description": "网站。" }, "email": { "type": "string", "description": "联系邮箱。" }, "phone": { "type": "string", "description": "联系电话。" }, "legal_entity_identifier": { "type": "string", "description": "全球法人机构识别编码（LEI）。" }, "location_of_registration": { "type": "string", "description": "注册地。" }, "control_scheme": { "type": "string", "description": "公司登记提供该信息时的治理方案。" }, "ownership_error": { "type": "string", "enum": [ "no_owners_on_record", "no_natural_person_owner", "ownership_section_unavailable", "company_not_found", "ambiguous_company_match", "missing_registration_number", "entity_type_not_covered", "provider_unavailable", "other" ], "description": "所请求的股权结构等级未能交付的原因，代码与 `ownership.unavailable_reason` 相同。`no_owners_on_record`（登记机构已响应但未列出任何所有人）与 `ownership_section_unavailable`（登记机构未返回股权结构部分）是不同的结果。" }, "section_errors": { "type": "object", "description": "公司登记未返回的板块，以板块（`officers`、`shareholders`、`group_structure`）为键。此处列出的板块从未投递过：其旁的空列表并不表示关于该企业的任何信息。", "additionalProperties": { "$ref": "#/components/schemas/KYBRegistrySectionError" } }, "ubo_resolution": { "$ref": "#/components/schemas/KYBRegistryUboResolution" }, "lite_enrichment": { "$ref": "#/components/schemas/KYBRegistryLiteEnrichment" }, "registry_metadata": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] }, "description": "公司登记处针对该企业自有的原始字段，以登记处命名为键，作为普通值返回（旧版记录）。仅包含审核确认为登记事实的字段。" }, "registry_sources": { "type": "array", "description": "读取该记录的官方登记册（历史遗留记录）。未标明其他来源名称。", "items": { "$ref": "#/components/schemas/KYBRegistrySource" } }, "previous_names": { "type": "array", "items": { "type": "string" }, "description": "企业以往注册所使用的名称（历史记录）。" }, "parent_companies": { "type": "array", "items": { "type": "string" }, "description": "登记处列出的母公司（历史记录）。" }, "documents_available": { "type": "integer", "description": "登记处为该公司提供的备案记录数量（历史记录）。" } } }, "KYBRegistryGroupCompany": { "type": "object", "description": "根据公司登记身份确定的企业集团所属公司。", "properties": { "name": { "type": "string", "nullable": true, "description": "企业名称。" }, "country_code": { "type": "string", "nullable": true, "description": "注册国家/地区。" }, "registration_number": { "type": "string", "nullable": true, "description": "注册号。" } }, "required": [ "name", "country_code", "registration_number" ] }, "KYBRegistryUboResolution": { "type": "object", "description": "UBO 层级遍历公司上层股权结构链的方式。", "properties": { "parent_chain": { "type": "array", "description": "从最终母公司到该公司的企业母实体层级。", "items": { "$ref": "#/components/schemas/KYBRegistryGroupCompany" } }, "subsidiaries": { "type": "array", "description": "企业集团内直接隶属于该企业的下级公司。", "items": { "$ref": "#/components/schemas/KYBRegistryGroupCompany" } }, "unresolved": { "type": "array", "description": "登记处无法解析的股权链部分（与 `ownership.unresolved` 条目相同）。", "items": { "type": "object", "properties": { "reason": { "type": "string", "description": "原因，例如 `no_group_structure_on_record`、`selected_company_not_in_group_structure` 或 `section_error`。" }, "section": { "type": "string", "nullable": true, "description": "相关的部分，例如 `group_structure`。" } }, "required": [ "reason", "section" ] } } }, "required": [ "parent_chain", "subsidiaries", "unresolved" ] }, "KYBRegistrySectionError": { "type": "object", "description": "公司登记未返回的部分。", "properties": { "status_code": { "type": "integer", "nullable": true, "description": "登记机关针对该板块返回的状态。" } }, "required": [ "status_code" ] }, "KYBRegistryLiteEnrichment": { "type": "object", "description": "由该国家/地区的其他登记数据源填充的空白 Lite 档案字段。数据源名称未公开。", "properties": { "fields": { "type": "array", "items": { "type": "string" }, "description": "已填写的企业字段。" }, "people_added": { "type": "integer", "description": "添加的高管或所有者数量。" } }, "required": [ "fields", "people_added" ] }, "KYBRegistrySource": { "type": "object", "description": "读取该记录的官方登记册。仅列出官方政府登记册、监管机构和官方标识符系统；忽略任何其他来源。", "properties": { "name": { "type": "string", "description": "登记机构名称，例如 `UK Companies House`。" }, "source_type": { "type": "string", "enum": [ "official" ], "description": "始终为 `official`。" } }, "required": [ "name", "source_type" ] }, "KYBOwnershipStructure": { "type": "object", "nullable": true, "description": "登记处证明的股权结构表，以交付股权结构等级时的状态为准：直接 `shareholders` 和 `beneficial_owners`。当登记处未证明任何股权结构时为 null。它从不携带登记处来源本身的行；如需获取当前记录，请读取 `company.beneficial_owners` 和 `company.ownership`。", "properties": { "shareholders": { "type": "array", "items": { "$ref": "#/components/schemas/KYBOwnershipStructureOwner" } }, "beneficial_owners": { "type": "array", "items": { "$ref": "#/components/schemas/KYBOwnershipStructureOwner" } } }, "required": [ "shareholders", "beneficial_owners" ] }, "KYBOwnershipStructureOwner": { "type": "object", "description": "股权结构快照中的一个所有者：与 `company.beneficial_owners[]` 具有相同的登记身份与持股份额，以及其规范化的 `shareholding`。", "properties": { "name": { "type": "string", "nullable": true, "description": "登记处注明的所有者名称。" }, "first_name": { "type": "string", "nullable": true, "description": "自然人的名字（当公司登记注明时）。" }, "last_name": { "type": "string", "nullable": true, "description": "自然人的姓氏，当公司登记有明确载明时提供。" }, "date_of_birth": { "type": "string", "nullable": true, "description": "公司登记处公布时的出生日期（ISO 8601）。" }, "country_of_birth": { "type": "string", "nullable": true, "description": "出生国家/地区（若登记处公布）。" }, "company_name": { "type": "string", "nullable": true, "description": "企业名称，适用于企业所有者。" }, "registration_number": { "type": "string", "nullable": true, "description": "企业所有者的注册号。" }, "entity_type": { "type": "string", "nullable": true, "enum": [ "person", "company", null ], "description": "所有者是自然人还是公司。" }, "nationality": { "type": "string", "nullable": true, "description": "登记处注明的国籍。" }, "designation": { "type": "string", "nullable": true, "description": "登记册上载明的所有人头衔或角色。" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "直接持有人为 `shareholder`，实际受益人为 `ubo`。" }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "持股比例下限，以百分比表示（对于确定比例，其值等于上限）。" }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "持股比例上限，以百分比表示。" }, "voting_min_shares": { "type": "string", "nullable": true, "description": "投票权下限，以百分比表示。" }, "voting_max_shares": { "type": "string", "nullable": true, "description": "投票权上限，以百分比表示。" }, "appointment_date": { "type": "string", "nullable": true, "description": "持股或任命开始的日期（ISO 8601）。" }, "is_active": { "type": "boolean", "nullable": true, "description": "对于前所有者为 False。" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } }, "required": [ "name", "first_name", "last_name", "date_of_birth", "country_of_birth", "company_name", "registration_number", "entity_type", "nationality", "designation", "roles", "ownership_min_shares", "ownership_max_shares", "voting_min_shares", "voting_max_shares", "appointment_date", "is_active", "shareholding" ] }, "DigitalIdWalletApiWalletVerificationError": { "type": "object", "properties": { "error": { "type": "string", "description": "稳定的机器可读代码，例如 wallet_unavailable。" }, "detail": { "type": "string" } }, "required": [ "detail", "error" ] }, "DigitalIdWalletApiWalletVerificationStartForbidden": { "oneOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiClientCredentialsForbiddenErrorMessage" }, { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" } ] }, "DigitalIdWalletApiClientCredentialsForbiddenErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Forbidden - User doesn't have permission" } } }, "DigitalIdWalletApiWalletVerificationStartBadRequest": { "oneOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationError" }, { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationFieldErrors" } ] }, "DigitalIdWalletApiWalletVerificationFieldErrors": { "type": "object", "description": "请求验证错误：每个被拒绝的字段及其消息。", "additionalProperties": { "type": "array", "items": { "type": "string" } } }, "DigitalIdWalletApiWalletVerificationResponse": { "type": "object", "description": "单次独立钱包验证，正如每个钱包 endpoint 返回的结果一样。", "properties": { "request_id": { "type": "string", "format": "uuid" }, "wallet_verification": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResult" }, "vendor_data": { "type": "string", "nullable": true }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "启动时发送的元数据对象，或 null。" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "created_at", "metadata", "request_id", "vendor_data", "wallet_verification" ] }, "DigitalIdWalletApiWalletVerificationResult": { "type": "object", "properties": { "wallet": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWallet" } ], "readOnly": true }, "country": { "type": "string" }, "status": { "type": "string", "description": "待处理时为未完成，随后为已通过（已核验）或已拒绝。" }, "outcome": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletVerificationResultOutcomeEnum" }, "error": { "type": "string", "nullable": true, "readOnly": true }, "interaction": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiInteractionEnum" } ], "readOnly": true }, "simulated": { "type": "boolean", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time" }, "next_action": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletNextAction" } ], "nullable": true, "readOnly": true }, "identity": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletIdentity" } ], "nullable": true, "readOnly": true }, "attributes": { "type": "object", "additionalProperties": {}, "nullable": true, "readOnly": true }, "level_of_assurance": { "type": "string", "nullable": true }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "signature_valid": { "type": "boolean", "nullable": true, "description": "凭证签名验证通过后为 true；模拟凭证为 null。" }, "credential_type": { "type": "string", "nullable": true } }, "required": [ "attributes", "country", "credential_type", "error", "expires_at", "identity", "interaction", "level_of_assurance", "next_action", "outcome", "signature_valid", "simulated", "status", "verified_at", "wallet" ] }, "DigitalIdWalletApiWalletIdentity": { "type": "object", "properties": { "full_name": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "nationality": { "type": "string", "nullable": true, "description": "ISO3 国籍，仅在钱包明确声明时提供（绝不进行推断）。" }, "issuing_state": { "type": "string", "description": "签发该身份的方案所属的 ISO3 国家/地区。" } }, "required": [ "date_of_birth", "first_name", "full_name", "issuing_state", "last_name", "nationality" ] }, "DigitalIdWalletApiWalletNextAction": { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletNextActionTypeEnum" } ], "description": "redirect：将用户浏览器重定向至 url。confirm_in_app：向用户显示 verification_code，用户核对该验证码与其钱包应用中的代码一致后在应用内确认；随后进行轮询。request_digital_credential：在您最初发起流程的源上通过用户手势调用 digital_credentials.request 请求钱包，然后将返回的内容发送至 POST .../verifications/{request_id}/response/。\n\n* `redirect` - redirect\n* `confirm_in_app` - confirm_in_app\n* `request_digital_credential` - request_digital_credential" }, "url": { "type": "string", "format": "uri", "description": "仅限 redirect：用户使用钱包登录的页面。" }, "digital_credentials": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiWalletDigitalCredentialsRequest" } ], "description": "仅限 request_digital_credential：传递给钱包的请求内容。" }, "verification_code": { "type": "string", "description": "仅限 confirm_in_app：钱包应用上同步显示的 4 位比对码。" }, "poll_interval_seconds": { "type": "integer", "description": "仅限 confirm_in_app：调用 POST .../verifications/{request_id}/poll/ 以获取即时反馈的频率。Didit 还会在后台轮询待处理的登录，因此即使您不进行轮询，Webhook 也会报告结果。" } }, "required": [ "type" ] }, "DigitalIdWalletApiWalletNextActionTypeEnum": { "enum": [ "redirect", "confirm_in_app", "request_digital_credential" ], "type": "string", "description": "* `redirect` - 重定向\n* `confirm_in_app` - 应用内确认\n* `request_digital_credential` - 请求数字凭证" }, "DigitalIdWalletApiInteractionEnum": { "enum": [ "redirect", "in_app", "digital_credentials" ], "type": "string", "description": "* `redirect` - 重定向\n* `in_app` - 应用内\n* `digital_credentials` - 数字凭证" }, "DigitalIdWalletApiWalletVerificationResultOutcomeEnum": { "enum": [ "pending", "verified", "cancelled", "timeout", "failed" ], "type": "string", "description": "* `pending` - 待处理\n* `verified` - 已验证\n* `cancelled` - 用户已取消\n* `timeout` - 已超时\n* `failed` - 已失败" }, "DigitalIdWalletApiWallet": { "type": "object", "properties": { "id": { "type": "string", "description": "钱包的目录 ID，例如 bankid_se。" }, "name": { "type": "string" }, "issuing_authority": { "type": "string", "nullable": true } }, "required": [ "id", "issuing_authority", "name" ] }, "DigitalIdWalletApiEudiWalletVerificationStartRequest": { "type": "object", "description": "发起 EUDI Wallet 验证（AUT, BEL, BGR, HRV, CYP, CZE, DNK, EST, FIN, FRA, DEU, GRC, HUN, IRL, ITA, LVA, LTU, LUX, MLT, NLD, POL, PRT, ROU, SVK, SVN, ESP, SWE, ISL, LIE, NOR）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiEudiWalletVerificationStartCountryEnum" } ], "description": "EUDI Wallet 身份的 ISO 3166-1 alpha-3 国家/地区代码。\n\n* `AUT` - AUT\n* `BEL` - BEL\n* `BGR` - BGR\n* `HRV` - HRV\n* `CYP` - CYP\n* `CZE` - CZE\n* `DNK` - DNK\n* `EST` - EST\n* `FIN` - FIN\n* `FRA` - FRA\n* `DEU` - DEU\n* `GRC` - GRC\n* `HUN` - HUN\n* `IRL` - IRL\n* `ITA` - ITA\n* `LVA` - LVA\n* `LTU` - LTU\n* `LUX` - LUX\n* `MLT` - MLT\n* `NLD` - NLD\n* `POL` - POL\n* `PRT` - PRT\n* `ROU` - ROU\n* `SVK` - SVK\n* `SVN` - SVN\n* `ESP` - ESP\n* `SWE` - SWE\n* `ISL` - ISL\n* `LIE` - LIE\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "country", "return_url" ] }, "DigitalIdWalletApiDeviceEnum": { "enum": [ "same_device", "cross_device" ], "type": "string", "description": "* `same_device` - 同一设备\n* `cross_device` - 跨设备" }, "DigitalIdWalletApiEudiWalletVerificationStartCountryEnum": { "enum": [ "AUT", "BEL", "BGR", "HRV", "CYP", "CZE", "DNK", "EST", "FIN", "FRA", "DEU", "GRC", "HUN", "IRL", "ITA", "LVA", "LTU", "LUX", "MLT", "NLD", "POL", "PRT", "ROU", "SVK", "SVN", "ESP", "SWE", "ISL", "LIE", "NOR" ], "type": "string", "description": "* `AUT` - AUT\n* `BEL` - BEL\n* `BGR` - BGR\n* `HRV` - HRV\n* `CYP` - CYP\n* `CZE` - CZE\n* `DNK` - DNK\n* `EST` - EST\n* `FIN` - FIN\n* `FRA` - FRA\n* `DEU` - DEU\n* `GRC` - GRC\n* `HUN` - HUN\n* `IRL` - IRL\n* `ITA` - ITA\n* `LVA` - LVA\n* `LTU` - LTU\n* `LUX` - LUX\n* `MLT` - MLT\n* `NLD` - NLD\n* `POL` - POL\n* `PRT` - PRT\n* `ROU` - ROU\n* `SVK` - SVK\n* `SVN` - SVN\n* `ESP` - ESP\n* `SWE` - SWE\n* `ISL` - ISL\n* `LIE` - LIE\n* `NOR` - NOR" }, "DigitalIdWalletApiConnectidWalletVerificationStartRequest": { "type": "object", "description": "发起 ConnectID 验证（AUS）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum" } ], "default": "AUS", "description": "ConnectID 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 AUS，即其唯一支持的国家/地区。\n\n* `AUS` - AUS" }, "authorisation_server_id": { "type": "string", "minLength": 1, "description": "使用 ConnectID 银行选择器选中的授权服务器 ID。沙盒环境默认为 Mock Bank A。", "maxLength": 36 }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiConnectidWalletVerificationStartCountryEnum": { "enum": [ "AUS" ], "type": "string", "description": "* `AUS` - AUS" }, "DigitalIdWalletApiAudkenniWalletVerificationStartRequest": { "type": "object", "description": "开始 Auðkenni 验证（ISL）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum" } ], "default": "ISL", "description": "Auðkenni 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 ISL，即其唯一支持的国家/地区。\n\n* `ISL` - ISL" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiAudkenniWalletVerificationStartCountryEnum": { "enum": [ "ISL" ], "type": "string", "description": "* `ISL` - ISL" }, "DigitalIdWalletApiFranceconnectWalletVerificationStartRequest": { "type": "object", "description": "启动 FranceConnect 验证（FRA）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum" } ], "default": "FRA", "description": "FranceConnect 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 FRA，即其唯一支持的国家/地区。\n\n* `FRA` - FRA" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiFranceconnectWalletVerificationStartCountryEnum": { "enum": [ "FRA" ], "type": "string", "description": "* `FRA` - FRA" }, "DigitalIdWalletApiDiiaWalletVerificationStartRequest": { "type": "object", "description": "发起 Diia 验证（UKR）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum" } ], "default": "UKR", "description": "Diia 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 UKR，即其唯一支持的国家/地区。\n\n* `UKR` - UKR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiDiiaWalletVerificationStartCountryEnum": { "enum": [ "UKR" ], "type": "string", "description": "* `UKR` - UKR" }, "DigitalIdWalletApiMojeidWalletVerificationStartRequest": { "type": "object", "description": "发起 MojeID 验证（CZE）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryE2dEnum" } ], "default": "CZE", "description": "MojeID 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 CZE，即其支持的唯一国家/地区。\n\n* `CZE` - CZE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountryE2dEnum": { "enum": [ "CZE" ], "type": "string", "description": "* `CZE` - CZE" }, "DigitalIdWalletApiBankidCzWalletVerificationStartRequest": { "type": "object", "description": "发起 Bank iD 验证（CZE）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryE2dEnum" } ], "default": "CZE", "description": "Bank iD 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 CZE，即其唯一支持的国家/地区。\n\n* `CZE` - CZE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiEparakstsMobileWalletVerificationStartRequest": { "type": "object", "description": "发起 eParaksts mobile 验证（LVA）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum" } ], "default": "LVA", "description": "eParaksts mobile 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 LVA，即其支持的唯一国家/地区。\n\n* `LVA` - LVA" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiEparakstsMobileWalletVerificationStartCountryEnum": { "enum": [ "LVA" ], "type": "string", "description": "* `LVA` - LVA" }, "DigitalIdWalletApiIdcardEeWalletVerificationStartRequest": { "type": "object", "description": "发起 Estonian ID-card 验证（EST）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum" } ], "default": "EST", "description": "Estonian ID-card 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 EST，即其唯一支持的国家/地区。\n\n* `EST` - EST" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiIdcardEeWalletVerificationStartCountryEnum": { "enum": [ "EST" ], "type": "string", "description": "* `EST` - EST" }, "DigitalIdWalletApiMobileIdWalletVerificationStartRequest": { "type": "object", "description": "启动 Mobile-ID 验证（EST、LTU）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum" } ], "description": "Mobile-ID 身份的 ISO 3166-1 alpha-3 国家/地区。\n\n* `EST` - EST\n* `LTU` - LTU" }, "personal_code": { "type": "string", "minLength": 1, "description": "用户的国家个人身份识别码。它用于寻址用户的 Mobile-ID 应用；用户在应用中确认比对码并输入其 PIN。切勿收集该 PIN。", "pattern": "^[0-9-]{6,20}$" }, "phone_number": { "type": "string", "minLength": 1, "description": "采用 E.164 格式（+372... 或 +370...）的 Mobile-ID 电话号码。", "maxLength": 16 } }, "required": [ "country", "personal_code", "phone_number" ] }, "DigitalIdWalletApiMobileIdWalletVerificationStartCountryEnum": { "enum": [ "EST", "LTU" ], "type": "string", "description": "* `EST` - EST\n* `LTU` - LTU" }, "DigitalIdWalletApiSmartIdWalletVerificationStartRequest": { "type": "object", "description": "发起 Smart-ID 验证（EST、LVA、LTU、BEL）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum" } ], "description": "Smart-ID 身份的 ISO 3166-1 alpha-3 国家/地区。\n\n* `EST` - EST\n* `LVA` - LVA\n* `LTU` - LTU\n* `BEL` - BEL" }, "personal_code": { "type": "string", "minLength": 1, "description": "用户的国家个人身份识别码。它用于寻址用户的 Smart-ID 应用；用户在应用中确认比对码并在应用中输入其 PIN。切勿收集该 PIN。", "pattern": "^[0-9-]{6,20}$" } }, "required": [ "country", "personal_code" ] }, "DigitalIdWalletApiSmartIdWalletVerificationStartCountryEnum": { "enum": [ "EST", "LVA", "LTU", "BEL" ], "type": "string", "description": "* `EST` - EST\n* `LVA` - LVA\n* `LTU` - LTU\n* `BEL` - BEL" }, "DigitalIdWalletApiGovukWalletWalletVerificationStartRequest": { "type": "object", "description": "启动 GOV.UK Wallet 验证（GBR）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountry520Enum" } ], "default": "GBR", "description": "GOV.UK Wallet 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 GBR，即其支持的唯一国家/地区。\n\n* `GBR` - GBR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountry520Enum": { "enum": [ "GBR" ], "type": "string", "description": "* `GBR` - GBR" }, "DigitalIdWalletApiOneidWalletVerificationStartRequest": { "type": "object", "description": "发起 OneID 验证（GBR）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountry520Enum" } ], "default": "GBR", "description": "OneID 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 GBR，即其支持的唯一国家/地区。\n\n* `GBR` - GBR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiGovbrWalletVerificationStartRequest": { "type": "object", "description": "发起 gov.br 验证（BRA）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum" } ], "default": "BRA", "description": "gov.br 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 BRA，即其支持的唯一国家/地区。\n\n* `BRA` - BRA" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiGovbrWalletVerificationStartCountryEnum": { "enum": [ "BRA" ], "type": "string", "description": "* `BRA` - BRA" }, "DigitalIdWalletApiUaePassWalletVerificationStartRequest": { "type": "object", "description": "发起 UAE PASS 验证（ARE）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum" } ], "default": "ARE", "description": "UAE PASS 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 ARE，即其支持的唯一国家/地区。\n\n* `ARE` - ARE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiUaePassWalletVerificationStartCountryEnum": { "enum": [ "ARE" ], "type": "string", "description": "* `ARE` - ARE" }, "DigitalIdWalletApiFrejaidWalletVerificationStartRequest": { "type": "object", "description": "启动 Freja eID 验证（SWE）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryEe9Enum" } ], "default": "SWE", "description": "Freja eID 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 SWE，即其支持的唯一国家/地区。\n\n* `SWE` - SWE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountryEe9Enum": { "enum": [ "SWE" ], "type": "string", "description": "* `SWE` - SWE" }, "DigitalIdWalletApiPersonalausweisWalletVerificationStartRequest": { "type": "object", "description": "发起 Personalausweis 验证（DEU）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum" } ], "default": "DEU", "description": "Personalausweis 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 DEU，即其支持的唯一国家/地区。\n\n* `DEU` - DEU" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiPersonalausweisWalletVerificationStartCountryEnum": { "enum": [ "DEU" ], "type": "string", "description": "* `DEU` - DEU" }, "DigitalIdWalletApiFtnWalletVerificationStartRequest": { "type": "object", "description": "启动 Finnish Trust Network 验证（FIN）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiFtnWalletVerificationStartCountryEnum" } ], "default": "FIN", "description": "Finnish Trust Network 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 FIN，即其唯一支持的国家/地区。\n\n* `FIN` - FIN" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiFtnWalletVerificationStartCountryEnum": { "enum": [ "FIN" ], "type": "string", "description": "* `FIN` - FIN" }, "DigitalIdWalletApiIdinWalletVerificationStartRequest": { "type": "object", "description": "发起 iDIN 验证（NLD）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiIdinWalletVerificationStartCountryEnum" } ], "default": "NLD", "description": "iDIN 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 NLD，即其支持的唯一国家/地区。\n\n* `NLD` - NLD" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiIdinWalletVerificationStartCountryEnum": { "enum": [ "NLD" ], "type": "string", "description": "* `NLD` - NLD" }, "DigitalIdWalletApiItsmeWalletVerificationStartRequest": { "type": "object", "description": "发起 itsme 验证（BEL、LUX、NLD）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum" } ], "description": "itsme 身份的 ISO 3166-1 alpha-3 国家/地区。\n\n* `BEL` - BEL\n* `LUX` - LUX\n* `NLD` - NLD" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "country", "return_url" ] }, "DigitalIdWalletApiItsmeWalletVerificationStartCountryEnum": { "enum": [ "BEL", "LUX", "NLD" ], "type": "string", "description": "* `BEL` - BEL\n* `LUX` - LUX\n* `NLD` - NLD" }, "DigitalIdWalletApiBuypassWalletVerificationStartRequest": { "type": "object", "description": "发起 Buypass ID 验证（NOR）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryAfcEnum" } ], "default": "NOR", "description": "Buypass ID 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 NOR，即其唯一支持的国家/地区。\n\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiCountryAfcEnum": { "enum": [ "NOR" ], "type": "string", "description": "* `NOR` - NOR" }, "DigitalIdWalletApiVippsWalletVerificationStartRequest": { "type": "object", "description": "发起 Vipps 验证（NOR）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryAfcEnum" } ], "default": "NOR", "description": "Vipps 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 NOR，即其支持的唯一国家/地区。\n\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiBankidNoWalletVerificationStartRequest": { "type": "object", "description": "发起 BankID 验证（NOR）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryAfcEnum" } ], "default": "NOR", "description": "BankID 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 NOR，即其唯一支持的国家/地区。\n\n* `NOR` - NOR" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiBankidSeWalletVerificationStartRequest": { "type": "object", "description": "发起 BankID 验证（SWE）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiCountryEe9Enum" } ], "default": "SWE", "description": "BankID 身份的 ISO 3166-1 alpha-3 国家/地区代码。默认值为 SWE，即其唯一支持的国家/地区。\n\n* `SWE` - SWE" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiMitidWalletVerificationStartRequest": { "type": "object", "description": "启动 MitID 验证（DNK）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiMitidWalletVerificationStartCountryEnum" } ], "default": "DNK", "description": "MitID 身份的 ISO 3166-1 alpha-3 国家/地区。默认为 DNK，即其支持的唯一国家/地区。\n\n* `DNK` - DNK" }, "return_url": { "type": "string", "format": "uri", "minLength": 1, "description": "用户浏览器在钱包操作后返回的 https URL，末尾会附加 request_id 和 result。其 host 必须在应用的 allowed_return_hosts 中注册（或为其白标域名）。切勿仅信任 result：请通过 GET .../verifications/{request_id}/ 或 Webhook 读取最终结果。", "maxLength": 2048 }, "device": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiDeviceEnum" } ], "default": "same_device", "description": "用户在显示您页面的设备上登录时为 same_device，使用另一台设备（例如 BankID 二维码）时为 cross_device。\n\n* `same_device` - same_device\n* `cross_device` - cross_device" } }, "required": [ "return_url" ] }, "DigitalIdWalletApiMitidWalletVerificationStartCountryEnum": { "enum": [ "DNK" ], "type": "string", "description": "* `DNK` - DNK" }, "DigitalIdWalletApiWalletCatalogResponse": { "type": "object", "properties": { "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/DigitalIdWalletApiWalletCatalogEntry" } } }, "required": [ "wallets" ] }, "DigitalIdWalletApiWalletCatalogEntry": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "path": { "type": "string", "description": "钱包专属的启动 endpoint。" }, "countries": { "type": "array", "items": { "type": "string" } }, "issuing_authority": { "type": "string" }, "level_of_assurance": { "type": "string", "nullable": true }, "interaction": { "$ref": "#/components/schemas/DigitalIdWalletApiInteractionEnum" }, "required_fields": { "type": "array", "items": { "type": "string" } }, "available": { "type": "boolean", "description": "该应用目前能否在此环境中启动它。列出并不代表已在生产环境上线。" } }, "required": [ "available", "countries", "id", "interaction", "issuing_authority", "level_of_assurance", "name", "path", "required_fields" ] }, "CaseDuplicateCaseDuplicate": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "case_number": { "type": "string", "nullable": true, "maxLength": 32 }, "title": { "type": "string", "maxLength": 255 }, "status": { "$ref": "#/components/schemas/CaseDuplicateStatusEnum" }, "priority": { "$ref": "#/components/schemas/CaseDuplicatePriorityEnum" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "title", "uuid" ] }, "CaseDuplicateCaseDuplicatePage": { "type": "object", "properties": { "count": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseDuplicateCaseDuplicate" } } }, "required": [ "count", "next_offset", "results" ] }, "RoutingPublicationPolicyDraftResponse": { "type": "object", "properties": { "draft": { "allOf": [ { "$ref": "#/components/schemas/RoutingPublicationPolicyDraft" } ], "nullable": true } }, "required": [ "draft" ] }, "RoutingPublicationPolicyDraftWriteRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true }, "changes": { "type": "object", "additionalProperties": {} } }, "required": [ "changes", "expected_revision", "expected_version" ] }, "CasePublicationPolicyDraft": { "type": "object", "properties": { "revision": { "type": "string", "format": "uuid" }, "base_version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "changes": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "base_version", "updated_at" ] }, "CasePublicationPolicyDraftPreconditionRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "expected_revision", "expected_version" ] }, "CaseCollaborationCaseNote": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "comment": { "type": "string" }, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 255 }, "actor_name": { "type": "string", "nullable": true, "maxLength": 255 }, "mentioned_emails": {}, "is_internal": { "type": "boolean" }, "attachments": {}, "tags": {}, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "reply_to": { "allOf": [ { "$ref": "#/components/schemas/CaseCollaborationCaseNoteReply" } ], "nullable": true, "readOnly": true }, "is_pinned": { "type": "boolean" }, "client_reference": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "comment", "created_at", "reply_to", "uuid" ] }, "CustomerMessagingPaginatedCaseRequestList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingCaseRequest" } } } }, "FraudCheckResponse": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid", "description": "为此检查创建的原生验证会话。" }, "client_reference": { "type": "string", "nullable": true }, "processing_status": { "$ref": "#/components/schemas/FraudProcessingStatusEnum" }, "profile_id": { "type": "string" }, "profile_version": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckInput" } }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckModuleReport" } }, "attribute_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "compound_evidence": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "risk": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckRisk" } }, "network": { "type": "object", "additionalProperties": {} }, "enrichment": { "type": "object", "additionalProperties": {} }, "identity_relationship": { "allOf": [ { "$ref": "#/components/schemas/FraudCheckIdentityRelationship" } ], "nullable": true }, "recommendation": { "$ref": "#/components/schemas/FraudRecommendationEnum" }, "next_action": { "$ref": "#/components/schemas/FraudNextActionEnum" }, "decision_reasons": { "type": "array", "items": { "type": "string" } }, "coverage": { "type": "object", "additionalProperties": {} }, "usage": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "vendor_data": { "type": "string", "nullable": true }, "metadata": { "nullable": true } }, "required": [ "attribute_evidence", "check_id", "client_reference", "completed_at", "compound_evidence", "coverage", "created_at", "decision_reasons", "inputs", "modules", "network", "next_action", "processing_status", "profile_id", "profile_version", "recommendation", "risk", "usage" ] }, "CaseReviewTeam": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeamMember" }, "maxItems": 250 }, "is_active": { "type": "boolean" }, "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "CaseActionCaseEntityActionRequest": { "type": "object", "properties": { "client_reference": { "type": "string", "format": "uuid" }, "retry": { "type": "boolean", "default": false }, "action": { "$ref": "#/components/schemas/CaseActionActionEnum" }, "status": { "type": "string", "nullable": true }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "note": { "type": "string", "nullable": true } }, "required": [ "action" ] }, "RoutingPublicationPaginatedPolicyRevisionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingPublicationPolicyRevision" } } } }, "FraudRecommendationEnum": { "enum": [ "approve", "review", "reject" ], "type": "string", "description": "* `approve` - 通过\n* `review` - 审核\n* `reject` - 拒绝" }, "CustomerMessagingCaseRequestPreviewResponse": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "recipient": { "type": "string", "format": "email" }, "sender": { "type": "string" }, "subject": { "type": "string" }, "html": { "type": "string" }, "requires_user_action": { "type": "boolean" }, "preview_token": { "type": "string" } }, "required": [ "expires_at", "html", "preview_token", "recipient", "request_id", "requires_user_action", "sender", "subject" ] }, "CustomerMessagingCaseCustomerResponseRequest": { "type": "object", "properties": { "full_name": { "type": "string", "minLength": 1, "maxLength": 512 }, "date_of_birth": { "type": "string", "format": "date" }, "file": { "type": "string", "format": "binary", "writeOnly": true } } }, "CaseCollaborationCaseNoteReply": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "actor_name": { "type": "string", "nullable": true }, "actor_email": { "type": "string", "format": "email", "nullable": true }, "comment": { "type": "string", "maxLength": 300 } }, "required": [ "actor_email", "actor_name", "comment", "uuid" ] }, "FraudCheckModuleReport": { "type": "object", "properties": { "module": { "$ref": "#/components/schemas/FraudExcludeEnum" }, "status": { "$ref": "#/components/schemas/FraudStatusEnum" }, "reason": { "type": "string", "nullable": true }, "latency_ms": { "type": "integer" }, "freshness": { "type": "string", "nullable": true }, "billable_units": { "type": "integer" } }, "required": [ "billable_units", "freshness", "latency_ms", "module", "reason", "status" ] }, "CaseDuplicateEntityTypeEnum": { "enum": [ "session", "business_session", "transaction" ], "type": "string", "description": "* `session` - 会话\n* `business_session` - 企业会话\n* `transaction` - 交易" }, "FraudClientCredentialsErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Authentication failed: Invalid client access token." } } }, "FraudAvailabilityEnum": { "enum": [ "available", "not_requested", "no_reference", "insufficient_history", "unsupported_region", "source_unavailable" ], "type": "string", "description": "* `available` - 可用\n* `not_requested` - 未请求\n* `no_reference` - 无参考数据\n* `insufficient_history` - 历史记录不足\n* `unsupported_region` - 不受支持的地区\n* `source_unavailable` - 数据源不可用" }, "CasePublicationPolicyDraftResponse": { "type": "object", "properties": { "draft": { "allOf": [ { "$ref": "#/components/schemas/CasePublicationPolicyDraft" } ], "nullable": true } }, "required": [ "draft" ] }, "FraudCheckAttributesRequest": { "type": "object", "description": "佐证属性。全部可选；它们可扩大模块覆盖范围。", "properties": { "first_name": { "type": "string", "maxLength": 128 }, "last_name": { "type": "string", "maxLength": 128 }, "full_name": { "type": "string", "maxLength": 256 }, "date_of_birth": { "type": "string", "format": "date" }, "nationality": { "type": "string", "maxLength": 3 }, "gender": { "type": "string", "maxLength": 16 }, "address": { "type": "string", "maxLength": 512 }, "city": { "type": "string", "maxLength": 128 }, "state": { "type": "string", "maxLength": 128 }, "postal_code": { "type": "string", "maxLength": 32 } } }, "NetworkNote": { "type": "object", "required": [ "uuid", "actor_email", "comment", "client_reference", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "actor_email": { "type": "string", "format": "email", "readOnly": true, "description": "已认证的作者，由服务器分配。" }, "comment": { "type": "string", "minLength": 1, "maxLength": 10000 }, "client_reference": { "type": "string", "format": "uuid" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } } }, "CaseActionEntityTypeEnum": { "enum": [ "user", "business" ], "type": "string", "description": "* `user` - 用户\n* `business` - 企业" }, "CaseRoutingCondition": { "type": "object", "properties": { "field": { "type": "string", "enum": [ "source", "priority", "tags" ] }, "operator": { "type": "string", "enum": [ "equals", "in", "contains" ] }, "value": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "required": [ "field", "operator", "value" ], "description": "来源和优先级支持使用 equals 或 in 运算符匹配支持的值。标签支持针对单个非空标签使用 contains 运算符。" }, "RoutingPublicationPolicyRevision": { "type": "object", "properties": { "version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "snapshot": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "published_at", "snapshot", "version" ] }, "CasePublicationPolicyRevision": { "type": "object", "properties": { "version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "snapshot": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "published_at": { "type": "string", "format": "date-time" } }, "required": [ "published_at", "snapshot", "version" ] }, "FraudCheckIdentityRelationship": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/FraudResultEnum" }, "reference_type": { "type": "string" }, "country": { "type": "string" }, "availability": { "$ref": "#/components/schemas/FraudAvailabilityEnum" }, "reason_codes": { "type": "array", "items": { "type": "string" } } }, "required": [ "availability", "country", "reason_codes", "reference_type", "result" ] }, "CasePublicationPaginatedPolicyRevisionList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CasePublicationPolicyRevision" } } } }, "CaseDuplicateBlankEnum": { "enum": [ "" ] }, "FraudCheckPlan": { "type": "object", "properties": { "profile_id": { "type": "string" }, "profile_version": { "type": "string" }, "modules": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckPlannedModule" } }, "estimated_price": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "is_sandbox": { "type": "boolean" }, "can_afford": { "type": "boolean" } }, "required": [ "can_afford", "currency", "estimated_price", "is_sandbox", "modules", "profile_id", "profile_version" ] }, "CaseReviewTeamUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeamMember" }, "maxItems": 250 }, "is_active": { "type": "boolean" } } }, "RoutingPublicationPolicyDraft": { "type": "object", "properties": { "revision": { "type": "string", "format": "uuid" }, "base_version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "changes": {}, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "base_version", "updated_at" ] }, "FraudCheckRequestRequest": { "type": "object", "properties": { "client_reference": { "type": "string", "minLength": 1, "description": "您为此项检查指定的自身参考编号。同时充当幂等性密钥：使用相同的请求体复用该编号将返回原始检查结果，而不会再次运行模块或计费；使用不同的请求体复用该编号将返回 409。", "maxLength": 255 }, "profile": { "type": "string", "minLength": 1, "default": "standard", "description": "编排配置文件 ID。默认为 Didit 的 `standard` 配置文件。", "maxLength": 64 }, "profile_version": { "type": "string", "minLength": 1, "description": "固定冻结的档案版本。默认为档案的当前版本。", "maxLength": 32 }, "subject": { "$ref": "#/components/schemas/FraudCheckSubjectRequest" }, "context": { "$ref": "#/components/schemas/FraudCheckContextRequest" }, "checks": { "$ref": "#/components/schemas/FraudCheckModuleSelectionRequest" }, "vendor_data": { "type": "string", "maxLength": 1000 }, "metadata": {} }, "required": [ "subject" ] }, "CaseDuplicateCaseSubjectInputRequest": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CaseDuplicateTypeEnum" }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "type", "uuid" ] }, "CaseReviewTeamMember": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "availability": { "type": "string", "enum": [ "available", "unavailable" ], "default": "available" }, "capacity": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 10 }, "skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "available_from": { "type": "string", "format": "date-time", "nullable": true }, "available_until": { "type": "string", "format": "date-time", "nullable": true } }, "required": [ "user_id" ] }, "CaseRoutingPreviewRequest": { "type": "object", "properties": { "source": { "type": "string", "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ] }, "priority": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "default": "MEDIUM" }, "tags": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 50 }, "rule_uuid": { "type": "string", "format": "uuid" }, "draft": { "$ref": "#/components/schemas/CaseRoutingRuleCreate" } }, "required": [ "source" ] }, "FraudExcludeEnum": { "enum": [ "normalization", "email_risk", "email_social", "phone_social", "phone_risk", "ip_risk", "database_validation", "networks_same_org", "networks_cross_org", "biometric_identity" ], "type": "string", "description": "* `normalization` - 标准化\n* `email_risk` - 邮箱风险\n* `email_social` - 邮箱社交账号\n* `phone_social` - 电话社交账号\n* `phone_risk` - 电话风险\n* `ip_risk` - IP 风险\n* `database_validation` - 数据库核验\n* `networks_same_org` - 同组织网络\n* `networks_cross_org` - 跨组织网络\n* `biometric_identity` - 生物识别身份" }, "CaseDuplicateCaseLinkCreateRequest": { "type": "object", "properties": { "entity_type": { "$ref": "#/components/schemas/CaseDuplicateEntityTypeEnum" }, "entity_uuid": { "type": "string", "format": "uuid" } }, "required": [ "entity_type", "entity_uuid" ] }, "CaseDuplicateStatusEnum": { "enum": [ "OPEN", "AWAITING_USER", "RESOLVED" ], "type": "string", "description": "* `OPEN` - 已开启\n* `AWAITING_USER` - 等待用户\n* `RESOLVED` - 已解决" }, "FraudBandEnum": { "enum": [ "low", "medium", "high", "unknown" ], "type": "string", "description": "* `low` - 低\n* `medium` - 中\n* `high` - 高\n* `unknown` - 未知" }, "CaseDuplicatePriorityEnum": { "enum": [ "LOW", "MEDIUM", "HIGH" ], "type": "string", "description": "* `LOW` - 低\n* `MEDIUM` - 中\n* `HIGH` - 高" }, "FraudStatusEnum": { "enum": [ "planned", "completed", "skipped", "failed" ], "type": "string", "description": "* `planned` - 已计划\n* `completed` - 已完成\n* `skipped` - 已跳过\n* `failed` - 已失败" }, "FraudCheckInput": { "type": "object", "properties": { "reference": { "type": "string", "description": "所提交标识符的脱敏句柄。" }, "type": { "$ref": "#/components/schemas/FraudTypeEnum" }, "namespace": { "type": "object", "additionalProperties": {} }, "quality": { "type": "string" }, "normalization": { "type": "object", "additionalProperties": {} }, "availability": { "$ref": "#/components/schemas/FraudAvailabilityEnum" } }, "required": [ "availability", "namespace", "normalization", "quality", "reference", "type" ] }, "CustomerMessagingPurposesEnum": { "enum": [ "identity_document", "proof_of_address", "business_document", "confirm_details", "review_in_progress" ], "type": "string", "description": "* `identity_document` - identity_document\n* `proof_of_address` - proof_of_address\n* `business_document` - business_document\n* `confirm_details` - confirm_details\n* `review_in_progress` - review_in_progress" }, "FraudTypeEnum": { "enum": [ "email", "phone", "national_id", "tax_number", "passport_number", "driving_licence_number", "residence_permit_number", "voter_id", "external_id" ], "type": "string", "description": "* `email` - 邮箱\n* `phone` - 电话\n* `national_id` - 国民身份证号\n* `tax_number` - 税号\n* `passport_number` - 护照号码\n* `driving_licence_number` - 驾驶证号\n* `residence_permit_number` - 居留许可号码\n* `voter_id` - 选民证号\n* `external_id` - 外部 ID" }, "CaseDuplicateCaseSubjectInput": { "type": "object", "properties": { "type": { "$ref": "#/components/schemas/CaseDuplicateTypeEnum" }, "uuid": { "type": "string", "format": "uuid" } }, "required": [ "type", "uuid" ] }, "CaseReviewTeamCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "members": { "type": "array", "items": { "$ref": "#/components/schemas/CaseReviewTeamMember" }, "maxItems": 250 }, "is_active": { "type": "boolean" } }, "required": [ "name", "members" ] }, "CaseDuplicateCaseDuplicateQueryRequest": { "type": "object", "properties": { "subject": { "$ref": "#/components/schemas/CaseDuplicateCaseSubjectInputRequest" }, "links": { "type": "array", "items": { "$ref": "#/components/schemas/CaseDuplicateCaseLinkCreateRequest" } }, "offset": { "type": "integer", "maximum": 1000000, "minimum": 0, "default": 0 } } }, "CaseDuplicateResolutionEnum": { "enum": [ "FALSE_POSITIVE", "VALID_THREAT" ], "type": "string", "description": "* `FALSE_POSITIVE` - 误报\n* `VALID_THREAT` - 真实威胁" }, "CasePublicationPolicyDraftWriteRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true }, "changes": { "type": "object", "additionalProperties": {} } }, "required": [ "changes", "expected_revision", "expected_version" ] }, "FraudCheckSubjectRequest": { "type": "object", "properties": { "selfie": { "type": "string", "minLength": 1, "description": "Base64 编码的 JPEG、PNG 或 WebP 自拍照，最大 6 MB。无参考图片或 URL。", "maxLength": 8388672 }, "identifiers": { "type": "array", "items": { "$ref": "#/components/schemas/FraudCheckIdentifierRequest" }, "description": "一个或多个带类型的标识符。提供一个即可。", "maxItems": 10, "minItems": 1 }, "attributes": { "$ref": "#/components/schemas/FraudCheckAttributesRequest" } }, "required": [ "identifiers" ] }, "RoutingPublicationRoutingCondition": { "type": "object", "properties": { "field": { "$ref": "#/components/schemas/RoutingPublicationFieldEnum" }, "operator": { "$ref": "#/components/schemas/RoutingPublicationOperatorEnum" }, "value": {} }, "required": [ "field", "operator", "value" ] }, "CaseActionCaseActionReceipt": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "client_reference": { "type": "string", "format": "uuid" }, "action": { "type": "string", "maxLength": 32 }, "status": { "$ref": "#/components/schemas/CaseActionStatusEnum" }, "result": {}, "error": { "type": "string", "maxLength": 255 }, "actor_email": { "type": "string", "format": "email", "nullable": true, "maxLength": 254 }, "attempts": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "action", "client_reference", "created_at", "status", "updated_at", "uuid" ] }, "FraudCheckContextRequest": { "type": "object", "properties": { "ip_address": { "type": "string", "minLength": 1 }, "user_agent": { "type": "string", "maxLength": 512 }, "country": { "type": "string", "description": "主体声称所在的国家/地区。仅作为背景信息，绝不能作为身份归属的证明。", "maxLength": 3 }, "purpose": { "type": "string", "maxLength": 128 }, "consent_obtained": { "type": "boolean" } } }, "CustomerMessagingCaseCustomerResponseResult": { "type": "object", "properties": { "responded_at": { "type": "string", "format": "date-time" } }, "required": [ "responded_at" ] }, "CustomerMessagingCaseRequestContact": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "email": { "type": "string", "format": "email" }, "verified_at": { "type": "string", "format": "date-time" } }, "required": [ "email", "uuid", "verified_at" ] }, "FraudClientCredentialsForbiddenErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Forbidden - User doesn't have permission" } } }, "CasePublicationAssignmentMethodEnum": { "enum": [ "MANUAL", "AUTOMATIC" ], "type": "string", "description": "* `MANUAL` - 手动\n* `AUTOMATIC` - 自动" }, "CaseDuplicateNullEnum": { "enum": [ null ] }, "CustomerMessagingLanguageEnum": { "enum": [ "en", "es", "pt" ], "type": "string", "description": "* `en` - en\n* `es` - es\n* `pt` - pt" }, "CaseDuplicateCaseFraudSourceContextRequest": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "source_section": { "type": "string", "minLength": 1, "pattern": "^[A-Z][A-Z0-9_:-]{0,63}$" } }, "required": [ "check_id", "request_id", "source_section" ] }, "FraudCheckPlannedModule": { "type": "object", "properties": { "module": { "$ref": "#/components/schemas/FraudExcludeEnum" }, "available": { "type": "boolean" }, "availability_reason": { "type": "string", "nullable": true }, "will_run": { "type": "boolean" }, "selection_reason": { "type": "string", "nullable": true }, "estimated_price": { "type": "string", "nullable": true } }, "required": [ "availability_reason", "available", "estimated_price", "module", "selection_reason", "will_run" ] }, "CustomerMessagingCaseRequestOptions": { "type": "object", "properties": { "contacts": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingCaseRequestContact" } }, "purposes": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingPurposesEnum" } }, "languages": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerMessagingLanguagesEnum" } } }, "required": [ "contacts", "languages", "purposes" ] }, "CaseCollaborationPaginatedCaseNoteList": { "type": "object", "required": [ "count", "results" ], "properties": { "count": { "type": "integer", "example": 123 }, "next": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=400&limit=100" }, "previous": { "type": "string", "nullable": true, "format": "uri", "example": "http://api.example.org/accounts/?offset=200&limit=100" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseCollaborationCaseNote" } } } }, "FraudProcessingStatusEnum": { "enum": [ "pending", "running", "completed", "failed" ], "type": "string", "description": "* `pending` - 等待中\n* `running` - 运行中\n* `completed` - 已完成\n* `failed` - 失败" }, "CasePublicationCaseBlueprint": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "maxLength": 24 }, "description": { "type": "string", "nullable": true }, "assignment_method": { "$ref": "#/components/schemas/CasePublicationAssignmentMethodEnum" }, "assignee_pool": {}, "max_active_cases": { "type": "integer", "maximum": 2147483647, "minimum": 0, "nullable": true }, "escalation_enabled": { "type": "boolean" }, "escalation_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "escalation_blueprint_name": { "type": "string", "readOnly": true }, "transfer_enabled": { "type": "boolean" }, "four_eyes_checker_blueprint": { "type": "string", "format": "uuid", "nullable": true }, "four_eyes_checker_blueprint_name": { "type": "string", "readOnly": true }, "require_resolution_note": { "type": "boolean" }, "content_config": {}, "version": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "default_deadline_hours": { "type": "integer", "maximum": 2147483647, "minimum": 0, "nullable": true }, "is_active": { "type": "boolean" }, "preset_key": { "type": "string", "nullable": true, "maxLength": 64 }, "creation_sources": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "readOnly": true }, "receives_escalation_from": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "created_at", "creation_sources", "escalation_blueprint_name", "four_eyes_checker_blueprint_name", "name", "receives_escalation_from", "updated_at", "uuid" ] }, "CaseRoutingRuleUpdate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingCondition" }, "maxItems": 20 }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "team": { "type": "string", "format": "uuid", "nullable": true }, "is_active": { "type": "boolean" }, "expected_version": { "type": "integer", "minimum": 1, "writeOnly": true, "description": "编辑器打开的版本。提供此参数时，过期写入将返回 409 且不会更改规则。" } } }, "CustomerMessagingCaseRequestPreviewRequest": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "purpose": { "$ref": "#/components/schemas/CustomerMessagingPurposeEnum" }, "language": { "allOf": [ { "$ref": "#/components/schemas/CustomerMessagingLanguageEnum" } ], "default": "en" } }, "required": [ "contact_id", "purpose" ] }, "CaseDuplicateCaseFraudSourceContext": { "type": "object", "properties": { "check_id": { "type": "string", "format": "uuid" }, "request_id": { "type": "string", "format": "uuid" }, "source_section": { "type": "string", "pattern": "^[A-Z][A-Z0-9_:-]{0,63}$" } }, "required": [ "check_id", "request_id", "source_section" ] }, "RoutingPublicationOperatorEnum": { "enum": [ "equals", "in", "contains" ], "type": "string", "description": "* `equals` - equals\n* `in` - in\n* `contains` - contains" }, "CaseRoutingPreview": { "type": "object", "properties": { "rule_uuid": { "type": "string", "format": "uuid", "nullable": true }, "rule_name": { "type": "string", "nullable": true }, "rule_version": { "type": "integer", "nullable": true }, "blueprint_uuid": { "type": "string", "format": "uuid", "nullable": true }, "team_uuid": { "type": "string", "format": "uuid", "nullable": true }, "assignee_user_id": { "type": "string", "format": "uuid", "nullable": true }, "reason": { "type": "string" }, "candidates": { "type": "array", "items": { "type": "object", "properties": { "user_id": { "type": "string", "format": "uuid" }, "eligible": { "type": "boolean" }, "active_cases": { "type": "integer", "nullable": true }, "reason": { "type": "string", "nullable": true } } } }, "matched_rules": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "priority": { "type": "integer" } } } } } }, "FraudDimensionEnum": { "enum": [ "identity", "contact", "device_network", "behavioral", "fraud_network" ], "type": "string", "description": "* `identity` - 身份\n* `contact` - 联系方式\n* `device_network` - 设备网络\n* `behavioral` - 行为\n* `fraud_network` - 欺诈网络" }, "FraudBadRequestErrorMessage": { "type": "object", "properties": { "detail": { "type": "string", "default": "Bad Request - Invalid request data" } } }, "FraudNextActionEnum": { "enum": [ "none", "manual_review", "step_up", "resubmit_capture" ], "type": "string", "description": "* `none` - 无\n* `manual_review` - 人工审核\n* `step_up` - 强化验证\n* `resubmit_capture` - 重新提交采集" }, "RoutingPublicationPolicyDraftPreconditionRequest": { "type": "object", "properties": { "expected_version": { "type": "integer", "minimum": 0 }, "expected_revision": { "type": "string", "format": "uuid", "nullable": true } }, "required": [ "expected_revision", "expected_version" ] }, "FraudCheckRisk": { "type": "object", "properties": { "dimension": { "$ref": "#/components/schemas/FraudDimensionEnum" }, "score": { "type": "integer", "nullable": true }, "band": { "$ref": "#/components/schemas/FraudBandEnum" }, "availability": { "$ref": "#/components/schemas/FraudAvailabilityEnum" }, "requested_but_unavailable": { "type": "boolean", "description": "当请求提供了该维度所需的一切信息，但平台仍无法给出结果时为 true。仅凭已有结果的维度，此类核验绝不建议予以批准。" }, "reason_codes": { "type": "array", "items": { "type": "string" } }, "evidence_indexes": { "type": "array", "items": { "type": "integer" } } }, "required": [ "availability", "band", "dimension", "evidence_indexes", "reason_codes", "requested_but_unavailable", "score" ] }, "CaseDuplicateSourceEnum": { "enum": [ "MANUAL", "AML_SCREENING", "TRANSACTION_RULE", "WORKFLOW_BUILDER" ], "type": "string", "description": "* `MANUAL` - 手动\n* `AML_SCREENING` - AML 筛查\n* `TRANSACTION_RULE` - 交易规则\n* `WORKFLOW_BUILDER` - 工作流构建器" }, "CaseCollaborationPatchedCaseNoteUpdateRequest": { "type": "object", "properties": { "is_pinned": { "type": "boolean" } } }, "CustomerMessagingPurposeEnum": { "enum": [ "identity_document", "proof_of_address", "business_document", "confirm_details", "review_in_progress" ], "type": "string", "description": "* `identity_document` - identity_document\n* `proof_of_address` - proof_of_address\n* `business_document` - business_document\n* `confirm_details` - confirm_details\n* `review_in_progress` - review_in_progress" }, "CaseDuplicateTypeEnum": { "enum": [ "user", "business" ], "type": "string", "description": "* `user` - 用户\n* `business` - 企业" }, "CaseCollaborationCaseNoteCreateRequest": { "type": "object", "properties": { "comment": { "type": "string", "minLength": 1, "maxLength": 10000 }, "reply_to": { "type": "string", "format": "uuid", "nullable": true }, "client_reference": { "type": "string", "format": "uuid", "nullable": true }, "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email", "minLength": 1 } }, "is_internal": { "type": "boolean", "default": false }, "attachments": { "type": "array", "items": { "type": "object", "additionalProperties": {} } }, "tags": { "type": "array", "items": { "type": "string", "minLength": 1 } } }, "required": [ "comment" ] }, "CustomerMessagingLanguagesEnum": { "enum": [ "en", "es", "pt" ], "type": "string", "description": "* `en` - en\n* `es` - es\n* `pt` - pt" }, "CustomerMessagingCaseRequestConfirmRequest": { "type": "object", "properties": { "contact_id": { "type": "string", "format": "uuid" }, "purpose": { "$ref": "#/components/schemas/CustomerMessagingPurposeEnum" }, "language": { "allOf": [ { "$ref": "#/components/schemas/CustomerMessagingLanguageEnum" } ], "default": "en" }, "request_id": { "type": "string", "format": "uuid" }, "expires_at": { "type": "string", "format": "date-time" }, "preview_token": { "type": "string", "minLength": 1, "maxLength": 512 } }, "required": [ "contact_id", "expires_at", "preview_token", "purpose", "request_id" ] }, "CaseRoutingRule": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingCondition" }, "maxItems": 20 }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "team": { "type": "string", "format": "uuid", "nullable": true }, "is_active": { "type": "boolean" }, "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true }, "version": { "type": "integer", "readOnly": true }, "blueprint_name": { "type": "string", "readOnly": true }, "team_name": { "type": "string", "nullable": true, "readOnly": true } } }, "FraudResultEnum": { "enum": [ "match", "mismatch", "inconclusive", "no_reference" ], "type": "string", "description": "* `match` - 匹配\n* `mismatch` - 不匹配\n* `inconclusive` - 无明确结论\n* `no_reference` - 无参考数据" }, "CaseRoutingRuleCreate": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CaseRoutingCondition" }, "maxItems": 20 }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "team": { "type": "string", "format": "uuid", "nullable": true }, "is_active": { "type": "boolean" }, "publish": { "type": "boolean", "writeOnly": true, "description": "设置为 false 可保存未发布的草稿。在草稿显式发布之前，记录将保持非活动状态且版本为 0。省略此字段可保持现有集成的立即创建行为。" } }, "required": [ "name", "conditions", "blueprint" ] }, "FraudCheckIdentifierRequest": { "type": "object", "properties": { "type": { "allOf": [ { "$ref": "#/components/schemas/FraudTypeEnum" } ], "description": "标识符类型。决定需要哪些命名空间字段。\n\n* `email` - 邮箱\n* `phone` - 电话\n* `national_id` - 身份证号\n* `tax_number` - 税号\n* `passport_number` - 护照号\n* `driving_licence_number` - 驾驶证号\n* `residence_permit_number` - 居留许可号\n* `voter_id` - 选民证号\n* `external_id` - 外部 ID" }, "value": { "type": "string", "minLength": 1, "description": "标识符的值，采用任何惯用格式均可。", "maxLength": 255 }, "country": { "type": "string", "description": "ISO-3166 alpha-2 或 alpha-3 签发国家/地区。政府证件号码类型必填：相同的号码在不同国家/地区代表不同的人。", "maxLength": 3 }, "issuer": { "type": "string", "description": "可选的签发机构或国家/地区以下级别的签发方，适用于仅凭国家/地区无法唯一定位的情况。", "maxLength": 128 } }, "required": [ "type", "value" ] }, "CaseActionActionEnum": { "enum": [ "set_status", "add_tags", "add_note", "add_to_blocklist" ], "type": "string", "description": "* `set_status` - 设置状态\n* `add_tags` - 添加标签\n* `add_note` - 添加备注\n* `add_to_blocklist` - 添加到黑名单" }, "CaseActionCaseActionReceiptPage": { "type": "object", "properties": { "count": { "type": "integer" }, "next_offset": { "type": "integer", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CaseActionCaseActionReceipt" } } }, "required": [ "count", "next_offset", "results" ] }, "CaseActionCaseEntityActionResult": { "type": "object", "properties": { "receipt": { "$ref": "#/components/schemas/CaseActionCaseActionReceipt" }, "entity_type": { "$ref": "#/components/schemas/CaseActionEntityTypeEnum" }, "entity_uuid": { "type": "string", "format": "uuid" }, "action": { "type": "string" }, "previous_status": { "type": "string" }, "new_status": { "type": "string" }, "tags_added": { "type": "array", "items": { "type": "string" } }, "comment_uuid": { "type": "string", "format": "uuid" }, "blocklisted": { "type": "array", "items": { "type": "string" } } } }, "CustomerMessagingCaseRequest": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "purpose": { "type": "string", "readOnly": true }, "language": { "type": "string", "readOnly": true }, "recipient": { "type": "string", "format": "email", "readOnly": true }, "expires_at": { "type": "string", "format": "date-time", "readOnly": true }, "actor_email": { "type": "string", "format": "email", "readOnly": true, "nullable": true }, "delivery_status": { "type": "string", "readOnly": true }, "delivered_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "responded_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "response": { "readOnly": true, "nullable": true }, "has_attachment": { "type": "boolean", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "actor_email", "cancelled_at", "created_at", "delivered_at", "delivery_status", "expires_at", "has_attachment", "language", "purpose", "recipient", "responded_at", "response", "uuid" ] }, "CustomerMessagingCaseRequestPublic": { "type": "object", "properties": { "request_id": { "type": "string", "format": "uuid" }, "purpose": { "$ref": "#/components/schemas/CustomerMessagingPurposeEnum" }, "language": { "$ref": "#/components/schemas/CustomerMessagingLanguageEnum" }, "expires_at": { "type": "string", "format": "date-time" }, "responded_at": { "type": "string", "format": "date-time", "nullable": true }, "copy": { "type": "object", "additionalProperties": {} }, "organization_name": { "type": "string" }, "is_white_label": { "type": "boolean" }, "customization": { "type": "object", "additionalProperties": {}, "nullable": true } }, "required": [ "copy", "customization", "expires_at", "is_white_label", "language", "organization_name", "purpose", "request_id", "responded_at" ] }, "RoutingPublicationFieldEnum": { "enum": [ "source", "priority", "tags" ], "type": "string", "description": "* `source` - 来源\n* `priority` - 优先级\n* `tags` - 标签" }, "RoutingPublicationCaseRoutingRule": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid", "readOnly": true }, "name": { "type": "string", "maxLength": 100 }, "description": { "type": "string", "maxLength": 500 }, "priority": { "type": "integer", "maximum": 2147483647, "minimum": 0 }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/RoutingPublicationRoutingCondition" } }, "required_skills": { "type": "array", "items": { "type": "string", "maxLength": 64 }, "maxItems": 25 }, "blueprint": { "type": "string", "format": "uuid" }, "blueprint_name": { "type": "string", "readOnly": true }, "team": { "type": "string", "format": "uuid", "nullable": true }, "team_name": { "type": "string", "readOnly": true }, "is_active": { "type": "boolean" }, "version": { "type": "integer", "readOnly": true }, "created_at": { "type": "string", "format": "date-time", "readOnly": true }, "updated_at": { "type": "string", "format": "date-time", "readOnly": true } }, "required": [ "blueprint", "blueprint_name", "conditions", "created_at", "name", "team_name", "updated_at", "uuid", "version" ] }, "CaseActionStatusEnum": { "enum": [ "APPLIED", "FAILED" ], "type": "string", "description": "* `APPLIED` - 已应用\n* `FAILED` - 失败" }, "FraudCheckModuleSelectionRequest": { "type": "object", "properties": { "include": { "type": "array", "items": { "$ref": "#/components/schemas/FraudExcludeEnum" } }, "exclude": { "type": "array", "items": { "$ref": "#/components/schemas/FraudExcludeEnum" } } } }, "SignatureField": { "type": "object", "description": "放置在会话证件上的字段：由哪个签署人填写、如何填写以及在何处填写。提供位置（`page`、`x`、`y`、`width` 和 `height`）或 `anchor`。位置是页面显示时以页面左上角为起点的比例，四舍五入保留 4 位小数，且字段必须完全位于页面内部。一个证件最多支持 200 个字段，一个签署人最多支持 500 个字段，且在该证件上拥有字段的每个角色都需要一个 `signature` 或 `initials` 字段。参见[证件上的字段](/zh/core-technology/electronic-signature/overview#文档上的字段)。", "required": [ "key", "type" ], "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,63}$", "description": "在结果中以及 `sign.field_values` 中命名该字段。在证件内唯一。" }, "type": { "type": "string", "enum": [ "signature", "initials", "full_name", "date_signed", "text", "checkbox", "email", "data" ], "description": "该字段包含的内容。签署人应用其采用的 `signature` 和 `initials`，输入 `text`，勾选 `checkbox`，并在会话没有已验证邮箱时输入 `email`。Didit 会自动填充 `full_name`（已核验的姓名）、`date_signed`（签署日期，采用签署人所在时区）、`data`（来自 `prefill`）和已验证的 `email`，并以只读方式显示它们。没有日期选择器类型：请使用 `text`。" }, "role": { "type": "string", "enum": [ "verified_person", "legal_representative", "key_people" ], "description": "填写该字段的主体，包含 `signature_signer` 的值。一个步骤仅填写并标记属于其自身签署人的字段。默认为该步骤的签署人。" }, "page": { "type": "integer", "minimum": 1, "description": "页码，从 1 到证件的总页数。对于 Word 证件，指转换后 PDF 的页码。" }, "x": { "type": "number", "minimum": 0, "maximum": 1, "description": "左边缘，占页面宽度的比例。" }, "y": { "type": "number", "minimum": 0, "maximum": 1, "description": "顶部边缘，以页面高度的比例表示。" }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "宽度，占页面宽度的比例。签名宽度至少为 `0.12`。" }, "height": { "type": "number", "minimum": 0.012, "maximum": 1, "description": "高度，表示为页面高度的比例。签名的最小高度为 `0.035`。" }, "anchor": { "$ref": "#/components/schemas/SignatureFieldAnchor" }, "required": { "type": "boolean", "description": "`signature` and `initials` are required unless you set `false`. `full_name`, `date_signed` and `data` are always required. The signer can't finish a document until its required fields have a value, and a required checkbox must be ticked." }, "label": { "type": "string", "minLength": 1, "maxLength": 80, "description": "向签署人展示并显示在结果中。默认取自类型。" }, "placeholder": { "type": "string", "nullable": true, "maxLength": 80, "description": "仅支持 `text` 和 `email`。" }, "validation": { "$ref": "#/components/schemas/SignatureFieldValidation" }, "prefill": { "type": "string", "nullable": true, "description": "值的来源：`identity.full_name`、`identity.first_name`、`identity.last_name`、`identity.date_of_birth`（`DD/MM/YYYY`）、`identity.nationality`、`identity.document_number`、`identity.document_type`、`identity.issuing_country`、`identity.address`、`contact.email`、`contact.phone`、`company.name`、`company.registration_number`、`company.address`、`company.country`（KYB）、`session.vendor_data`、`metadata.`（会话 `metadata` 的键）或 `api.`（`sign.field_values` 的键）。对 `data` 为必填。`full_name` 始终使用 `identity.full_name`，`email` 使用 `contact.email`。当签署人开始签署时，`data`、`full_name` 和已验证的 `email` 字段的值将被固定。" }, "editable_when_prefilled": { "type": "boolean", "default": false, "description": "仅支持 `text` 和 `email`：签署人可以修改预填值。" }, "checked_by_default": { "type": "boolean", "default": false, "description": "仅限 `checkbox`：该框默认勾选。" }, "date_format": { "type": "string", "enum": [ "DD/MM/YYYY", "MM/DD/YYYY", "YYYY-MM-DD", "D MMMM YYYY" ], "default": "DD/MM/YYYY", "description": "仅限 `date_signed`。" } } }, "SessionSignDocument": { "type": "object", "required": [ "file_name", "content_base64" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 255, "description": "向签署人显示的标题。默认为 `file_name`。" }, "file_name": { "type": "string", "minLength": 1, "maxLength": 255, "description": "文件名，以 `.pdf` 或 `.docx` 结尾。" }, "content_base64": { "type": "string", "format": "byte", "description": "经 base64 编码的文件。PDF 文件大小上限为 20 MB 且最多 100 页，不得包含密码、脚本或附加文件。Word 文件（`.docx`）大小上限为 20 MB，在请求执行期间转换为 PDF，耗时最多 25 秒；转换后的 PDF 适用相同的限制。每次会话最多 5 个 Word 文件。包含宏、修订记录、外部内容链接或嵌入式对象的 Word 文件将被拒绝，错误码为 `signature_document_not_supported`；无法转换的文件将返回 `signature_document_conversion_failed`，均附带 `reason`。" }, "fields": { "type": "array", "description": "放置在此文档上的可选字段，最多 200 个。页码和位置基于 PDF（Word 文件则基于转换后的 PDF）。若未设置字段，签署人阅读文档并同意。", "items": { "$ref": "#/components/schemas/SignatureField" }, "maxItems": 200 } } }, "SignatureResult": { "type": "object", "description": "单个电子签名步骤中一位签名人的结果。请参阅[电子签名报告](/zh/core-technology/electronic-signature/report-electronic-signature)。", "properties": { "id": { "type": "string", "format": "uuid", "description": "将其作为 `signature_id` 传入以下载该签署人的证据或核验其签名。" }, "node_id": { "type": "string", "description": "生成它的工作流步骤。" }, "status": { "type": "string", "enum": [ "intro", "review", "code", "signing", "signed", "declined" ], "description": "签署人在该步骤中所处的进度。仅 `signed` 表示文件已签署。" }, "verdict": { "type": "string", "enum": [ "Not Finished", "Approved", "In Review", "Declined" ], "description": "步骤的结果。警告会通过其规则对其进行设置；自定义状态规则在此之后应用。" }, "level": { "type": "string", "enum": [ "simple", "aes", "qes" ], "description": "`simple`（默认）或 `aes`。`qes`（合格电子签名，QES）是尚未开放的附加功能。" }, "format": { "type": "string", "enum": [ "pdf", "pades" ], "description": "Simple 签名对应 `pdf`，Advanced (AES) 对应 `pades`。" }, "profile": { "type": "string", "nullable": true, "description": "高级（AES）签名完成签署后为 `PAdES-B-LT`，否则为 null。" }, "signer": { "type": "object", "properties": { "name": { "type": "string", "nullable": true, "description": "签署人的姓名。已验证（来自已通过的身份证件验证或会话），但 Simple 等级且没有已验证会话姓名的情况除外，此时为签署人输入的姓名且未经核验。" }, "capacity": { "type": "string", "enum": [ "self", "company" ] }, "company": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true, "description": "关键人员的职务（按申报）。" }, "roles": { "type": "array", "items": { "type": "string" }, "description": "关键人员的结构化角色（针对企业申报）。" }, "identity_session_id": { "type": "string", "format": "uuid", "description": "验证了签署人的 KYC 会话。" } } }, "identity_used": { "type": "object", "description": "签名所依赖的已验证身份。对于未关联已验证身份的 Simple 签名，该项为空。", "properties": { "session_id": { "type": "string", "format": "uuid" }, "kyc_id": { "type": "string", "format": "uuid", "nullable": true }, "verified": { "type": "boolean" }, "expected_name": { "type": "string", "nullable": true, "description": "签署人必须匹配的姓名。" } } }, "certificate": { "type": "object", "nullable": true, "description": "签署文件所用的证书。签署前为 `null`，对于简单签名则始终为 `null`。", "properties": { "issuer": { "type": "string" }, "issued_to": { "type": "string" }, "serial": { "type": "string", "description": "序列号，十六进制。" }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" } } }, "confirmation": { "type": "object", "properties": { "channel": { "type": "string", "nullable": true, "enum": [ "email", "sms" ], "description": "对于没有代码的 Simple 签名，该值为 `null`。" }, "destination": { "type": "string", "nullable": true, "description": "验证码发送至的已脱敏联系方式。" }, "confirmed_at": { "type": "string", "format": "date-time", "nullable": true }, "attempts": { "type": "integer", "description": "已输入的验证码，其中包括正确的验证码。" } } }, "timestamp": { "type": "object", "nullable": true, "description": "签名中的 RFC 3161 时间戳，由 Didit 签发。完成签名之前为 `null`，对于简单签名（Simple signature）始终为 `null`。", "properties": { "time": { "type": "string", "format": "date-time" }, "qualified": { "type": "boolean", "description": "对于 AES 始终为 `false`。" }, "valid": { "type": "boolean" } } }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "此签署人副本上的证件。用于下载已签署的文件。" }, "uuid": { "type": "string", "format": "uuid", "description": "与 `id` 相同。" }, "title": { "type": "string" }, "file_name": { "type": "string" }, "pages": { "type": "integer", "description": "已签署的证件页码。对于 Word 证件，指转换后的 PDF 页码。" }, "size_bytes": { "type": "integer" }, "sha256_original": { "type": "string", "description": "向签署人展示的文档的 SHA-256。" }, "sha256_signed": { "type": "string", "nullable": true, "description": "签署后的 PDF 的 SHA-256。" }, "status": { "type": "string", "enum": [ "signed", "declined", "not_signed", "not_reached" ], "description": "`not_signed`：已打开但未签署。`not_reached`：从未打开。" }, "opened_at": { "type": "string", "format": "date-time", "nullable": true }, "read_at": { "type": "string", "format": "date-time", "nullable": true, "description": "当步骤有要求时，签署人到达无字段证件末尾的时间。" }, "read_to_end": { "type": "boolean" }, "consented_at": { "type": "string", "format": "date-time", "nullable": true, "description": "签署人同意无字段证件的时间，或完成有字段证件中各个字段的时间。" }, "consent": { "type": "boolean" }, "signed_file": { "type": "string", "nullable": true, "description": "签署后的 PDF 路径（签署完成后）。参见[下载已签署证件](/zh/sessions-api/electronic-signature/download-signed-document)。" }, "mode": { "type": "string", "enum": [ "fields", "read_and_agree" ], "description": "带有字段的证件为 `fields`，没有字段的证件为 `read_and_agree`。" }, "source_format": { "type": "string", "enum": [ "pdf", "docx" ], "description": "`pdf`，或者对于 Didit 转换为 PDF 的 Word 文档为 `docx`。" }, "conversion": { "type": "object", "nullable": true, "description": "PDF 文件为 `null`。对于 Word 文档，则包含原始文件和转换后的文件。", "properties": { "from": { "type": "string", "enum": [ "docx" ] }, "file_name": { "type": "string", "description": "您的原始 Word 文件名。" }, "sha256": { "type": "string", "description": "您原始 Word 文件的 SHA-256。" }, "size_bytes": { "type": "integer", "description": "您的原始 Word 文件的大小。" }, "converter": { "type": "string", "description": "生成该 PDF 的转换器版本。" } } }, "fields": { "type": "array", "description": "证件上的字段及其对应值。对于没有字段的证件，该项为空。", "items": { "$ref": "#/components/schemas/SignatureFieldResult" } } } } }, "adopted_signature": { "type": "object", "nullable": true, "description": "签署人为签名和首字母字段采用的签名及首字母。在签署人采用之前为 `null`。", "properties": { "method": { "type": "string", "enum": [ "typed", "drawn" ], "description": "`typed`：手写体风格的已验证姓名。`drawn`：使用手指或鼠标绘制。" }, "font": { "type": "string", "nullable": true, "description": "键入签名的手写样式。手绘签名时为 `null`。" }, "adopted_at": { "type": "string", "format": "date-time" } } }, "electronic_signature_consent_at": { "type": "string", "format": "date-time", "nullable": true, "description": "签署人在审核屏幕上同意对证件进行电子签名的时间。当任何证件包含字段时设置。" }, "evidence_file": { "type": "string", "nullable": true, "description": "签名完成后证据 PDF 的路径。参见[下载签名证据](/zh/sessions-api/electronic-signature/download-evidence)。" }, "warnings": { "type": "array", "description": "针对该签名人的警告。请参阅[电子签名警告](/zh/core-technology/electronic-signature/warnings-electronic-signature)。", "items": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "SIGNATURE_DECLINED", "SIGNATURE_OTP_FAILED", "SIGNATURE_NAME_MISMATCH", "SIGNATURE_IDENTITY_NOT_VERIFIED", "SIGNATURE_DOCUMENT_CHANGED", "SIGNATURE_FIELD_DATA_MISSING" ] }, "node_id": { "type": "string" } } } }, "validation": { "type": "object", "nullable": true, "description": "已签名证件的最新加密核验结果。在证件签名之前为 `null`。如果 Didit 无法确认签名结果，则为 `{\"valid\": null, \"reason\": \"signature_provider_outcome_unknown\", \"checked_at\": ...}`，且 `status` 保持为 `signing`：请将其视为未签名。", "properties": { "valid": { "type": "boolean", "nullable": true, "description": "当所有证件均有效时为 `true`。当无法确认签名结果时为 `null`。" }, "reason": { "type": "string", "description": "当 `valid` 为 `null` 时设置：`signature_provider_outcome_unknown`。" }, "checked_at": { "type": "string", "format": "date-time" }, "documents": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "checked_at": { "type": "string", "format": "date-time" }, "valid": { "type": "boolean", "description": "当签名和时间戳均有效且可信时为 `true`。" }, "integrity": { "type": "boolean", "description": "当证件自签名后未发生更改时为 `true`。" }, "trusted": { "type": "boolean", "description": "当签名证书链接到受信任的根证书时为 `true`。" }, "revoked": { "type": "boolean" }, "trusted_list": { "type": "object", "description": "欧盟信任列表（EU Trusted List）检查。对于 AES：`{\"status\": \"not_applicable\", \"reason\": \"aes_not_qualified\"}`。", "properties": { "status": { "type": "string" }, "reason": { "type": "string" } } }, "certificate": { "type": "object", "nullable": true, "description": "签署文件所用的证书。签署前为 `null`，对于简单签名则始终为 `null`。", "properties": { "issuer": { "type": "string" }, "issued_to": { "type": "string" }, "serial": { "type": "string", "description": "序列号，十六进制。" }, "valid_from": { "type": "string", "format": "date-time" }, "valid_until": { "type": "string", "format": "date-time" } } }, "timestamp": { "type": "object", "nullable": true, "description": "签名中的 RFC 3161 时间戳，由 Didit 签发。完成签名之前为 `null`，对于简单签名（Simple signature）始终为 `null`。", "properties": { "time": { "type": "string", "format": "date-time" }, "qualified": { "type": "boolean", "description": "对于 AES 始终为 `false`。" }, "valid": { "type": "boolean" } } } } } } } }, "declined_at": { "type": "string", "format": "date-time", "nullable": true }, "declined_action": { "type": "string", "enum": [ "DECLINE", "REVIEW", "NO_ACTION" ] }, "signed_at": { "type": "string", "format": "date-time", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "description": "签名链接失效的时间。" }, "email_sent_at": { "type": "string", "format": "date-time", "nullable": true }, "email_unavailable_reason": { "type": "string", "nullable": true }, "ip_address": { "type": "string", "nullable": true, "description": "签署人请求验证码时的地址。" }, "place": { "type": "string", "nullable": true, "description": "未采集：始终为 `null`。" }, "place_unavailable_reason": { "type": "string", "nullable": true, "enum": [ "not_collected" ] } } }, "SignatureFieldValidation": { "type": "object", "nullable": true, "description": "`text` 字段值的规则。控制台预览、签署流程和 API 应用相同的规则。", "properties": { "kind": { "type": "string", "enum": [ "any", "letters", "number", "email", "pattern" ], "description": "`letters`：任何文字系统中的字母、空格、连字符和撇号。`number`：数字以及可选的小数分隔符。`pattern`：值必须与 `pattern` 匹配。" }, "min_length": { "type": "integer", "minimum": 0, "maximum": 500, "description": "从 `0` 到 `max_length`。" }, "max_length": { "type": "integer", "minimum": 1, "maximum": 500, "default": 120 }, "pattern": { "type": "string", "nullable": true, "minLength": 1, "maxLength": 200, "description": "当 `kind: \"pattern\"` 时必填。整个值必须匹配的正则表达式。不支持环视（lookarounds）和反向引用（backreferences）。" }, "message": { "type": "string", "nullable": true, "maxLength": 120, "description": "向签署人展示，替代默认错误信息。" } } }, "SignatureFieldAnchor": { "type": "object", "description": "根据文档中的一段文本放置字段，而不是使用位置坐标。Didit 不会从 PDF 中移除该文本，因此请将其设置为与页面背景相同的颜色。未找到该文本时，调用将返回 `400` 并附带 `field_anchor_not_found`。请参阅[通过定位文本放置字段](/zh/sessions-api/create-session#按锚点文本放置字段)。", "required": [ "text" ], "properties": { "text": { "type": "string", "minLength": 1, "maxLength": 64, "description": "在证件中搜索的文本。对于 Word 文件，指在转换后的 PDF 中搜索。" }, "occurrence": { "type": "string", "enum": [ "first", "all" ], "default": "first", "description": "`all` 为每个匹配项放置一个字段；首个匹配项之后的键将附加 `_2`、`_3` 等后缀。" }, "offset_x": { "type": "number", "description": "添加到文本左边缘，表示为页面宽度的比例。" }, "offset_y": { "type": "number", "description": "添加到文本上边缘，表示为页面高度的比例。" }, "width": { "type": "number", "minimum": 0.02, "maximum": 1, "description": "字段宽度，占页面宽度的比例。" }, "height": { "type": "number", "minimum": 0.012, "maximum": 1, "description": "字段高度，表示为页面高度的比例。" } } }, "SignatureFieldResult": { "type": "object", "description": "已签署证件的一个字段，包含其在此签署人副本上的值。请参阅 [Fields](/zh/core-technology/electronic-signature/report-electronic-signature#字段)。", "properties": { "key": { "type": "string", "description": "字段的键，与 `sign.field_values` 中使用的相同。" }, "type": { "type": "string", "enum": [ "signature", "initials", "full_name", "date_signed", "text", "checkbox", "email", "data" ] }, "role": { "type": "string", "enum": [ "verified_person", "legal_representative", "key_people" ] }, "label": { "type": "string" }, "page": { "type": "integer", "description": "页码，从 1 开始。对于 Word 证件，指转换后 PDF 的页码。" }, "x": { "type": "number", "description": "左边缘，占页面宽度的比例。" }, "y": { "type": "number", "description": "顶部边缘，以页面高度的比例表示。" }, "width": { "type": "number", "description": "宽度，占页面宽度的比例。" }, "height": { "type": "number", "description": "高度，表示为页面高度的比例。" }, "required": { "type": "boolean" }, "value": { "nullable": true, "description": "`text`、`email`、`full_name`、`date_signed` 和 `data` 为字符串，`checkbox` 为布尔值，应用的签名或缩写签名为 `true`。为空时为 `null`。" }, "display_value": { "type": "string", "nullable": true, "description": "页面上印刻的值：日期采用字段的 `date_format`，复选框为 `Yes` 或 `No`，签名或姓名缩写为 `Signed`。" }, "value_source": { "type": "string", "nullable": true, "enum": [ "signer", "identity", "contact", "company", "session", "metadata", "api", "signing_time", null ], "description": "该值的来源：`signer`（由签署人输入、勾选或应用）、`identity`（核验的证件）、`contact`（核验的邮箱或电话）、`company`（核验的公司）、`session`（`vendor_data`）、`metadata`、`api`（`sign.field_values`）或 `signing_time`（签署日期）。" }, "filled_at": { "type": "string", "format": "date-time", "nullable": true }, "image_url": { "type": "string", "nullable": true, "description": "仅限签名和姓名首字母：所应用图像的路径。请参阅[下载签名图像](/zh/sessions-api/electronic-signature/download-field-image)。" }, "value_unavailable_reason": { "type": "string", "nullable": true, "enum": [ "source_empty", null ], "description": "当预填字段在会话中没有值且 `signature_field_data_missing_action` 允许签署人仍然签名时，为 `source_empty`。" } } }, "VaspDirectoryWidgetEntry": { "type": "object", "description": "终端用户的 VASP 选择器显示的内容：该 VASP 是谁以及是否可达。", "properties": { "id": { "type": "string", "format": "uuid", "description": "条目 ID，用于 GET /v3/travel-rule/vasps/{vasp_id}/。" }, "kind": { "type": "string", "enum": [ "directory", "didit" ], "description": "directory 表示共享目录条目；didit 表示 Didit 网络成员。" }, "name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string", "description": "数据源所提供的 ISO 3166 国家/地区代码。" }, "domains": { "type": "array", "items": { "type": "string" }, "description": "VASP 的 Web 域名。对于 Didit 网络成员始终为空。" }, "reachable": { "type": "boolean", "description": "您的应用是否有通往该 VASP 或其某个品牌实体的可用路由。对于 Didit 网络成员始终为 true。" } } }, "TravelRuleDataSharingFields": { "type": "object", "description": "Didit 就您自己的用户按实体类型向交易对手 VASP 发送的字段。无论列表内容如何，始终会发送 `name` 和 `wallet_address`。您未选择过的实体类型将共享所有字段。空列表也是一种选择：仅共享姓名和钱包。", "properties": { "individual": { "type": "array", "items": { "type": "string", "enum": [ "name", "wallet_address", "address", "national_id", "customer_identification", "date_of_birth", "place_of_birth" ] }, "description": "共享的自然人字段。" }, "company": { "type": "array", "items": { "type": "string", "enum": [ "name", "wallet_address", "address", "national_id", "customer_identification" ] }, "description": "共享的法人字段。" } } }, "TravelRuleMatchingRules": { "type": "object", "description": "按实体类型，交易对手数据的各个字段与您持有的数据进行比对的严格程度。省略的字段将保留其默认值。`NONE` 跳过比对，`STRICT` 要求词语完全一致，`CONTAINS` 接受一个值的所有词均出现在另一个值中，`DEFAULT` 为标准子集匹配，`FUZZY` 接受相近的拼写（对于出生日期，允许日和月调换）。", "properties": { "individual": { "type": "object", "description": "自然人规则。", "properties": { "name": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "默认：遵循 `name_matching_strictness`。" }, "date_of_birth": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "默认为 `NONE`。" }, "address": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "默认为 `NONE`。" }, "account": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "交易所路由经过的钱包。默认值为 `STRICT`。" } } }, "company": { "type": "object", "description": "法人规则。", "properties": { "name": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "默认：遵循 `name_matching_strictness`。" }, "address": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "默认为 `NONE`。" }, "account": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ], "description": "交易所路由经过的钱包。默认值为 `STRICT`。" } } } } }, "TravelRuleDataMatch": { "type": "object", "nullable": true, "description": "转账当事方数据与对方已知的钱包持有人信息之间的逐字段比对。该项仅指明字段和结果，绝不包含具体值，因此在交易对手数据被脱敏的同时仍保持可读性。在执行比对前为 null。", "properties": { "matched": { "type": "boolean", "description": "当比对的字段均无差异时为 true。" }, "mismatched_fields": { "type": "array", "items": { "type": "string", "enum": [ "name", "date_of_birth", "address", "account" ] }, "description": "存在差异的字段。" }, "fields": { "type": "object", "description": "针对该参与方实体类型所比对的每个字段对应一个条目（`name`、`date_of_birth`、`address`、`account`；企业没有 `date_of_birth`）。", "additionalProperties": { "type": "object", "properties": { "result": { "type": "string", "enum": [ "matched", "mismatched", "not_compared" ], "description": "当规则为 `NONE` 或任一方该字段均无值时为 `not_compared`。" }, "strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ] } } } } } }, "TravelRuleDataUnmasked": { "type": "object", "nullable": true, "description": "交易对手数据解除掩码时刻的审计记录。当数据仍处于掩码状态时以及出站转账时为 null。", "properties": { "at": { "type": "string", "format": "date-time" }, "reason": { "type": "string", "enum": [ "ownership_confirmed", "wallet_proof", "address_book_match", "own_verified_wallet", "inquiry_approved", "known_payment_method", "travel_address" ], "description": "确认股权结构的依据：ownership_confirmed（您通过控制台或 API 进行的确认）、wallet_proof（小组件中的钱包证明，或在创建时设置的 INTERNAL 入站转账）、address_book_match（已验证的地址簿钱包）、own_verified_wallet（您的用户本人的已验证钱包）、inquiry_approved（您对入站 TRP 问讯或 GTR 或 Sygna 消息的批准）、known_payment_method（您的用户已用于付款的钱包）或 travel_address（按钱包分配的 Travel Address 指定了该钱包）。" }, "actor": { "type": "string", "description": "确认此项的主体：控制台用户的邮箱或 API 密钥的标签。自动决策时为空白。" } } }, "TravelRuleMessageAttachment": { "type": "object", "nullable": true, "description": "附加到消息的证件，像任何其他交易证件一样存储。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "label": { "type": "string", "nullable": true }, "note": { "type": "string", "nullable": true }, "uploaded_by": { "type": "string", "nullable": true, "description": "附加该文件的主体。在提取门户中，您发送的文件会显示您的 VASP 名称，绝不会显示其背后的个人或 API 密钥。" }, "created_at": { "type": "string", "format": "date-time" }, "files": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "file_url": { "type": "string", "nullable": true, "description": "有时限的下载 URL。" }, "original_filename": { "type": "string" }, "file_size": { "type": "integer" } } } } } }, "TravelRuleMessage": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "MESSAGE", "DOCUMENT_REQUEST" ] }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "`OUTBOUND` 是读取方自身发送的内容。在 pickup 门户中，方向是来自交易对手一方。" }, "author": { "type": "string", "description": "在其所属方写入该内容的主体：控制台用户的邮箱、API 密钥标签，或对方 VASP 的名称。" }, "body": { "type": "string" }, "requested_documents": { "type": "array", "items": { "type": "string" }, "description": "DOCUMENT_REQUEST 所请求的内容，以请求者的措辞描述。" }, "reply_to": { "type": "string", "format": "uuid", "nullable": true }, "fulfilled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "一旦对 DOCUMENT_REQUEST 的回复携带了证件，便会在该请求上设置。" }, "attachment": { "$ref": "#/components/schemas/TravelRuleMessageAttachment" }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleMessageCreateRequest": { "type": "object", "description": "以 JSON 格式发送，或以 multipart/form-data 格式发送并将附件放入 `files` 中。", "properties": { "kind": { "type": "string", "enum": [ "MESSAGE", "DOCUMENT_REQUEST" ], "default": "MESSAGE" }, "body": { "type": "string", "maxLength": 5000, "description": "MESSAGE 所必需，除非附加了文件。" }, "requested_documents": { "type": "array", "items": { "type": "string", "maxLength": 255 }, "maxItems": 10, "description": "DOCUMENT_REQUEST 所必需（至少一个），且仅允许在该类型中使用。" }, "reply_to": { "type": "string", "format": "uuid", "nullable": true, "description": "同一笔转账的消息。携带证件的回复可满足其所响应的证件请求。" }, "files": { "type": "array", "items": { "type": "string", "format": "binary" }, "maxItems": 5, "description": "仅限 multipart。最多 5 个文件，每个文件不超过 10 MB。" } } }, "SessionDeletionJob": { "type": "object", "description": "正在后台运行的批量会话删除：包含进度和按结果统计的数量，绝不包含其删除了哪些会话。", "properties": { "job_id": { "type": "string", "format": "uuid", "description": "使用此 ID 轮询 `GET /v3/sessions/delete/{job_id}/`。" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ], "description": "`PENDING`：已接受，尚未开始。`PROCESSING`：正在删除；`processed` 和 `outcomes` 正在更新。`COMPLETED`：所有选定的会话均已处理。`FAILED`：任务提前停止；详见 `error`。" }, "total": { "type": "integer", "description": "请求删除时选定的会话。" }, "processed": { "type": "integer", "description": "截至目前作业已处理完成的会话。" }, "outcomes": { "type": "object", "description": "以各项结果结束的会话数量。每个键始终存在。", "properties": { "deleted": { "type": "integer", "description": "与人脸特征向量一同删除的会话。" }, "none": { "type": "integer", "description": "已删除且不包含人脸特征向量的会话。" }, "retained_with_user": { "type": "integer", "description": "根据请求或应用策略的要求，在为其用户保留了一个不含图像的生物特征模板的同时删除的会话。" }, "ineligible_no_vendor_user": { "type": "integer", "description": "因请求保留但未关联用户而连同其人脸特征向量一同被删除的会话。" }, "failed_retryable": { "type": "integer", "description": "报告为未删除的会话。作业会自动重试其自身未能删除的分组，而不会将其计入此处。" }, "already_deleted": { "type": "integer", "description": "在任务处理到所选会话时，这些会话已被删除（例如被另一个请求删除）。" } } }, "deleted_child_verifications": { "type": "integer", "description": "已被删除的企业验证所创建的验证数，已随之一并删除。对于由 `POST /v3/sessions/delete/` 启动的任务，此项始终为 `0`，因为该任务仅删除 KYC 会话。" }, "error": { "type": "string", "nullable": true, "description": "除非 `status` 为 `FAILED`，否则为 `null`；若失败则表示删除停止的原因。该作业尚未处理到的会话仍保留在原处：可重复该请求以继续删除它们。" }, "created_at": { "type": "string", "format": "date-time", "description": "请求删除的时间。" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "任务完成时间；运行中时为 `null`。" } } }, "EntityStatusUpdateRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ACTIVE", "FLAGGED", "BLOCKED" ], "description": "新的生命周期状态。`BLOCKED` 还会将 `vendor_data` 添加到系统黑名单中。" } } }, "AMLMonitoringToggleResult": { "oneOf": [ { "type": "object", "required": [ "users_total", "already_enabled", "with_existing_aml", "needing_screening", "skipped_no_identity_data", "skipped_blocked", "estimated_screening_cost_usd", "estimated_annual_monitoring_cost_usd", "balance_sufficient", "unmatched" ], "description": "费用预览。当 estimate_only 为 true 时直接返回（不写入任何内容）。", "properties": { "users_total": { "type": "integer", "description": "所选条件匹配的档案。" }, "already_enabled": { "type": "integer", "description": "已处于监控状态的档案（启用时无需操作；禁用时将关闭这些档案的监控）。" }, "with_existing_aml": { "type": "integer", "description": "现有 AML 筛查将被切换为受监控状态的档案（不进行新的筛查）。" }, "needing_screening": { "type": "integer", "description": "没有任何 AML 筛查记录、将首先进行筛查的档案（按常规 AML 筛查计费）。" }, "skipped_no_identity_data": { "type": "integer", "description": "因缺少身份数据而无法进行筛查的档案。" }, "skipped_blocked": { "type": "integer", "description": "将被跳过的已拉黑用户（对于企业始终为 0）。" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "新增筛查的一次性费用。" }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "即将纳入监控的档案的年度监控成本。" }, "balance_sufficient": { "type": "boolean", "description": "组织余额是否足以支付筛查以及第一年的监控费用。" }, "unmatched": { "type": "array", "items": { "type": "string" }, "description": "请求中与该应用中的任何档案均不匹配的标识符，与发送时完全一致。" } } }, { "type": "object", "required": [ "job_id", "status", "is_enabled", "target_type", "total", "processed", "outcomes", "results", "error", "created_at", "completed_at", "estimate", "unmatched" ], "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean", "description": "当任务启用监控时为 true，停用监控时为 false。" }, "target_type": { "type": "string", "enum": [ "user", "business" ], "description": "该作业切换哪个配置文件系列。" }, "total": { "type": "integer", "description": "该任务处理的档案。" }, "processed": { "type": "integer", "description": "截至目前已处理的档案。" }, "outcomes": { "type": "object", "description": "每条记录的结果计数器。每个选定的个人资料都会准确归入一个计数器；不会静默跳过任何内容。", "properties": { "enabled": { "type": "integer", "description": "已在现有 AML 筛查上启用监控。" }, "screened_and_enabled": { "type": "integer", "description": "已创建新的 AML 筛查（已计费）并对其启用了监控。" }, "already_enabled": { "type": "integer", "description": "监控已处于活动状态；未发生任何更改，也未计费。" }, "disabled": { "type": "integer", "description": "已在该档案的所有 AML 筛查中关闭监控。" }, "skipped_no_identity_data": { "type": "integer", "description": "已跳过：资料缺少进行筛查所需的姓名、出生日期和国家/地区（用户）或名称（企业）。" }, "skipped_blocked": { "type": "integer", "description": "已跳过：用户已被封禁。" }, "skipped_sandbox": { "type": "integer", "description": "已跳过：沙盒应用，不创建筛查。" }, "failed_provider": { "type": "integer", "description": "无法完成筛查；请稍后重试。" }, "failed_insufficient_balance": { "type": "integer", "description": "任务运行时余额耗尽。" } } }, "results": { "type": "array", "description": "每个已处理的档案对应一个条目，按处理顺序排列。在任务运行期间逐步增加；状态变为 COMPLETED 时完成。仅对通过 API 启动的任务进行记录。", "items": { "type": "object", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "个人资料的 Didit 内部 ID。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您为资料指定的自身标识符。" }, "outcome": { "type": "string", "enum": [ "enabled", "screened_and_enabled", "already_enabled", "disabled", "skipped_no_identity_data", "skipped_blocked", "skipped_sandbox", "failed_provider", "failed_insufficient_balance" ] } } } }, "error": { "type": "string", "nullable": true, "description": "状态为 FAILED 时的通用失败消息；详细原因保留在平台端。" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "estimate": { "type": "object", "description": "费用预览。当 estimate_only 为 true 时直接返回（不写入任何内容）。", "properties": { "users_total": { "type": "integer", "description": "所选条件匹配的档案。" }, "already_enabled": { "type": "integer", "description": "已处于监控状态的档案（启用时无需操作；禁用时将关闭这些档案的监控）。" }, "with_existing_aml": { "type": "integer", "description": "现有 AML 筛查将被切换为受监控状态的档案（不进行新的筛查）。" }, "needing_screening": { "type": "integer", "description": "没有任何 AML 筛查记录、将首先进行筛查的档案（按常规 AML 筛查计费）。" }, "skipped_no_identity_data": { "type": "integer", "description": "因缺少身份数据而无法进行筛查的档案。" }, "skipped_blocked": { "type": "integer", "description": "将被跳过的已拉黑用户（对于企业始终为 0）。" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "新增筛查的一次性费用。" }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "即将纳入监控的档案的年度监控成本。" }, "balance_sufficient": { "type": "boolean", "description": "组织余额是否足以支付筛查以及第一年的监控费用。" } } }, "unmatched": { "type": "array", "items": { "type": "string" }, "description": "请求中与该应用中的任何档案均不匹配的标识符，与发送时完全一致。它们不属于任务的一部分。" } } } ] }, "AMLMonitoringJob": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean", "description": "当任务启用监控时为 true，停用监控时为 false。" }, "target_type": { "type": "string", "enum": [ "user", "business" ], "description": "该作业切换哪个配置文件系列。" }, "total": { "type": "integer", "description": "该任务处理的档案。" }, "processed": { "type": "integer", "description": "截至目前已处理的档案。" }, "outcomes": { "type": "object", "description": "每条记录的结果计数器。每个选定的个人资料都会准确归入一个计数器；不会静默跳过任何内容。", "properties": { "enabled": { "type": "integer", "description": "已在现有 AML 筛查上启用监控。" }, "screened_and_enabled": { "type": "integer", "description": "已创建新的 AML 筛查（已计费）并对其启用了监控。" }, "already_enabled": { "type": "integer", "description": "监控已处于活动状态；未发生任何更改，也未计费。" }, "disabled": { "type": "integer", "description": "已在该档案的所有 AML 筛查中关闭监控。" }, "skipped_no_identity_data": { "type": "integer", "description": "已跳过：资料缺少进行筛查所需的姓名、出生日期和国家/地区（用户）或名称（企业）。" }, "skipped_blocked": { "type": "integer", "description": "已跳过：用户已被封禁。" }, "skipped_sandbox": { "type": "integer", "description": "已跳过：沙盒应用，不创建筛查。" }, "failed_provider": { "type": "integer", "description": "无法完成筛查；请稍后重试。" }, "failed_insufficient_balance": { "type": "integer", "description": "任务运行时余额耗尽。" } } }, "results": { "type": "array", "description": "每个已处理的档案对应一个条目，按处理顺序排列。在任务运行期间逐步增加；状态变为 COMPLETED 时完成。仅对通过 API 启动的任务进行记录。", "items": { "type": "object", "properties": { "didit_internal_id": { "type": "string", "format": "uuid", "description": "个人资料的 Didit 内部 ID。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您为资料指定的自身标识符。" }, "outcome": { "type": "string", "enum": [ "enabled", "screened_and_enabled", "already_enabled", "disabled", "skipped_no_identity_data", "skipped_blocked", "skipped_sandbox", "failed_provider", "failed_insufficient_balance" ] } } } }, "error": { "type": "string", "nullable": true, "description": "状态为 FAILED 时的通用失败消息；详细原因保留在平台端。" }, "created_at": { "type": "string", "format": "date-time" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true }, "estimate": { "type": "object", "description": "费用预览。当 estimate_only 为 true 时直接返回（不写入任何内容）。", "properties": { "users_total": { "type": "integer", "description": "所选条件匹配的档案。" }, "already_enabled": { "type": "integer", "description": "已处于监控状态的档案（启用时无需操作；禁用时将关闭这些档案的监控）。" }, "with_existing_aml": { "type": "integer", "description": "现有 AML 筛查将被切换为受监控状态的档案（不进行新的筛查）。" }, "needing_screening": { "type": "integer", "description": "没有任何 AML 筛查记录、将首先进行筛查的档案（按常规 AML 筛查计费）。" }, "skipped_no_identity_data": { "type": "integer", "description": "因缺少身份数据而无法进行筛查的档案。" }, "skipped_blocked": { "type": "integer", "description": "将被跳过的已拉黑用户（对于企业始终为 0）。" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2, "description": "新增筛查的一次性费用。" }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07, "description": "即将纳入监控的档案的年度监控成本。" }, "balance_sufficient": { "type": "boolean", "description": "组织余额是否足以支付筛查以及第一年的监控费用。" } } }, "unmatched": { "type": "array", "items": { "type": "string" }, "description": "请求中与该应用中的任何档案均不匹配的标识符，与发送时完全一致。它们不属于任务的一部分。" } } }, "OngoingMonitoringToggleRequest": { "type": "object", "required": [ "is_enabled" ], "properties": { "is_enabled": { "type": "boolean", "description": "为 true 表示启用监控，为 false 表示停用监控。" }, "estimate_only": { "type": "boolean", "default": false, "description": "为 true 时，返回费用估算且不执行任何写入。" }, "update_all": { "type": "boolean", "default": false, "description": "应用于该应用的所有实体（存在 filter_* 参数时受其限定）。" }, "filter_search": { "type": "string" }, "filter_status": { "type": "array", "items": { "type": "string" } }, "filter_country": { "type": "string" }, "filter_date_from": { "type": "string", "format": "date" }, "filter_date_to": { "type": "string", "format": "date" }, "didit_internal_id_list": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "要切换状态的实体。除非 update_all 为 true，否则为必填项。" } } }, "OngoingMonitoringJob": { "type": "object", "properties": { "job_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "COMPLETED", "FAILED" ] }, "is_enabled": { "type": "boolean" }, "total": { "type": "integer" }, "processed": { "type": "integer" }, "outcomes": { "type": "object", "description": "按实体划分的结果计数器。没有任何内容会被静默跳过：每个请求的实体都会精确解析为一个计数器。", "properties": { "enabled": { "type": "integer", "description": "已在现有 AML 筛查上启用监控。" }, "screened_and_enabled": { "type": "integer", "description": "已创建新的 AML 筛查（已计费）并启用了监控。" }, "already_enabled": { "type": "integer", "description": "监控已处于活动状态（历史重复行已合并）。" }, "disabled": { "type": "integer", "description": "已在实体的每条 AML 记录上禁用监控。" }, "skipped_no_identity_data": { "type": "integer", "description": "已跳过：无可用于筛查的姓名 + 出生日期 + 国家/地区。" }, "skipped_blocked": { "type": "integer", "description": "已跳过：用户已被封禁。" }, "skipped_sandbox": { "type": "integer", "description": "已跳过：沙盒应用。" }, "failed_provider": { "type": "integer", "description": "筛查服务商调用失败。" }, "failed_insufficient_balance": { "type": "integer", "description": "任务运行中途余额耗尽。" } } }, "error": { "type": "string", "nullable": true }, "estimate": { "type": "object", "description": "费用预览。当 estimate_only 为 true 时直接返回（不执行写入操作）。", "properties": { "users_total": { "type": "integer", "description": "所选范围内的实体。" }, "already_enabled": { "type": "integer" }, "with_existing_aml": { "type": "integer", "description": "现有 AML 筛查将切换为受监控状态的实体。" }, "needing_screening": { "type": "integer", "description": "未进行过任何 AML 筛查的主体，将优先被筛查（计费）。" }, "skipped_no_identity_data": { "type": "integer" }, "skipped_blocked": { "type": "integer" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2 }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07 }, "balance_sufficient": { "type": "boolean" } } } } }, "OngoingMonitoringToggleResult": { "oneOf": [ { "type": "object", "description": "费用预览。当 estimate_only 为 true 时直接返回（不执行写入操作）。", "properties": { "users_total": { "type": "integer", "description": "所选范围内的实体。" }, "already_enabled": { "type": "integer" }, "with_existing_aml": { "type": "integer", "description": "现有 AML 筛查将切换为受监控状态的实体。" }, "needing_screening": { "type": "integer", "description": "未进行过任何 AML 筛查的主体，将优先被筛查（计费）。" }, "skipped_no_identity_data": { "type": "integer" }, "skipped_blocked": { "type": "integer" }, "estimated_screening_cost_usd": { "type": "number", "example": 0.2 }, "estimated_annual_monitoring_cost_usd": { "type": "number", "example": 0.07 }, "balance_sufficient": { "type": "boolean" } } }, { "$ref": "#/components/schemas/OngoingMonitoringJob" } ] }, "CaseBlueprintPresetInstallResult": { "type": "object", "properties": { "created": { "type": "array", "items": { "type": "string" } } } }, "CaseBulkUpdateResult": { "type": "object", "properties": { "updated": { "type": "integer" }, "failures": { "type": "array", "items": { "type": "object", "properties": { "case_uuid": { "type": "string", "format": "uuid" }, "detail": { "type": "string" } } } } } }, "RegulatoryReportList": { "type": "object", "properties": { "count": { "type": "integer", "description": "匹配行数，出于性能考虑上限为 100。" }, "next": { "type": "string", "nullable": true }, "previous": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/RegulatoryReportDetail" } } } }, "EntityNetworkMembershipList": { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/EntityNetworkMembership" } } } }, "SessionDecision": { "type": "object", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "会话的唯一标识符。" }, "session_kind": { "type": "string", "enum": [ "user", "business" ], "description": "指示这是用户验证（KYC）还是企业验证（KYB）会话的鉴别器。当为 `user` 时，KYC 功能数组（`id_verifications`、`nfc_verifications`、`liveness_checks`、`face_matches`、`poa_verifications`、`document_ai_documents`、`database_validations` 等）适用，且企业数组不存在。当为 `business` 时，payload 转为携带 `registry_checks`、`document_verifications`、`key_people_checks` 以及共享数组（`aml_screenings`、`phone_verifications`、`email_verifications`、`ip_analyses`、`questionnaire_responses`）。**当传递 `include=events` 时省略**：事件结构仅存在于用户会话中，因此该变体中去除了此鉴别器。" }, "shared_from_session": { "type": "string", "format": "uuid", "nullable": true, "description": "对于使用 `POST /v3/session/import-shared/` 克隆的会话：为源应用中原始会话的 `session_id`。对于所有其他会话为 `null`。传入 `include=events` 时省略。" }, "shared_from_session_number": { "type": "integer", "nullable": true, "description": "当此会话是从您组织的另一个应用导入时，为源会话的 `session_number`。否则为 `null`。" }, "session_number": { "type": "integer", "description": "会话编号。", "nullable": true }, "session_url": { "type": "string", "format": "uri", "description": "会话的 URL。", "nullable": true }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Awaiting User", "In Review", "Approved", "Declined", "Resubmitted", "Expired", "Kyc Expired", "Abandoned" ], "description": "会话的整体生命周期状态，即汇总的工作流结果。终态值为 `Approved`、`Declined`、`In Review`、`Expired`、`Kyc Expired` 和 `Abandoned`；`Not Started`、`In Progress`、`Awaiting User` 和 `Resubmitted` 表示会话仍在工作流流转中。" }, "status_override": { "type": "object", "nullable": true, "description": "在审核员手动设置 `status` 时存在。当状态为自动设置时为 `null`。可用于区分人工审核通过与自动通过。", "properties": { "overridden_at": { "type": "string", "format": "date-time", "nullable": true }, "automatic_status": { "type": "string", "nullable": true, "description": "平台自身检查得出的状态。" } } }, "decision_trace": { "type": "object", "description": "状态是如何达成的：由谁设置以及触发了哪些警告。", "properties": { "status": { "type": "string", "description": "会话状态。" }, "decided_by": { "type": "string", "nullable": true, "enum": [ "manual", "automatic", "investigator", null ], "description": "设置该状态的人员。会话尚未做出决策时为 `null`。" }, "decided_at": { "type": "string", "format": "date-time", "nullable": true }, "automatic_status": { "type": "string", "nullable": true, "description": "平台自身检查得出的结论，在人工决策后该值与 `status` 不同。" }, "terminal_node_id": { "type": "string", "nullable": true, "description": "结束会话的工作流状态节点（若有）。" }, "actor": { "type": "object", "nullable": true, "description": "负责人工决策的审核员。", "properties": { "user": { "type": "string", "nullable": true }, "actor_type": { "type": "string", "nullable": true } } }, "warning_counts": { "type": "object", "description": "按 `log_type`（`error`、`warning`、`information`）划分的警告数及 `total`。", "additionalProperties": { "type": "integer" } }, "status_warnings": { "type": "array", "description": "会将状态设置为 `Declined` 或 `In Review` 的警告。", "items": { "type": "object", "properties": { "risk": { "type": "string" }, "feature": { "type": "string", "nullable": true }, "node_id": { "type": "string", "nullable": true }, "log_type": { "type": "string", "nullable": true }, "check_status": { "type": "string", "nullable": true }, "source": { "type": "string", "description": "产生该警告的 payload 列表，例如 `id_verifications`。" }, "short_description": { "type": "string", "nullable": true } } } } } }, "linked_records": { "type": "object", "nullable": true, "description": "与会话关联的其他记录的摘要。没有可显示内容时以及声明了年龄确认标准的工作流为 `null`。", "properties": { "same_face": { "type": "object", "nullable": true, "description": "人脸与本次会话的人脸搜索之一相匹配的其他人员。", "properties": { "count": { "type": "integer" }, "best_match": { "type": "object", "nullable": true, "properties": { "session_id": { "type": "string", "format": "uuid", "nullable": true }, "session_number": { "type": "integer", "nullable": true }, "vendor_user_id": { "type": "string", "format": "uuid", "nullable": true }, "similarity_percentage": { "type": "number", "nullable": true } } } } }, "earlier_verifications": { "type": "object", "nullable": true, "properties": { "count": { "type": "integer" }, "vendor_user_id": { "type": "string", "format": "uuid", "nullable": true } } }, "networks": { "type": "object", "nullable": true, "properties": { "count": { "type": "integer" }, "open": { "type": "integer" }, "dismissed": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "network_id": { "type": "string", "format": "uuid" }, "display_number": { "type": "integer", "nullable": true }, "name": { "type": "string" }, "status": { "type": "string" }, "risk_score": { "type": "number", "nullable": true } } } } } } } }, "workflow_id": { "type": "string", "format": "uuid", "description": "生成此会话的工作流组的稳定标识符。工作流具有多版本，该值标识工作流本身，而非特定版本。", "nullable": true }, "features": { "type": "array", "items": { "type": "string", "description": "会话的功能。" }, "description": "为该会话配置的验证功能列表，显示名称为：`ID_VERIFICATION`、`NFC`、`LIVENESS`、`FACE_MATCH`、`POA`、`PHONE`、`EMAIL_VERIFICATION`、`AML`、`IP_ANALYSIS`、`DATABASE_VALIDATION`、`QUESTIONNAIRE`、`AGE_ESTIMATION`、`FACE_SEARCH`、`GEOLOCATION`（位置验证）（企业验证（KYB）会话使用 KYB 功能集：`KYB_REGISTRY`、`KYB_DOCUMENTS`、`KYB_KEY_PEOPLE`、`AML`、`PHONE`、`EMAIL_VERIFICATION`、`IP_ANALYSIS`、`QUESTIONNAIRE`）。使用 `include=events` 时，每个条目将变为对象 `{feature, node_id}` 而不是纯字符串，并且邮箱功能将被重命名：在事件模式下显示为 `EMAIL`，而不是此处使用的 `EMAIL_VERIFICATION`。" }, "vendor_data": { "type": "string", "description": "会话的供应商数据。", "nullable": true }, "metadata": { "type": "object", "description": "会话的元数据。", "nullable": true }, "expected_details": { "type": "object", "description": "在创建会话时提供的预期详细信息，用于与提取的数据进行交叉比对（KYC）或预填充公司登记搜索（KYB）。原样返回所提供的键；未提供时为 `null`。KYC 会话包含人员字段；企业验证（KYB）会话包含 `company_name`、`registry_country` 和 `registration_number`。", "properties": { "first_name": { "type": "string", "description": "用户的名。例如 `John`。" }, "last_name": { "type": "string", "description": "用户的姓。例如 `Doe`。" }, "date_of_birth": { "type": "string", "format": "date", "description": "用户的出生日期，格式为：YYYY-MM-DD。例如 `1990-05-15`。" }, "gender": { "type": "string", "nullable": true, "enum": [ "M", "F" ], "default": null, "description": "用户的性别。必须为 'M'、'F' 或 null。" }, "nationality": { "type": "string", "description": "代表申请人原籍国家/地区的 ISO 3166-1 alpha-3 国家/地区代码。例如 `USA`。" }, "country": { "type": "string", "description": "代表地址证明文件的国家/地区，或申请人身份证件的国家/地区的 ISO 3166-1 alpha-3 国家/地区代码（可能与国籍不同）。例如 `GBR`。" }, "address": { "type": "string", "description": "人类可读格式的地址，包含尽可能多的详细信息。例如 `123 Main St, San Francisco, CA 94105, USA`。" }, "identification_number": { "type": "string", "description": "用户的证件号码、个人编号或税号。例如 `123456789`。" }, "ip_address": { "type": "string", "format": "ipv4", "description": "会话的预期 IP 地址。如果实际 IP 地址与此值不一致，将记录警告。例如 `192.168.1.100`。" }, "expected_document_types": { "type": "array", "description": "在创建会话时身份证件验证步骤所限定的证件类型。为空/未设置表示无限制。代码：`P`（护照）、`ID`（国民身份证）、`DL`（驾照）、`RP`（居留许可）、`HIC`（健康保险卡）、`TC`（税卡）、`SSC`（社会保障卡）。", "items": { "type": "string", "enum": [ "P", "ID", "DL", "RP", "HIC", "TC", "SSC" ] } }, "id_country": { "type": "string", "nullable": true, "description": "创建时受限的预期身份证件签发国家/地区（ISO 3166-1 alpha-3）。", "example": "ESP" }, "poa_country": { "type": "string", "nullable": true, "description": "创建时受限的预期地址证明文件国家/地区（ISO 3166-1 alpha-3）。", "example": "ESP" }, "company_name": { "type": "string", "description": "企业的预期法定名称。仅适用于企业验证（KYB）会话。" }, "registry_country": { "type": "string", "description": "预期登记国家/地区，格式为 `XX` 或 `XX-YY`（ISO 3166-1 alpha-2，针对州级登记可选附带 ISO 3166-2 细分代码，例如 `US-CA`）。仅适用于企业验证（KYB）会话。" }, "registration_number": { "type": "string", "description": "预期的公司注册号。仅限企业（KYB）会话。" } }, "nullable": true }, "contact_details": { "type": "object", "description": "创建会话时提供的联系方式详情（用于通知邮件、预填的电话/邮箱验证以及沟通语言）。当既未提供邮箱也未提供电话号码时为 `null`。", "properties": { "email": { "type": "string", "description": "用户的邮箱地址（例如 \"john.doe@example.com\"），将在邮箱验证步骤中使用。如果未提供，用户必须在验证流程中自行提供。" }, "email_lang": { "type": "string", "description": "邮件通知的语言代码（ISO 639-1）。控制所有邮件通信的语言（例如 \"en\"、\"es\"、\"fr\"）。" }, "send_notification_emails": { "type": "boolean", "default": false, "description": "若为 true 且提供了邮箱，Didit 会在创建用户验证（KYC）或企业验证（KYB）会话时异步发送初始的“验证您的身份”邮件。对于需要人工审核的会话，Didit 还会向提供的邮箱地址发送验证状态通知。" }, "phone": { "type": "string", "nullable": true, "description": "用户的电话号码（E.164 格式，若有，例如 +14155552671）。如果会话创建时仅提供了邮箱，则为 `null`。注意：此字段返回会话创建时提供的原始电话号码。如果该号码无效，可能不是 E.164 格式。" } }, "nullable": true }, "callback": { "type": "string", "format": "uri", "description": "会话的回调 URL。", "nullable": true }, "id_verifications": { "type": "array", "nullable": true, "description": "**身份证件验证 (OCR) 报告数组**，由工作流图谱中的证件步骤生成。始终为 JSON 数组 — 如果您的工作流可以运行多个证件核查（例如主要核查加上升级核查），请读取 `id_verifications[0]` 并进行遍历。在至少有一个证件步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别 `status`、提取的证件字段、图像 URL、质量评分、MRZ、地址解析、跨会话匹配项以及 `warnings[]`。", "items": { "type": "object", "description": "单个身份证件验证报告：单个身份证件验证步骤的完整报告。`verification_method` 说明生成该报告所使用的三种方式之一（证件采集、非证件查询或钱包登录），并相应填充特定方式的证据块。", "properties": { "node_id": { "type": "string", "description": "生成此报告的 OCR 步骤的工作流图谱节点 ID。" }, "verification_method": { "type": "string", "enum": [ "document", "id_lookup", "wallet" ], "description": "生成此报告的身份证件验证方法。`document` - 用户拍摄了实体证件（默认值，也是在其他方法存在之前创建的每个会话的值）。`id_lookup` - 用户输入其国民身份证号码，并通过该国家/地区的政府登记处或其他权威数据源进行核验（`id_lookup.source` 指明具体数据源）。`wallet` - 用户使用政府或银行数字身份登录。" }, "assurance": { "type": "string", "enum": [ "documentary", "data_match", "cryptographic" ], "description": "基于 `verification_method` 推导出的保证等级：`documentary` 表示已采集并核查证件，`data_match` 表示详情与所查询数据源中的记录相匹配，`cryptographic` 表示属性由身份提供商完成认证并签名。" }, "wallet_provider": { "type": "string", "nullable": true, "description": "当 `verification_method` 为 `wallet` 时的目录钱包 ID（`mitid`、`bankid_se`、`itsme` 等）。否则为 `null`。" }, "fallback_from": { "type": "object", "nullable": true, "description": "非证件方式未能完成证件验证步骤的原因。在查询或钱包登录失败时设置：若该国家/地区的回退开关为 `fallback_to_document`，则记录在用户继续进行的证件验证上（`action` 为 `fallback_to_document`）；若为 `decline`，则记录在已拒绝报告上。其他情况下为 `null`。", "properties": { "method": { "type": "string", "enum": [ "id_lookup", "wallet" ], "description": "失败的方法。" }, "reason": { "type": "string", "description": "导致其终止的结果，例如 `no_match`、`provider_error`、`cancelled`、`timeout`。" }, "action": { "type": "string", "enum": [ "fallback_to_document", "decline" ], "description": "所执行的已配置操作：`fallback_to_document` 或 `decline`。" } } }, "id_lookup": { "type": "object", "nullable": true, "description": "公司登记凭据。仅在 `verification_method` 为 `id_lookup` 时存在；否则为 `null`。", "properties": { "source": { "type": "string", "description": "所查询数据源面向客户的名称，例如 `Department of Home Affairs`（政府登记库）或 `UK credit bureau and financial services records`（非政府登记库）。这是该查询唯一的来源声明；请勿假定为政府来源。" }, "checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "登记机关响应的时间。" }, "attempts": { "type": "integer", "description": "生成此报告的从 1 开始计数的尝试编号。" }, "max_attempts": { "type": "integer", "description": "针对该国家/地区配置的尝试配额（1 到 5，默认为 1）。" }, "outcome": { "type": "string", "enum": [ "match", "partial_match", "no_match", "provider_error", "format_rejected" ], "nullable": true, "description": "登记机构返回的结果。只有 `match`、`partial_match` 和 `no_match` 会计入尝试预算并产生计费。" }, "comparison": { "type": "array", "description": "数据源返回的每个可比对字段对应一行，此外每个数据源错误各对应一行。比对行使用下方的标准化字段名称，而非各国家/地区的请求字段键，因为多个请求字段（名字与姓氏，或任何标识符别名）会合并为单次比对。失败的数据源会附加一行 `field: \"provider\"` 且 `result: \"error\"`，因此在将某行视为字段判定之前，请先查看 `result`。", "items": { "type": "object", "required": [ "field", "label", "provided", "record", "result" ], "properties": { "field": { "type": "string", "enum": [ "identification_number", "full_name", "date_of_birth", "address", "provider" ], "description": "归一化的比对字段。`provider` 不是用户字段：它用于标记数据源错误行。" }, "label": { "type": "string", "description": "行的显示标签，例如 `ID number`、`Full name`、`Provider`。" }, "provided": { "type": "string", "nullable": true, "description": "用户输入的内容。在 `provider` 错误行上为 `null`。" }, "record": { "type": "string", "nullable": true, "description": "数据源包含的内容。在 `provider` 错误行上，此项将替换为错误信息。" }, "result": { "type": "string", "enum": [ "match", "partial", "no_match", "error" ], "description": "逐字段比对结果。`error` 仅出现在 `provider` 行，表示该数据源未响应；请将其视为有关查询本身的信息，绝非字段不匹配。" } } } }, "registry_portrait": { "type": "string", "format": "uri", "nullable": true, "description": "数据源返回肖像图像的短期预签名 URL。仅限返回肖像的四个政府登记机构（南非、尼日利亚、阿根廷、巴拿马）。" }, "face_match_score": { "type": "number", "nullable": true, "description": "自拍照与登记处肖像比对分数，0-100。仅在登记处返回肖像时提供。" } } }, "wallet_verification": { "type": "object", "nullable": true, "description": "凭证证据。仅当 `verification_method` 为 `wallet` 时存在；否则为 `null`。", "properties": { "provider": { "type": "string", "description": "目录钱包 ID，例如 `mitid`。" }, "provider_name": { "type": "string", "nullable": true, "description": "终端用户知晓的钱包名称，例如 `MitID`。" }, "issuing_authority": { "type": "string", "nullable": true, "description": "钱包背后的主管机构，例如 `Danish Agency for Digital Government`。" }, "issuing_country": { "type": "string", "description": "提供该钱包的 ISO 3166-1 alpha-3 国家/地区。" }, "credential_type": { "type": "string", "nullable": true, "description": "钱包出示的凭证，例如 `person_identification`。" }, "level_of_assurance": { "type": "string", "enum": [ "low", "substantial", "high" ], "nullable": true, "description": "钱包声明的保障级别。声明级别低于请求级别的登录会失败，而不是降级。" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "钱包的认证时刻。" }, "signature_valid": { "type": "boolean", "nullable": true, "description": "钱包返回的签名断言是否通过验证。" }, "attributes": { "type": "object", "additionalProperties": true, "description": "钱包共享的属性，按钱包目录条目中所列的键名组织。" }, "portrait": { "type": "string", "format": "uri", "nullable": true, "description": "钱包所共享肖像图像的短期预签名 URL（若钱包有共享）。" }, "face_match_score": { "type": "number", "nullable": true, "description": "自拍照与钱包肖像比对分数，0-100，在钱包共享肖像时提供。" } } }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Expired" ], "description": "此身份证件验证步骤的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。" }, "document_type": { "type": "string", "description": "身份证件类型" }, "document_subtype": { "type": "string", "nullable": true, "description": "工作流证件设置中接受的证件子类型代码，适用时包含证件地区。示例：`ID_CARD_GENERIC`、`QUEENSLAND_DRIVER_LICENSE_GENERIC`。" }, "document_number": { "type": "string", "description": "证件识别号码" }, "personal_number": { "type": "string", "description": "个人身份号码" }, "portrait_image": { "type": "string", "format": "uri", "description": "肖像图像 URL" }, "front_image": { "type": "string", "format": "uri", "description": "证件正面图像 URL" }, "front_video": { "type": "string", "format": "uri", "description": "证件正面视频 URL" }, "back_image": { "type": "string", "format": "uri", "description": "证件背面图像的 URL" }, "back_video": { "type": "string", "format": "uri", "description": "证件背面视频 URL" }, "full_front_image": { "type": "string", "format": "uri", "description": "完整证件正面图像 URL" }, "full_back_image": { "type": "string", "format": "uri", "description": "完整证件背面图像 URL" }, "front_image_camera_front": { "type": "string", "format": "uri", "description": "从前置摄像头捕获的证件正面图像 URL" }, "back_image_camera_front": { "type": "string", "format": "uri", "description": "从前置摄像头捕获的证件背面图像 URL" }, "date_of_birth": { "type": "string", "format": "date", "description": "证件中的出生日期" }, "age": { "type": "integer", "description": "根据出生日期计算出的年龄" }, "expiration_date": { "type": "string", "format": "date", "description": "证件到期日期" }, "date_of_issue": { "type": "string", "format": "date", "description": "证件签发日期" }, "issuing_state": { "type": "string", "description": "签发州的 ISO 代码" }, "issuing_state_name": { "type": "string", "description": "签发州的完整名称" }, "first_name": { "type": "string", "description": "证件中的名" }, "last_name": { "type": "string", "description": "证件上的姓氏" }, "full_name": { "type": "string", "description": "证件中的姓名" }, "gender": { "type": "string", "description": "证件中的性别" }, "address": { "type": "string", "description": "证件中的原始地址" }, "formatted_address": { "type": "string", "description": "格式化的完整地址" }, "place_of_birth": { "type": "string", "description": "证件上的出生地点" }, "marital_status": { "type": "string", "description": "证件中的婚姻状况" }, "nationality": { "type": "string", "description": "ISO 国籍代码" }, "extra_fields": { "type": "object", "description": "证件附加字段。包括证件专有属性（例如 `dl_categories`、`blood_group`、`sponsor`、`employer`、`dl_class_code_b_from`、`dl_class_code_b_to`）。驾照准驾车型有效期日期以 `dl_class_code__from` 和 `dl_class_code__to` 形式返回，准驾车型的限制/信息代码（例如英国驾照的第 12 栏）以 `dl_class_code__notes` 形式返回。当证件包含多种文字系统的姓名、地址或出生地时，此对象还会包含这些字段的其他文字系统版本。工作流设置 `preferred_characters`（`latin` 或 `non_latin`）控制哪个文字系统填充顶层字段（`first_name`、`last_name`、`full_name`、`address`、`place_of_birth`）；相反的文字系统则放入此处，当 `preferred_characters` 为 `latin` 时记为 `first_name_non_latin` / `last_name_non_latin` / `full_name_non_latin` / `middle_name_non_latin` / `address_non_latin` / `place_of_birth_non_latin`，当 `preferred_characters` 为 `non_latin` 时带 `_latin` 后缀。仅当 OCR 实际提取出真实的备选文字系统值时才会出现对应键；若某个字段的备选值与首选字符集处于同一文字系统（例如，以西里尔字母标注的字段其 OCR 提取值返回了拉丁同形字），则会被跳过。当 `preferred_characters` 为 `latin` 但证件仅包含非拉丁文本时，Didit 会对提取的值进行音译，并提供 `first_name_latin` / `last_name_latin` 等作为后备。", "additionalProperties": true, "properties": { "dl_categories": { "type": "array", "items": { "type": "string" } }, "blood_group": { "type": "string", "nullable": true }, "first_name_non_latin": { "type": "string", "description": "当 `preferred_characters=latin` 且证件上存在非拉丁文版本时的非拉丁文字系统名（例如吉尔吉斯斯坦身份证上的 `Айна`）。" }, "last_name_non_latin": { "type": "string", "description": "当 `preferred_characters=latin` 且证件上存在非拉丁字母版本时的非拉丁字母文字系统姓氏。" }, "middle_name_non_latin": { "type": "string", "description": "当 `preferred_characters=latin` 且证件上存在非拉丁字母版本时，采用非拉丁文字系统的中间名 / 父名。" }, "full_name_non_latin": { "type": "string", "description": "非拉丁文字系统的组合姓名。当名和姓均可用时，从各个组成部分重构。" }, "address_non_latin": { "type": "string", "description": "当 `preferred_characters=latin` 且证件上存在非拉丁版本时，非拉丁文字系统的地址。" }, "place_of_birth_non_latin": { "type": "string", "description": "当 `preferred_characters=latin` 且证件上存在非拉丁文版本时，以非拉丁文字系统表示的出生地点。" }, "first_name_latin": { "type": "string", "description": "拉丁文字系统的名。在 `preferred_characters=non_latin` 且证件上存在拉丁文版本时填充；或在 `preferred_characters=latin` 但证件仅包含非拉丁文本时，作为音译回退填充。" }, "last_name_latin": { "type": "string", "description": "拉丁字母文字系统的姓氏。规则同 `first_name_latin`。" }, "middle_name_latin": { "type": "string", "description": "拉丁字母中间名 / 父名。规则同 `first_name_latin`。" }, "full_name_latin": { "type": "string", "description": "拉丁文字系统的组合姓名。当名和姓均可用时，始终从各个组成部分重构。" }, "address_latin": { "type": "string", "description": "拉丁字母系统的地址。规则与 `first_name_latin` 相同。" }, "place_of_birth_latin": { "type": "string", "description": "以拉丁文字系统表示的出生地点。规则与 `first_name_latin` 相同。" } } }, "mrz": { "type": "object", "nullable": true, "description": "从证件中提取的机读区（MRZ）解析字段。若未检测到 MRZ 则为 `null`。", "properties": { "surname": { "type": "string", "example": "MARTINEZ_families` / `very_high_similarity_plus__families`。仅当 `match_source` 为 `recovered_high` 时存在。" } } } }, "browser_version": { "type": "string", "nullable": true }, "os_version": { "type": "string", "nullable": true }, "user_agent": { "type": "string", "nullable": true, "description": "浏览器的用户代理字符串。" }, "accept_language": { "type": "string", "nullable": true, "description": "浏览器发送的 `Accept-Language` 请求头。" }, "session_identifier": { "type": "string", "nullable": true, "description": "运行验证的浏览会话的标识符。" }, "session_age_ms": { "type": "integer", "nullable": true, "description": "运行该步骤时该浏览会话的时长（毫秒）。" }, "coords_accuracy": { "type": "number", "nullable": true, "description": "设备报告的坐标精度半径（以米为单位）。" }, "raw_device_data": { "type": "object", "nullable": true, "additionalProperties": true, "description": "为此步骤收集的原始设备信号。" } } } }, "geolocation_checks": { "type": "array", "nullable": true, "description": "**位置验证结果数组**，每个位置验证步骤对应一项：即该步骤已接受的尝试。在位置验证步骤生成数据之前为 `null`。同一步骤先前的尝试位于 `geolocation_attempts` 中。", "items": { "$ref": "#/components/schemas/GeolocationCheck" } }, "geolocation_attempts": { "type": "array", "nullable": true, "description": "该会话中每个位置验证步骤的每次尝试，按时间正序排列。被重新提交所取代的尝试会被排除在外。如果工作流通过其响应属性隐去了 `geolocation_checks`，则该列表也会被隐去。", "items": { "$ref": "#/components/schemas/GeolocationAttempt" } }, "database_validations": { "type": "array", "nullable": true, "description": "**数据库核验报告数组** — 始终为 JSON 数组，绝非单独的 `database_validation` 对象。在至少有一个数据库核验步骤生成数据之前为 `null`。每一项均为完整报告，包含 `node_id`、功能级别的 `status`、`screened_data`、按服务划分的 `validations[]`（各项均包含其登记机构的 `source_data`）以及 `warnings[]`。`screened_data` 和 `source_data` 字段因国家/地区而异：\n\n**ARG（阿根廷）**：screened_data: {document_number, selfie, gender, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, date_of_death, tax_id, tax_id_type, face_match_score, sit_1_since, banks, last_position, highest_position, rejected_checks}。使用 RENAPER 生物识别人脸比对核验。当证件（例如驾照）中未包含性别时，会通过人脸分析或名字自动推断性别\n\n**BOL（玻利维亚）**：screened_data: {document_number, date_of_birth, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender}\n\n**BRA（巴西）**：screened_data: {tax_number, first_name, last_name, date_of_birth}。对于成功的 CPF 匹配，source_data 始终包含 {identification_number, first_name, last_name, date_of_birth, lgpd_minor, minor_under_18, minor_under_16}。成功的成年人查询会将这些标志设置为 false。Receita Federal Consulta CPF 服务可能会返回 HTTP 422（未满 18 岁未成年人）或 451（未满 16 岁）并附带因 LGPD 而不提供的数据；在这些情况下，source_data 会相应地将未成年人标志设置为 true，包含上游 HTTP 状态，且字段级核验为 no_match。有关完整代码列表，请参阅数据库核验结果代码参考中的巴西部分。\n\n**CHL（智利）**：screened_data: {personal_number, first_name, last_name, date_of_birth}。source_data: {identification_number, first_name, last_name, date_of_birth, gender}\n\n**COL（哥伦比亚）**：screened_data: {document_number, document_type, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, document_type}\n\n**CRI（哥斯达黎加）**：screened_data: {personal_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}\n\n**DOM（多米尼加共和国）**：screened_data: {personal_number}。source_data: {identification_number}（仅返回有效/无效）\n\n**ECU（厄瓜多尔）**：screened_data: {personal_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, street, formatted_address, gender, nationality, education, marital_status, spouse, mother_name, father_name, profession}\n\n**ESP（西班牙）**：screened_data: {personal_number, document_type, expiration_date, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, document_type, expiration_date}\n\n**GTM（危地马拉）**：screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}\n\n**HND（洪都拉斯）**：screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}\n\n**MEX（墨西哥）**：screened_data: {personal_number (CURP), first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, date_of_birth, gender, nationality, curp_status, state_of_birth, doc_probatorio, registration_year, registration_state, registration_municipality, num_acta, crip, issuing_state_code, foreign_registry_number, folio_carta, folio_certificado}。使用 RENAPO 民事登记处。对于 MEX，还提供单独的 INE 有效性检查服务作为额外的逐一核验。\n\n**PAN（巴拿马）**：screened_data: {personal_number, selfie}。source_data: {identification_number}。使用 SIB 生物识别核验\n\n**PER（秘鲁）**：screened_data: {personal_number (DNI), first_name, last_name}。source_data: {identification_number, first_name, last_name, paternal_name, maternal_name, verification_number, verification_letter}\n\n**PRY（巴拉圭）**：screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}\n\n**SLV（萨尔瓦多）**：screened_data: {document_number, date_of_birth, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}\n\n**URY（乌拉圭）**：screened_data: {personal_number, date_of_birth, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name}\n\n**VEN（委内瑞拉）**：screened_data: {document_number, first_name, last_name}。source_data: {identification_number, first_name, last_name, full_name, gender, date_of_birth, document_type}", "items": { "type": "object", "properties": { "node_id": { "type": "string", "description": "工作流图谱中此数据库核验步骤的唯一标识符。" }, "issuing_state": { "type": "string", "description": "已查询其政府/登记机构数据源的国家/地区的 ISO 3166-1 alpha-3 代码（例如 `BRA`、`MEX`、`ESP`、`NGA`、`IDN`）。数据库核验覆盖美洲、欧洲、非洲、中东和亚太地区的 60+ 个国家/地区，以及全球多国数据源；覆盖范围定期扩展，因此请将该值视为开放集合而非固定枚举。" }, "validation_type": { "type": "string", "enum": [ "one_by_one", "two_by_two", "not_enabled" ], "description": "结果的交叉核验方式：`one_by_one`（单一服务结果）、`two_by_two`（两个或更多不同服务独立完全匹配证件号码）或 `not_enabled`（当没有服务产生可用匹配时保留）。该值绝不为 `null`。专用的生物识别 2x2 验证模式目前适用于 `ECU` 和 `PER`。" }, "screened_data": { "type": "object", "description": "用于核验的输入数据。字段因国家/地区而异，请参阅数据库核验文档（`/core-technology/database-validation/overview`）了解特定国家/地区的格式。", "properties": { "last_name": { "type": "string" }, "first_name": { "type": "string" }, "tax_number": { "type": "string", "description": "巴西：CPF（11 位数字）" }, "personal_number": { "type": "string", "description": "智利：RUT，多米尼加共和国：Cédula（11 位数字），厄瓜多尔：Cédula（10 位数字），西班牙：DNI/NIE，墨西哥：CURP（18 个字符），秘鲁：DNI（8 位数字），乌拉圭：CI" }, "document_number": { "type": "string", "description": "ARG: DNI, BOL: CI, COL: Cédula, GTM: DPI, HND: DNI, PAN: Cédula, PRY: CI, SLV: DUI, VEN: Cédula" }, "date_of_birth": { "type": "string", "format": "date" }, "document_type": { "type": "string", "description": "COL: CC/CE/TI/NIT, ESP: ID/PASSPORT" }, "expiration_date": { "type": "string", "format": "date", "description": "ESP 必需" } } }, "validations": { "type": "array", "description": "返回验证 payload 的每个登记服务对应一个条目。每个条目标识该服务（`service_id`、`service_name`），并包含逐字段的 `validation` 比对结果、服务上报时的 `outcome_code` / `outcome_detail`，以及 `source_data` 中的标准化登记记录。", "items": { "type": "object", "properties": { "service_id": { "type": "string", "description": "生成此验证结果的登记处服务的标识符。", "example": "bra_cpf" }, "service_name": { "type": "string", "description": "登记机构服务便于人类阅读的名称。", "example": "Brazil - CPF status check" }, "validation": { "type": "object", "description": "字段验证的结果。", "properties": { "full_name": { "type": "string", "description": "姓名的比对结果（例如，'full_match'、'partial_match'、'no_match'）。" }, "date_of_birth": { "type": "string", "description": "出生日期的比对结果。" }, "identification_number": { "type": "string", "description": "身份证件号码的比对结果。" } } }, "outcome_code": { "type": "string", "nullable": true, "description": "公司登记查询的机器可读结果（例如 `MATCH`、`NO_MATCH`、`PARTIAL_MATCH`、`INCONCLUSIVE`、特定于数据源的代码）。在服务报告此类结果时提供。" }, "outcome_detail": { "type": "string", "nullable": true, "description": "`outcome_code` 的便于人类阅读的说明（由服务提供时）。" }, "source_data": { "type": "object", "description": "从政府数据库返回的数据。通用字段：identification_number、first_name、last_name、full_name、date_of_birth、gender。按国家/地区划分的附加字段：BRA 在 CPF 匹配成功时始终包含 lgpd_minor、minor_under_18 和 minor_under_16；当 CPF 数据根据 LGPD 被扣留时，它还包含上游 HTTP 状态（HTTP 422/451）。ECU 增加 street、formatted_address、nationality、education、marital_status、spouse、mother_name、father_name、profession。PER 增加 paternal_name、maternal_name、verification_number、verification_letter。ESP 增加 document_type、expiration_date。VEN/COL 增加 document_type。", "additionalProperties": true } } } }, "errors": { "type": "array", "description": "核验时登记机构服务返回的错误，每个错误均标记有生成它的 `service_id`。**当没有错误时，该键会被完全省略。**", "items": { "type": "object", "description": "按原样展开的上游服务错误对象（其键名因服务而异，通常包含 message/code 以及任何提供商特有的详细信息），外加标识出错服务的 `service_id`。", "properties": { "service_id": { "type": "string", "nullable": true, "description": "报错的登记处服务的标识符。" } }, "additionalProperties": true } }, "match_type": { "type": "string", "enum": [ "no_match", "partial_match", "full_match" ], "nullable": true, "description": "所查询各服务的综合匹配结果。在核验被评估之前为 `null`。" }, "status": { "type": "string", "description": "此数据库核验的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ] }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACEMATCH", "PROOF_OF_ADDRESS", "PHONE", "EMAIL", "AML", "LOCATION", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "GEOLOCATION", "SIGNATURE" ], "description": "生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。" }, "risk": { "type": "string" }, "additional_data": { "type": "object", "nullable": true }, "log_type": { "type": "string" }, "short_description": { "type": "string" }, "long_description": { "type": "string" }, "node_id": { "type": "string", "description": "生成此警告的工作流图节点 ID" } } }, "description": "与数据库核验相关的警告。" } } } }, "database_validation_not_performed_reason": { "type": "object", "nullable": true, "additionalProperties": true, "description": "已配置的数据库核验未产生结果的原因，格式为 `{code, message}` 加上上下文字段。仅在包含该步骤的工作流中 `database_validations` 为 `null` 时存在，以便您能够区分“登记机构核对一致”与“未运行任何核验”。其他情况下为 `null`。", "properties": { "code": { "type": "string", "description": "稳定的机器可读原因。" }, "message": { "type": "string", "description": "便于人类阅读的说明。" } } }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "user": { "type": "string", "description": "执行审核的人员。通常是控制台审核员的标识符（其邮箱），但对于使用 API 密钥进行的状态更新，该值为 `\"API Client\"`；当无法解析执行者时，该值为 `\"Unknown\"`，因此请勿将此字段解析为邮箱地址。" }, "new_status": { "type": "string" }, "comment": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } } } }, "assignee": { "type": "object", "nullable": true, "description": "会话所分配到的控制台审核员，未分配给任何人时为 `null`。", "properties": { "email": { "type": "string", "format": "email" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true } } }, "waiting_since": { "type": "string", "format": "date-time", "nullable": true, "description": "会话开始等待审核的时间。除非会话为 `In Review` 且您的应用设置了审核截止期限，否则为 `null`。" }, "sla_due_at": { "type": "string", "format": "date-time", "nullable": true, "description": "审核截止时间。除非会话为 `In Review` 且您的应用设置了审核截止期限，否则为 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "会话创建时的时间戳（ISO 8601，UTC）。" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "该会话计划过期的时间戳。在创建时配置了过期时间的用户验证（KYC）会话上设置（或者一旦 `Approved` 状态触发 KYC 过期计算）。对于未配置过期的会话以及不使用过期的类型（例如从未接收到 `expires_at` 的企业验证（KYB）会话）为 `null`。" }, "registry_checks": { "type": "array", "nullable": true, "description": "公司登记核验。仅在 `session_kind = business` 时存在。每一项都封装了完整的公司登记 payload。", "items": { "type": "object", "description": "一次公司登记核验：包含股权结构与警告信息的完整公司登记 payload。仅在 `session_kind = business` 时存在。", "properties": { "status": { "type": "string", "description": "功能生命周期状态。" }, "node_id": { "type": "string", "nullable": true }, "data_resolved": { "type": "boolean" }, "company": { "type": "object", "description": "企业的完整公司登记 payload（公司登记记录与任何用户提供或控制台编辑的数据合并）。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "node_id": { "type": "string", "nullable": true }, "status": { "type": "string" }, "registry_status": { "type": "string", "nullable": true }, "data_resolved": { "type": "boolean" }, "company_name": { "type": "string" }, "registration_number": { "type": "string", "nullable": true }, "country_code": { "type": "string", "description": "注册国家/地区（ISO 3166-1 alpha-2，例如 `GB`、`DE`、`US`）。" }, "region": { "type": "string", "nullable": true, "description": "适用的 ISO 3166-2 行政区划代码（例如美国各州的 `CA`、`NY`）。" }, "company_type": { "type": "string", "nullable": true }, "incorporation_date": { "type": "string", "format": "date", "nullable": true }, "registered_address": { "type": "string", "nullable": true }, "tax_number": { "type": "string", "nullable": true }, "risk_level": { "type": "string", "enum": [ "LOW", "MEDIUM", "HIGH" ], "nullable": true }, "verification_status": { "type": "string", "nullable": true }, "is_from_registry": { "type": "boolean" }, "fetch_status": { "type": "string", "nullable": true }, "alternative_names": { "type": "string", "nullable": true, "description": "上报时的替代名称、商业名称、曾用名或原始语言公司名称（文本格式）。" }, "nature_of_business": { "type": "string", "nullable": true }, "registered_capital": { "type": "string", "nullable": true }, "registered_capital_amount": { "type": "string", "format": "decimal", "nullable": true, "description": "从公司登记备案中解析出的注册资本/股本金额，表示为十进制字符串（例如 `\"100.00\"`）。不可用时为 `null`。" }, "registered_capital_currency": { "type": "string", "nullable": true, "description": "`registered_capital_amount` 的 ISO 4217 货币代码（例如 `\"GBP\"`）。不可用时为 `null`。" }, "website": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "phone": { "type": "string", "nullable": true }, "legal_entity_identifier": { "type": "string", "nullable": true }, "location_of_registration": { "type": "string", "nullable": true }, "vat_number": { "type": "string", "nullable": true, "description": "欧盟增值税号（EU VAT number），在托管登记步骤中收集或随后编辑时提供。" }, "vat_validation_status": { "type": "string", "enum": [ "valid", "invalid", "format_valid", "invalid_format", "could_not_validate", "not_applicable" ], "description": "在登记提交时验证增值税号（若无，则为 `tax_number`）的结果。`valid` / `invalid`：由相应国家/地区的官方登记处判定（欧盟 VIES、挪威、瑞士、巴西、哥伦比亚、哥斯达黎加、厄瓜多尔、巴拉圭；波兰还由其国内增值税登记册判定）。`format_valid` / `invalid_format`：在无法查询登记处时，由该国家/地区的格式和校验位规则判定。`could_not_validate`：登记处不可用。`not_applicable`：无号码、无登记处或规则的国家/地区，或者沙盒会话。" }, "vat_validated_number": { "type": "string", "nullable": true, "description": "已核验的号码，格式以数据源所知为准（例如从法国 SIREN 或荷兰 RSIN 派生的增值税号）。若未运行核验，则为 `null`。" }, "vat_validation_source": { "type": "string", "nullable": true, "enum": [ "eu_vies", "pl_vat_white_list", "no_brreg", "ch_uid_register", "br_receita_federal", "co_rues", "cr_hacienda", "ec_sri", "py_dnit", "format_rules", null ], "description": "判定 `vat_validation_status` 的来源：官方登记，或 `format_rules`。未运行任何检查时为 `null`。" }, "vat_validated_name": { "type": "string", "nullable": true, "description": "向验证该号码的数据源登记的名称（如果该数据源公开名称）。仅当状态为 `valid` 时设置。" }, "vat_validated_address": { "type": "string", "nullable": true, "description": "核验该号码的数据源中登记的地址（若该数据源披露）。仅在状态为 `valid` 时设置。" }, "vat_checked_at": { "type": "string", "format": "date-time", "nullable": true, "description": "检查的时间戳。未运行检查时为 `null`。" }, "financial_summary": { "type": "object", "nullable": true }, "officers": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "designation": { "type": "string", "nullable": true }, "role": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "enum": [ "Approved", "Declined", "Pending" ], "nullable": true }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true }, "first_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的名字；并非从全名中推断。" }, "last_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的姓氏。" }, "address": { "type": "string", "nullable": true, "description": "登记处报告的官员地址。" }, "appointment_date": { "type": "string", "nullable": true, "description": "管理人员被任命的日期。", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "任期结束的日期（若有报告）。", "format": "date" }, "date_of_birth": { "type": "string", "nullable": true, "description": "公司登记报告的完整出生日期。如果仅已知出生年份或月份，则为 null。", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "公司登记所报告的出生年份，包括完整日期不可用的情况。" }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "公司登记所报告的出生月份。仅知晓年份时为 null。" } } } }, "beneficial_owners": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "roles": { "type": "array", "items": { "type": "string" } }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "公司登记报告的股权百分比下限。自由格式字符串（例如 `\"25.00\"`、`\"50\"`）；使用 `effective_ownership_percent` 获取解析后的数值。" }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "公司登记报告的持股比例上限。自由格式字符串；解析后的数值请使用 `effective_ownership_percent`。" }, "is_active": { "type": "boolean" }, "kyc_status": { "type": "string", "enum": [ "Approved", "Declined", "Pending" ], "nullable": true }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true }, "effective_ownership_percent": { "type": "number", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "完整的出生日期（如有报告）。", "format": "date" }, "appointment_date": { "type": "string", "nullable": true, "description": "有报告时的委任日期。", "format": "date" }, "shareholding": { "$ref": "#/components/schemas/KYBRegistryShareholding" } } } }, "addresses": { "type": "array", "nullable": true, "description": "登记处注明的每个地址，采用标准规范格式。如果未注明，则为 null。", "items": { "$ref": "#/components/schemas/KYBRegistryAddress" } }, "industries": { "type": "array", "nullable": true, "description": "登记机构对企业进行分类的业务活动，采用一种规范化格式。若未注明则为 null。", "items": { "$ref": "#/components/schemas/KYBRegistryIndustry" } }, "accounts": { "type": "object", "nullable": true, "additionalProperties": true, "description": "公司登记备案日期（如可用）。年度申报表和大会使用 last_annual_return_date 与 last_agm_date；它们与财务账目不同。" }, "registry_data": { "$ref": "#/components/schemas/KYBRegistryData" }, "user_provided_data": { "type": "object", "description": "由终端用户确认或编辑的数据。" }, "confirmed_by_user_at": { "type": "string", "format": "date-time", "nullable": true }, "last_console_edit_at": { "type": "string", "format": "date-time", "nullable": true }, "is_editable": { "type": "boolean" }, "ownership": { "$ref": "#/components/schemas/KYBRegistryOwnership" }, "registry_tier": { "type": "string", "nullable": true, "description": "工作流订购的公司登记等级：`basic`、`shareholders` 或 `ubo`。也可在 `ownership.tier_requested` 中查看。" }, "registry_tier_delivered": { "type": "string", "nullable": true, "description": "登记机构交付且计费的等级。亦包含在 `ownership.tier_delivered` 中。" }, "registry_ownership_status": { "type": "string", "nullable": true, "description": "`not_requested`、`pending`、`delivered`、`not_held` 或 `unavailable`。同样适用于 `ownership.status`。" }, "registry_monitoring": { "type": "object", "nullable": true, "description": "该企业的最新登记监控，不存在时为 `null`。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "unavailable_reason": { "type": "string", "nullable": true }, "enrolled_at": { "type": "string", "format": "date-time", "nullable": true }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true }, "last_bill_date": { "type": "string", "format": "date", "nullable": true }, "next_bill_date": { "type": "string", "format": "date", "nullable": true }, "last_event_at": { "type": "string", "format": "date-time", "nullable": true }, "events_count": { "type": "integer" }, "watched_fields": { "description": "监控器监视的企业字段。" } } } } }, "ownership_structure": { "$ref": "#/components/schemas/KYBOwnershipStructure" }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "key_people_checks": { "type": "array", "nullable": true, "description": "汇总的关键人员核验。仅在 `session_kind = business` 时存在。每个条目均使用双分组格式（`registry`、`submitted`、`ubo_kyc_summary`）。", "items": { "type": "object", "description": "对公司高级管理人员 + 实际受益人的综合核验。使用 `registry` / `submitted` 格式。仅在 session_kind = business 时提供。", "properties": { "status": { "type": "string" }, "node_id": { "type": "string", "nullable": true }, "registry": { "type": "object", "description": "通过登记处核验发现的当事方。", "properties": { "officers": { "type": "array", "description": "通过公司登记核验发现的官员，每位官员均附带有为其生成的子 KYC 会话和 AML 筛查的状态。", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "登记处记录的官员姓名。" }, "designation": { "type": "string", "nullable": true, "description": "来自登记机构的自由文本职务（例如 `Director`、`Company Secretary`）。" }, "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "归一化的职员角色。" }, "nationality": { "type": "string", "nullable": true }, "appointment_date": { "type": "string", "nullable": true, "description": "管理人员被任命的日期。", "format": "date" }, "termination_date": { "type": "string", "nullable": true, "description": "任期结束的日期（若有报告）。", "format": "date" }, "is_active": { "type": "boolean" }, "address": { "type": "string", "nullable": true, "description": "登记处报告的官员地址。" }, "aml_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "nullable": true, "description": "为此负责人运行的 AML 筛查状态。未运行 AML 筛查时为 `null`。" }, "kyc_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "为此管理人员生成的子 KYC 会话的原始生命周期状态。这是完整的会话状态枚举（并非缩减的 Approved/Declined/Pending 集合）。如果不存在子 KYC 会话，则为 `null`。" }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "子 KYC 会话的可共享 URL。不存在子会话时为 `null`。" }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "子 KYC 会话的会话 id。将其传递给同一个决策 endpoint 以获取该人员的完整 KYC 报告。如果不存在子会话，则为 `null`。" }, "verification_workflow_type": { "type": "string", "nullable": true, "description": "子会话工作流的基础工作流类型（例如 `kyc`）。对于基于图谱的工作流或不存在子会话时为 `null`。" }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "子会话使用的工作流 ID。不存在子会话时为 `null`。" }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "子会话工作流便于人类阅读的标签。未设置时为 `null`。" }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "子验证会话按功能划分的进度，例如 `[{\"feature\": \"ID_VERIFICATION\", \"status\": \"Approved\"}]`。当子会话没有可解析的功能列表时为 `null`。", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "功能显示名称（例如 `ID_VERIFICATION`、`LIVENESS`、`AML`）。" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "子会话内的功能级状态。" } } } }, "didit_internal_id": { "type": "string", "nullable": true, "description": "子会话背后已验证个人的稳定内部标识符 — 用于跨会话关联。当子会话不存在或用户尚未解析时为 `null`。" }, "kyc_document_type": { "type": "string", "nullable": true, "description": "子 KYC 会话中出示的证件类型（例如 `P`、`ID`、`DL`）。在子会话获得身份证件验证结果之前为 `null`。" }, "kyc_nationality": { "type": "string", "nullable": true, "description": "从子 KYC 会话中的证件提取的国籍。在可用前为 `null`。" }, "kyc_liveness_passed": { "type": "boolean", "nullable": true, "description": "子 KYC 会话的活体检测是否通过。未运行活体检测时为 `null`。" }, "kyc_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "子 KYC 会话达到 `Approved` 的时间。当子会话处于任何其他状态时为 `null`。" }, "kyc_aml_categories": { "type": "object", "nullable": true, "description": "根据个人的 AML 命中情况按类别汇总的摘要。无命中时为 `null`。", "properties": { "sanctions": { "type": "string", "enum": [ "match", "clear" ] }, "pep": { "type": "string", "enum": [ "match", "clear" ] }, "adverse_media": { "type": "string", "enum": [ "match", "clear" ] }, "warnings": { "type": "string", "enum": [ "match", "clear" ] } } }, "kyc_notification_sent_at": { "type": "string", "nullable": true, "description": "为该人员的子会话发送上一条验证邀请通知的 ISO 8601 时间戳。未发送时为 `null`。" }, "first_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的名字；并非从全名中推断。" }, "last_name": { "type": "string", "nullable": true, "description": "公司登记明确报告时的姓氏。" }, "date_of_birth": { "type": "string", "nullable": true, "description": "公司登记报告的完整出生日期。如果仅已知出生年份或月份，则为 null。", "format": "date" }, "date_of_birth_year": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 9999, "description": "公司登记所报告的出生年份，包括完整日期不可用的情况。" }, "date_of_birth_month": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 12, "description": "公司登记所报告的出生月份。仅知晓年份时为 null。" } } } }, "beneficial_owners": { "type": "array", "description": "通过登记处核查发现的实际受益人，每个受益人均补充了为其生成的任何子 KYC 会话和 AML 筛查的状态。", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string", "description": "实际受益人姓名（如果是企业 UBO 则为公司名称）。" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "nullable": true, "description": "完整的出生日期（如有报告）。", "format": "date" }, "country_of_birth": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "nationality": { "type": "string", "nullable": true }, "designation": { "type": "string", "nullable": true }, "roles": { "type": "array", "description": "该所有者持有的角色名称，例如 `[\"ubo\", \"shareholder\"]`。", "items": { "type": "string" } }, "ownership_min_shares": { "type": "string", "nullable": true, "description": "公司登记报告的股权百分比下限。自由格式字符串（例如 `\"25\"`、`\"25-50%\"`）；使用 `effective_ownership_percent` 获取解析后的数值。" }, "ownership_max_shares": { "type": "string", "nullable": true, "description": "公司登记报告的持股比例上限。自由格式字符串；解析后的数值请使用 `effective_ownership_percent`。" }, "is_active": { "type": "boolean" }, "aml_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "nullable": true, "description": "为此实际受益人运行的 AML 筛查状态。未运行 AML 筛查时为 `null`。" }, "kyc_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "为此实际受益人生成的子 KYC 会话的原始生命周期状态。这是完整的会话状态枚举（并非缩减的 Approved/Declined/Pending 集合）。如果不存在子 KYC 会话，则为 `null`。" }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "子 KYC 会话的可共享 URL。不存在子会话时为 `null`。" }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "子 KYC 会话的会话 id。将其传递给同一个决策 endpoint 以获取该人员的完整 KYC 报告。如果不存在子会话，则为 `null`。" }, "verification_workflow_type": { "type": "string", "nullable": true, "description": "子会话工作流的基础工作流类型（例如 `kyc`）。对于基于图谱的工作流或不存在子会话时为 `null`。" }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "子会话使用的工作流 ID。不存在子会话时为 `null`。" }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "子会话工作流便于人类阅读的标签。未设置时为 `null`。" }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "子验证会话按功能划分的进度，例如 `[{\"feature\": \"ID_VERIFICATION\", \"status\": \"Approved\"}]`。当子会话没有可解析的功能列表时为 `null`。", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "功能显示名称（例如 `ID_VERIFICATION`、`LIVENESS`、`AML`）。" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "子会话内的功能级状态。" } } } }, "didit_internal_id": { "type": "string", "nullable": true, "description": "子会话背后已验证个人的稳定内部标识符 — 用于跨会话关联。当子会话不存在或用户尚未解析时为 `null`。" }, "kyc_document_type": { "type": "string", "nullable": true, "description": "子 KYC 会话中出示的证件类型（例如 `P`、`ID`、`DL`）。在子会话获得身份证件验证结果之前为 `null`。" }, "kyc_nationality": { "type": "string", "nullable": true, "description": "从子 KYC 会话中的证件提取的国籍。在可用前为 `null`。" }, "kyc_liveness_passed": { "type": "boolean", "nullable": true, "description": "子 KYC 会话的活体检测是否通过。未运行活体检测时为 `null`。" }, "kyc_verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "子 KYC 会话达到 `Approved` 的时间。当子会话处于任何其他状态时为 `null`。" }, "kyc_aml_categories": { "type": "object", "nullable": true, "description": "根据个人的 AML 命中情况按类别汇总的摘要。无命中时为 `null`。", "properties": { "sanctions": { "type": "string", "enum": [ "match", "clear" ] }, "pep": { "type": "string", "enum": [ "match", "clear" ] }, "adverse_media": { "type": "string", "enum": [ "match", "clear" ] }, "warnings": { "type": "string", "enum": [ "match", "clear" ] } } }, "kyc_notification_sent_at": { "type": "string", "nullable": true, "description": "为该人员的子会话发送上一条验证邀请通知的 ISO 8601 时间戳。未发送时为 `null`。" }, "child_beneficial_owners": { "type": "array", "description": "对于企业 UBO：拥有实体自身的实际受益人，表示为从登记机构提取的原始对象。不适用时为空数组。", "items": { "type": "object" } }, "effective_ownership_percent": { "type": "number", "nullable": true, "description": "解析出的数值型股权百分比：可用时为上限值，否则为下限值。当两个边界都无法解析时为 `null`。" }, "voting_min_shares": { "type": "string", "nullable": true }, "voting_max_shares": { "type": "string", "nullable": true }, "appointment_date": { "type": "string", "nullable": true, "description": "有报告时的委任日期。", "format": "date" } } } } } }, "submitted": { "type": "object", "description": "企业管理员在关键人员流程中提交的当事方（source=USER 的 BusinessParty 行）。", "properties": { "parties": { "type": "array", "items": { "type": "object", "description": "企业管理员通过关键人员流程提交的当事方（source=USER）。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "entity_type": { "type": "string", "enum": [ "person", "company" ] }, "source": { "type": "string", "enum": [ "USER" ], "description": "此处始终为 `USER` — 此存储桶仅包含终端用户在关键人员流程中输入或确认的主体（从公司登记中发现的人员显示在 `registry` 下）。" }, "name": { "type": "string" }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "registration_number": { "type": "string", "nullable": true }, "email": { "type": "string", "format": "email", "nullable": true }, "nationality": { "type": "string", "nullable": true, "description": "个人为国籍；企业主体为注册成立国家/地区。" }, "phone_number": { "type": "string", "nullable": true }, "date_of_birth": { "type": "string", "format": "date", "nullable": true }, "position": { "type": "string", "nullable": true, "description": "自由文本职位/头衔（仅限个人）。" }, "custom_fields": { "type": "object", "description": "为此方收集的工作流定义自定义字段；键由工作流的关键人员字段描述符定义。" }, "is_active": { "type": "boolean" }, "is_skipped": { "type": "boolean", "description": "当终端用户跳过了对此当事方的验证时为 true（仅当角色允许跳过时才可能）。" }, "requires_verification": { "type": "boolean", "description": "根据角色设置和股权结构阈值，需要为此当事方创建子 KYC / KYB 子会话时为 true。" }, "roles": { "type": "array", "description": "该主体担任的所有角色，每个角色均有其自身的股权结构百分比和投票权百分比。主体本身没有标量 `role`/`ownership_percent`。", "items": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ] }, "ownership_percent": { "type": "number", "nullable": true }, "voting_percent": { "type": "number", "nullable": true } } } }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "需要验证的个人当事方的子 KYC 会话 ID。否则为 `null`。" }, "kyc_session_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "子 KYC 会话的生命周期状态。不存在子 KYC 会话时为 `null`。" }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true }, "kyb_sub_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "需要验证的企业当事方的子 KYB 子会话 ID。否则为 `null`。" }, "kyb_sub_session_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "nullable": true, "description": "KYB 子会话的生命周期状态。不存在子会话时为 `null`。" }, "kyb_sub_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "子 KYB 子会话的可共享 URL。不存在子会话时为 `null`。" }, "verification_workflow_type": { "type": "string", "nullable": true, "description": "子会话工作流的基础工作流类型（优先取 KYC 会话，回退到 KYB 子会话）。对于基于图谱的工作流或不存在子会话时为 `null`。" }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "子会话使用的工作流 ID。不存在子会话时为 `null`。" }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "子会话工作流便于人类阅读的标签。未设置时为 `null`。" }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "子验证会话按功能划分的进度，例如 `[{\"feature\": \"ID_VERIFICATION\", \"status\": \"Approved\"}]`。当子会话没有可解析的功能列表时为 `null`。", "items": { "type": "object", "properties": { "feature": { "type": "string", "description": "功能显示名称（例如 `ID_VERIFICATION`、`LIVENESS`、`AML`）。" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "子会话内的功能级状态。" } } } }, "didit_internal_id": { "type": "string", "nullable": true, "description": "子会话背后已验证个人的稳定内部标识符。未解析时为 `null`。" } } } } } }, "ubo_kyc_summary": { "type": "object", "nullable": true, "description": "汇总的实际受益人 KYC 进度；当没有实际受益人关联 KYC 会话时为 null。", "properties": { "total": { "type": "integer" }, "approved": { "type": "integer" }, "flagged": { "type": "integer", "description": "KYC 状态为已拒绝或审核中的实际受益人。" }, "pending": { "type": "integer" } } }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "document_verifications": { "type": "array", "nullable": true, "description": "按工作流节点分组的证件验证检查。仅在 `session_kind = business` 时提供。", "items": { "type": "object", "description": "按工作流节点分组的证件。仅在 session_kind = business 时提供。", "properties": { "status": { "type": "string" }, "node_id": { "type": "string", "nullable": true }, "items": { "type": "array", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "document_type": { "type": "string", "enum": [ "LEGAL_PRESENCE", "COMPANY_DETAILS", "OWNERSHIP_STRUCTURE", "REPRESENTATIVES_AUTHORIZATION", "OTHER" ], "nullable": true, "description": "该文件被分类归入的高级 KYB 证件组。未分类时为 `null`。" }, "document_subtype": { "type": "string", "nullable": true, "description": "OCR 检测出的特定子类型（例如 `CERTIFICATE_OF_INCORPORATION`、`SHAREHOLDER_REGISTRY`）；当 OCR 无法高置信度分类证件时为 `UNKNOWN`。" }, "document_group": { "type": "string", "enum": [ "LEGAL_PRESENCE", "COMPANY_DETAILS", "OWNERSHIP_STRUCTURE", "REPRESENTATIVES_AUTHORIZATION", "OTHER" ], "nullable": true, "description": "`document_type` 的别名：`groups` 和 `required_groups` 使用的分组名称。" }, "file_url": { "type": "string", "format": "uri", "nullable": true, "description": "已上传文件的短期预签名链接。对于分析师创建且尚未完成的证件请求占位符（`is_requested = true`），此值为 `null`。" }, "original_filename": { "type": "string", "nullable": true, "description": "用户或分析师上传时的文件名。" }, "file_size": { "type": "integer", "nullable": true, "description": "文件大小（字节）。" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "按证件划分的验证状态。" }, "created_at": { "type": "string", "format": "date-time" }, "cross_check_result": { "type": "object", "nullable": true, "description": "OCR 提取的证件字段与公司登记企业档案的交叉比对。一个包含 `critical`、`non_critical` 和 `people` 部分的对象，各部分将字段名称（例如 `company_name`、`registration_number`、`incorporation_date`、`registered_address`）映射到形如 `{\"document\": \"...\", \"registry\": \"...\", \"match\": true, \"score\": 0.97}` 的比对记录。当证件没有 OCR 数据或没有可比对的公司登记企业时为 `null`。" }, "document_metadata": { "type": "object", "nullable": true, "description": "从上传的企业证件中提取的元数据。当元数据提取成功时，所有 16 个键均始终存在（对该文件类型不适用的个别值设为 `null`）；当无法提取任何内容时，整个对象为 `null`。对于 PDF，`overlay_manipulation` 包含图层覆盖文本的取证分析。", "properties": { "file_size": { "type": "integer", "nullable": true, "description": "证件大小。" }, "content_type": { "type": "string", "nullable": true, "description": "证件的内容类型。" }, "creation_date": { "type": "string", "nullable": true, "description": "证件创建的日期。" }, "modified_date": { "type": "string", "nullable": true, "description": "证件修改的日期。" }, "creator": { "type": "string", "nullable": true, "description": "文件元数据中记录的编写工具/用户（PDF `Creator`）。" }, "producer": { "type": "string", "nullable": true, "description": "生成文件的软件（PDF `Producer`）。" }, "software": { "type": "string", "nullable": true, "description": "文件元数据中记录的编辑软件。" }, "encryption": { "type": "string", "nullable": true, "description": "文件加密时的加密方案。" }, "is_signed": { "type": "boolean", "nullable": true, "description": "证件是否带有数字签名。" }, "is_tampered": { "type": "boolean", "nullable": true, "description": "数字签名是否验证失败（签名后被篡改）。" }, "signature_info": { "type": "object", "nullable": true, "description": "数字签名的详细信息（若存在）。" }, "exif_original_date": { "type": "string", "nullable": true, "description": "EXIF 原始拍摄日期，适用于图片上传。" }, "exif_digitized_date": { "type": "string", "nullable": true, "description": "EXIF 数字化日期，适用于图片上传。" }, "processed_by_known_editor": { "type": "boolean", "nullable": true, "description": "元数据是否表明该文件曾经过已知的图像/PDF 编辑器处理。" }, "has_different_creation_mod_date": { "type": "boolean", "nullable": true, "description": "创建日期与修改日期是否存在差异，这是一种可能的（但非决定性的）编辑信号。" }, "overlay_manipulation": { "type": "object", "nullable": true, "description": "针对疑似覆盖文本篡改的 PDF 取证分析。当未发现覆盖篡改证据或证件不是 PDF 时为 Null。", "properties": { "detected": { "type": "boolean", "description": "是否检测到覆盖文本篡改的迹象。" }, "analyzed": { "type": "boolean", "description": "PDF 是否可以被分析。" }, "analysis_incomplete": { "type": "boolean", "description": "仅当文件无法被完整检查时才存在且值为 true。已检查的部分在可能的情况下保留其检查结果，文档会发出未经验证的文本替换警告。" }, "signals": { "type": "array", "items": { "type": "string" }, "description": "触发的取证信号，例如 duplicate_font_subset 或 glyph_fragmentation。" }, "manipulated_regions": { "type": "array", "description": "PDF 页面坐标系中疑似被篡改的区域。", "items": { "type": "object", "properties": { "page": { "type": "integer" }, "x": { "type": "number" }, "y": { "type": "number" }, "width": { "type": "number" }, "height": { "type": "number" }, "page_width": { "type": "number" }, "page_height": { "type": "number" } } } } } } } }, "description": { "type": "string", "nullable": true, "description": "分析师提供的证件请求标签或原因。常规上传为 `null`。" }, "is_requested": { "type": "boolean", "description": "如果为分析师创建且等待上传的证件请求占位项，则为 true。" }, "ocr_data": { "type": "object", "nullable": true }, "is_console_upload": { "type": "boolean", "description": "如果是从控制台而非终端用户流程上传的证件，则为 true。控制台上传绝不会更改功能级别的汇总状态。" }, "is_confirmed": { "type": "boolean", "description": "Console 上传初始为 `false`，管理员确认后转为 `true`；终端用户上传始终为 `true`。" } } } }, "groups": { "type": "object", "description": "按组划分的进度计数器，以组名称为键（例如 legal_presence、ownership_structure）。", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "approved": { "type": "integer" }, "pending": { "type": "integer" }, "declined": { "type": "integer" }, "in_review": { "type": "integer" }, "other": { "type": "integer" }, "missing": { "type": "integer", "description": "已请求但尚未上传文件的占位符。" } } } }, "required_groups": { "type": "array", "items": { "type": "string" } }, "warnings": { "type": "array", "items": { "type": "object" } } } } }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "会话是由生产环境应用（`live`）还是沙盒应用（`sandbox`）创建。沙盒会话是免费且完全模拟的，绝不会扣除额度。" }, "sandbox_scenario": { "type": "string", "nullable": true, "description": "创建会话时使用的沙盒场景。对于生产环境会话以及创建时未指定场景的沙盒会话，该值为 `null`。" }, "resubmissions": { "type": "array", "description": "仅在携带 `include=resubmissions` 时返回，适用于用户和企业会话。每次重新提交请求对应一个条目，按最早优先排序。每个条目都包含重新提交步骤在请求之前返回的结果，因此早期的提交内容仍可读取。删除会话将删除所有提交记录。", "items": { "type": "object", "properties": { "number": { "type": "integer", "description": "会话第一次重新提交为 1，第二次为 2，以此类推。" }, "created_at": { "type": "string", "format": "date-time", "description": "请求重新提交的时间。" }, "previous_status": { "type": "string", "description": "紧接请求发起前的会话状态。" }, "nodes": { "type": "array", "description": "返回给用户的工作流步骤。", "items": { "type": "object", "properties": { "node_id": { "type": "string" }, "feature": { "type": "string" } } } }, "reasons": { "type": "object", "nullable": true, "additionalProperties": { "type": "string" }, "description": "各步骤给出的原因，以 `node_id` 为键。" }, "requested_by": { "type": "object", "nullable": true, "description": "请求重新提交的人员。", "properties": { "name": { "type": "string" }, "email": { "type": "string" }, "type": { "type": "string" } } }, "results": { "type": "object", "additionalProperties": true, "description": "重新提交的步骤在请求前返回的内容，其键名和结构与此响应的当前结果相同（`id_verifications`、`nfc_verifications`、`liveness_checks`、`face_matches`、`poa_verifications`、`phone_verifications`、`email_verifications`、`aml_screenings`、`ip_analyses`、`database_validations`、`questionnaire_responses`、`document_ai_documents`、`geolocation_checks`；企业会话还包括 `document_verifications`）。仅显示被回传步骤的键名。" } } } }, "biometric_consent": { "type": "object", "nullable": true, "description": "会话在进行人脸采集前是否要求明确的生物识别同意、原因以及答复凭据。仅适用于用户验证（KYC）会话；该对象同样包含在会话 Webhook 的 `decision` 中。若会话从未经过评估（例如不含人脸采集的工作流），则为 `null`。未记录值的字段为 `null`。低于 4.10.0 的原生 SDK，或未上报版本的原生 SDK，无法显示同意步骤：其人脸采集将照常运行，而需要同意的会话随后将报告 `status: \"pending\"` 及 `reason: \"BIOMETRIC_CONSENT_UNSUPPORTED_SDK\"`。请参阅 [生物识别同意](/zh/getting-started/biometric-consent)。", "properties": { "required": { "type": "boolean", "description": "Whether the session must collect explicit biometric consent. Never goes back to `false`." }, "trigger": { "type": "string", "nullable": true, "enum": [ "declared_state", "ip_state", "ip_unknown", "document_issuer", "forced", "customer_collected" ], "description": "需要同意的原因，或其满足方式。`declared_state`：您声明了适用的州（`user_state`，或 `expected_details` 中的美国地址）。`ip_state`：该用户的 IP 位于适用的州（伊利诺伊州、得克萨斯州、科罗拉多州）。`ip_unknown`：证据表明该用户位于美国，但无法确定具体的州（IP 位于美国但没有具体州信息，或者无法定位且您的详细信息或证件表明该用户位于美国）。`document_issuer`：身份证件由适用的州签发。`forced`：应用的模式为 Always。`customer_collected`：您在创建会话时发送了 `biometric_consent`。非必需时为 `null`。" }, "status": { "type": "string", "enum": [ "not_required", "pending", "given", "declined" ], "description": "`not_required`；`pending`（必填但未提供：该人员尚未回答，或 `reason` 说明了未收集的原因）；`given`；`declined`（已记录拒绝，会话以 `Declined` 结束；目前 Didit 页面不提供拒绝选项）。" }, "given_at": { "type": "string", "format": "date-time", "nullable": true, "description": "给予同意的时间。对于 `customer_collected`，为您发送的 `given_at`。" }, "declined_at": { "type": "string", "format": "date-time", "nullable": true, "description": "记录拒绝的时间。" }, "text_version": { "type": "string", "nullable": true, "description": "该人员答复的同意文本版本 ID，或您发送的版本 ID。" }, "text_hash": { "type": "string", "nullable": true, "description": "所展示的确切同意文本（以所展示的语言）的 SHA-256（十六进制）。" }, "locale": { "type": "string", "nullable": true, "description": "同意声明文本显示的语言。" }, "policy_url": { "type": "string", "format": "uri", "nullable": true, "description": "同意步骤所链接的生物识别数据策略。" }, "step": { "type": "string", "nullable": true, "description": "当事人回答时会话所在的工作流步骤，例如 `LIVENESS`。" }, "node_id": { "type": "string", "nullable": true, "description": "当事人回答时会话所在的工作流图谱节点。" }, "ip_address": { "type": "string", "nullable": true, "description": "答案来源的 IP。" }, "ip_country_code": { "type": "string", "nullable": true, "description": "答案的 IP 所在国家/地区的 ISO 3166-1 alpha-2 代码。" }, "ip_state": { "type": "string", "nullable": true, "description": "答案所在 IP 的 ISO 3166-2 行政区划，例如 `US-IL`。" }, "ip_city": { "type": "string", "nullable": true, "description": "答案所用 IP 所在的城市。" }, "user_agent": { "type": "string", "nullable": true, "description": "提交回答请求的 User-Agent。" }, "detected_ip_address": { "type": "string", "nullable": true, "description": "上次评估该要求时该人员所用的 IP。如果该人员在其他设备上进行了作答，可能与 `ip_address` 不同。" }, "detected_country_code": { "type": "string", "nullable": true, "description": "检测到的 IP 所在国家/地区的 ISO 3166-1 alpha-2 代码。" }, "detected_state": { "type": "string", "nullable": true, "description": "检测到的 IP 对应的 ISO 3166-2 行政区划。" }, "detected_city": { "type": "string", "nullable": true, "description": "检测到的 IP 所在的城市。" }, "declared_state": { "type": "string", "nullable": true, "description": "您声明的 ISO 3166-2 行政区划：`user_state`，或 `expected_details` 中美国地址的州。" }, "document_state": { "type": "string", "nullable": true, "description": "签发身份证件的 ISO 3166-2 行政区划，于证件采集时读取。" }, "jurisdictions": { "type": "array", "items": { "type": "string" }, "description": "其生物识别法律涵盖该人员的美国各州（USPS 代码，例如 `IL`）。当证据表明该人员位于美国但州未知时为 `US`。不适用时为空。" }, "retention_months": { "type": "integer", "nullable": true, "description": "`jurisdictions` 中最短的生物特征保留限制（以月为单位）。当均不适用时为 `null`。" }, "reason": { "type": "string", "nullable": true, "enum": [ "BIOMETRIC_CONSENT_UNSUPPORTED_SDK", "BIOMETRIC_CONSENT_DECLINED" ], "description": "`BIOMETRIC_CONSENT_UNSUPPORTED_SDK`：需要同意，但低于 4.10.0 版本的原生 SDK 或未上报版本的 SDK 在没有同意步骤的情况下捕获了人脸；`status` 保持为 `pending`，如果用户稍后在托管流程中同意则变为 `given`。`BIOMETRIC_CONSENT_DECLINED`：记录了拒绝（这会替换 SDK 原因）。其他情况下为 `null`，且当会话不需要同意时始终为 `null`。" }, "decline_reason": { "type": "string", "nullable": true, "enum": [ "BIOMETRIC_CONSENT_DECLINED" ], "description": "当记录的拒绝导致会话终止时为 `BIOMETRIC_CONSENT_DECLINED`，否则为 `null`。" }, "face_data_deleted_at": { "type": "string", "format": "date-time", "nullable": true, "description": "拒绝操作删除该会话的人脸图像、视频和人脸模板的时间。除非记录了拒绝，否则为 `null`。" } } }, "investigator": { "$ref": "#/components/schemas/InvestigatorBlock" }, "biometric_retention": { "$ref": "#/components/schemas/BiometricRetention" }, "fraud_check": { "type": "object", "nullable": true, "additionalProperties": true, "description": "Fraud Check API 调用的结果。对于所有其他会话均为 `null`。" }, "full_session_video": { "type": "string", "format": "uri", "nullable": true, "description": "完整会话录屏的会过期 URL。仅当您的组织录制完整会话视频时返回。" }, "full_session_video_recorded_at": { "type": "string", "format": "date-time", "nullable": true, "description": "录制完整会话的时间。仅在您的组织录制完整会话视频时返回。" } } }, "WorkflowDetail": { "type": "object", "description": "以下字段均为类型化字段；该对象还包含工作流配置的每个其他列（功能开关、阈值、警告操作、允许的证件、回调）作为附加属性。不适用于该 `workflow_type` 的字段为 `null`。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "每个版本对应的标识符（`settings_uuid`）。工作流的每个版本都有其独有的标识符。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "工作流所有版本共享的稳定标识符。使用它创建的会话将采用最新发布的版本。" }, "workflow_label": { "type": "string", "description": "工作流的显示名称。" }, "workflow_type": { "type": "string", "nullable": true, "enum": [ "kyc", "kyb", "adaptive_age_verification", "biometric_authentication", "address_verification", "questionnaire_verification", "email_verification", "phone_verification", null ], "description": "工作流模板。对于未使用模板创建的图谱工作流为 `null`。" }, "is_default": { "type": "boolean", "description": "这是否为该应用的默认工作流。" }, "is_archived": { "type": "boolean", "description": "已归档的工作流无法启动新会话。" }, "version": { "type": "integer", "description": "工作流内的版本号。" }, "status": { "type": "string", "enum": [ "draft", "published" ], "description": "草稿版本可编辑；已发布版本不可更改，并用于新会话。" }, "published_at": { "type": "string", "format": "date-time", "nullable": true, "description": "此版本发布的时间。草稿为 `null`。" }, "is_simple_workflow": { "type": "boolean", "description": "当工作流没有自定义 `workflow_graph` 时为 `true`。" }, "is_editable": { "type": "boolean", "description": "仅对 `draft` 版本为 `true`。" }, "workflow_url": { "type": "string", "format": "uri", "description": "启动此工作流会话的公开 URL。" }, "workflow_graph": { "type": "object", "nullable": true, "additionalProperties": true, "description": "工作流的图谱结构（节点和边）。简单工作流为 `null`。" }, "features": { "type": "string", "description": "用 `\" + \"` 连接的已启用功能，例如 `\"OCR + LIVENESS\"`。" }, "total_price": { "type": "number", "nullable": true, "description": "每次会话的价格；对于图谱工作流，为最昂贵路径的价格。" }, "min_price": { "type": "number", "nullable": true, "description": "工作流中最便宜路径的价格。" }, "max_price": { "type": "number", "nullable": true, "description": "工作流中最昂贵路径的价格。" }, "special_add_on_prices": { "type": "object", "nullable": true, "additionalProperties": true, "description": "特定于组织的附加项价格，未设置时为 `null`。" }, "max_retry_attempts": { "type": "integer", "description": "验证被拒绝后允许的重试次数。" }, "retry_window_days": { "type": "integer", "nullable": true, "description": "允许重试的天数。" }, "session_expiration_time": { "type": "integer", "description": "未完成会话过期前的秒数。" }, "questionnaire": { "type": "object", "nullable": true, "additionalProperties": true, "description": "附加到工作流的问卷，或为 `null`。" }, "kyb_role_settings": { "type": "array", "items": { "type": "object", "additionalProperties": true }, "description": "针对 KYB 关键人员的按角色验证设置。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "signature_availability": { "type": "object", "description": "当前哪些电子签名等级可以签署。在设置 `signature_level` 之前请检查此项。在 `kyc`、`kyb` 和图谱工作流中返回。", "properties": { "simple": { "type": "boolean", "description": "Simple 始终可用。" }, "aes": { "type": "boolean", "description": "高级电子签名（AES）当前是否可以签署。当其为 `false` 时，若保存带有 `signature_level: \"aes\"` 的新步骤，将因 `aes_not_available` 而被拒绝。" }, "qes": { "type": "boolean", "description": "合格电子签名（QES）当前是否可以签署。在连接合格提供商之前，该值为 `false`。" } } }, "is_bank_verification_enabled": { "type": "boolean", "description": "简易 KYC 或 KYB 工作流是否运行银行验证。它在联系方式步骤（以及位置验证）之后、数据库核验、AML 及 IP 分析之前运行。银行验证目前尚未正式公开发布：在未启用的情况下开启将被拒绝。" }, "bank_verification_config": { "type": "object", "additionalProperties": true, "description": "简单工作流的银行验证设置，包含与 `BANK_VERIFICATION` 节点相同的键（例如 `bank_countries` 和 `bank_method_order`）。未知键将被丢弃。每个键均为可选，缺少的键保持其默认值，因此 `{}` 表示全部使用默认值。参见[银行验证设置](/zh/management-api/workflows/feature-configs#银行验证)。", "example": {} }, "is_geolocation_enabled": { "type": "boolean", "description": "简易 KYC 工作流是否运行位置验证。它在联系方式步骤之后、银行验证和数据库核验之前运行。企业（KYB）工作流无法运行该验证。" }, "geolocation_config": { "type": "object", "additionalProperties": true, "description": "简易工作流的位置验证设置，具有与 `GEOLOCATION` 节点相同的键（例如 `is_geolocation_geofencing_enabled` 和 `geolocation_max_attempts`）。未知的键将被丢弃。每个键都是可选的，缺少的键保持其默认值，因此 `{}` 表示全部使用默认值。", "example": {} } }, "additionalProperties": true }, "UserSessionListItem": { "title": "KYC session row (session_kind: user)", "type": "object", "description": "用户验证（KYC）会话的摘要行。身份字段（`full_name`、`country`、`document_type`、`portrait_image`、联系人字段）随着用户完成验证步骤逐步填充，在相关步骤完成之前为 `null`。受工作流响应属性配置限制的字段也返回为 `null`。", "required": [ "session_id", "session_kind", "session_number", "session_url", "portrait_image", "document_type", "full_name", "country", "status", "vendor_data", "didit_internal_id", "created_at", "features", "phone_number", "email_address", "additional_details" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "验证会话的唯一标识符。与 `GET /v3/session/{sessionId}/decision/` 一起使用以获取完整的决策 payload。", "example": "5b3720ed-d429-42ef-b67f-37ea805f48ee" }, "session_kind": { "type": "string", "enum": [ "user" ], "description": "行区分符。对于 KYC 行始终为 `\"user\"`；企业验证（KYB）行的值为 `\"business\"` 且具有不同的结构。", "example": "user" }, "session_number": { "type": "integer", "description": "您应用内该会话便于人类阅读的序号。也可通过 `search` 参数进行匹配。", "example": 720 }, "session_url": { "type": "string", "nullable": true, "description": "终端用户打开以完成流程的托管验证 URL。当会话没有托管 URL 时为 `null`。", "example": "https://verify.didit.me/session/CuXoBYCYVO5Y" }, "portrait_image": { "type": "string", "nullable": true, "description": "最佳可用肖像照的会过期的（预签名）URL：如可用则为 NFC 芯片照片，否则为身份证件肖像照，再否则为活体检测参考图像。在其中任一项存在之前为 `null`。请及时下载；链接会过期。", "example": "https:///portraits/5b3720ed.jpg?X-Amz-Expires=3600&X-Amz-Signature=..." }, "document_type": { "type": "string", "nullable": true, "enum": [ "Passport", "Identity Card", "Driver's License", "Residence Permit", "Health Insurance Card", "Tax Card" ], "description": "易于阅读的已验证身份证件类型。证件验证完成前为 `null`，且当验证后的代码没有显示映射（`SSC`、`WP`、`VISA`、`PSC`、`BC`、`OTHER`）时，完成后也为 `null`。注意：`document_type` 查询参数通过短代码（`P`、`ID`、`DL`、`RP`、...）进行过滤，而非这些显示值。", "example": "Passport" }, "full_name": { "type": "string", "nullable": true, "description": "会话可用的最佳姓名，按以下顺序解析：身份证件 OCR、AML 筛查数据、数据库核验筛查数据、地址证明文件，然后是创建会话时提供的预期详情。尚无可用的数据时为 `null`。", "example": "Jane Marie Doe" }, "country": { "type": "string", "nullable": true, "description": "与会话关联的 ISO 3166-1 alpha-3 国家/地区代码，按以下顺序解析：身份证件签发国/地区、数据库核验签发国/地区、地址证明签发国/地区、预期详情，然后是已验证电话的国家/地区。可能与国籍不同。", "example": "ESP" }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "总体会话状态。生命周期请参阅[验证状态](/zh/integration/verification-statuses)页面。", "example": "Approved" }, "vendor_data": { "type": "string", "nullable": true, "description": "您为终端用户指定的自身标识符，将完全按照创建会话时发送的内容原样返回。", "example": "your-user-id-123" }, "didit_internal_id": { "type": "string", "format": "uuid", "nullable": true, "description": "此会话背后已验证用户个人资料的 Didit 内部标识符。同一用户的多个会话之间保持稳定；可通过 `didit_internal_id` 查询参数进行过滤。", "example": "d9e78474-6c8d-4f2a-bb90-6f5c2f3a1147" }, "created_at": { "type": "string", "format": "date-time", "description": "创建会话时的 UTC 时间戳。", "example": "2026-06-09T12:26:54.328364Z" }, "features": { "type": "array", "description": "会话工作流中配置的每个验证步骤的功能状态，按工作流顺序排列。", "items": { "type": "object", "required": [ "feature", "status" ], "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACE_MATCH", "POA", "QUESTIONNAIRE", "EMAIL_VERIFICATION", "PHONE", "AML", "IP_ANALYSIS", "AGE_ESTIMATION", "DATABASE_VALIDATION", "GEOLOCATION" ], "description": "验证功能标识符。", "example": "ID_VERIFICATION" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "此功能的状态。在步骤完成前为 `Not Finished`。", "example": "Approved" } } } }, "phone_number": { "type": "object", "nullable": true, "description": "与会话关联的电话号码：如果执行了电话验证，则为验证后的电话号码，否则为会话创建时提供的联系电话。如果两者均不存在，则为 `null`。", "required": [ "number", "is_verified" ], "properties": { "number": { "type": "string", "description": "E.164 格式的电话号码。", "example": "+14155552671" }, "is_verified": { "type": "boolean", "description": "仅当电话验证功能通过此号码时为 `true`。", "example": true } } }, "email_address": { "type": "object", "nullable": true, "description": "与会话关联的邮箱：执行过邮箱验证时为已验证的邮箱，否则为创建会话时提供的联系邮箱。两者均不存在时为 `null`。", "required": [ "email", "is_verified" ], "properties": { "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "is_verified": { "type": "boolean", "description": "仅当邮箱验证功能通过此地址时为 `true`。", "example": true } } }, "additional_details": { "type": "object", "nullable": true, "description": "紧凑的各功能附加信息。仅产生数据的功能会作为键显示；若无功能产生附加信息则为 `null`。被工作流响应属性配置排除的字段将被省略。", "properties": { "aml": { "type": "object", "description": "在运行 AML 筛查时存在。", "properties": { "total_hits": { "type": "integer", "description": "AML 筛查命中项数量。", "example": 0 }, "entity_type": { "type": "string", "description": "受筛查实体类型。", "example": "person" }, "is_adverse_media_fetched": { "type": "boolean", "example": false }, "screened_data": { "type": "object", "description": "已筛查数据的子集。仅包含非空键。", "properties": { "nationality": { "type": "string", "example": "ESP" }, "document_number": { "type": "string", "example": "XX1234567" }, "date_of_birth": { "type": "string", "example": "1990-05-21" } } } } }, "database_validation": { "type": "object", "description": "在运行数据库核验时存在。", "properties": { "validation_type": { "type": "string", "example": "DOCUMENT_VALIDATION" }, "match_type": { "type": "string", "example": "FULL_MATCH" }, "identification_number": { "type": "string", "description": "已核验的税号、个人识别号或证件号码（首个可用值）。", "example": "12345678Z" } } }, "poa": { "type": "object", "description": "在运行地址证明时存在。", "properties": { "document_type": { "type": "string", "example": "UTILITY_BILL" }, "issuer": { "type": "string", "example": "Energy Co" }, "address": { "type": "string", "example": "Calle Mayor 1, 28013 Madrid" }, "name_on_document": { "type": "string", "example": "Jane Marie Doe" } } }, "liveness": { "type": "object", "description": "在运行活体检测时存在。", "properties": { "method": { "type": "string", "example": "PASSIVE" }, "score": { "type": "number", "description": "活体置信度分数，保留两位小数。", "example": 0.98 } } }, "face_match": { "type": "object", "description": "在运行人脸比对时存在。", "properties": { "score": { "type": "number", "description": "人脸比对相似度分数，四舍五入保留 2 位小数。", "example": 0.95 }, "source_image": { "type": "string", "description": "源人脸图像的会过期的（预签名）URL。", "example": "https:///faces/source.jpg?X-Amz-Expires=3600&..." }, "target_image": { "type": "string", "description": "目标人脸图像的会过期的（预签名）URL。", "example": "https:///faces/target.jpg?X-Amz-Expires=3600&..." } } }, "phone_verification": { "type": "object", "description": "在运行电话验证时存在。", "properties": { "country_code": { "type": "string", "description": "电话号码所在国家/地区的 ISO 3166-1 alpha-2 代码。", "example": "US" }, "is_temporary": { "type": "boolean", "example": false }, "is_ported": { "type": "boolean", "example": false }, "is_blocked": { "type": "boolean", "example": false } } }, "email_verification": { "type": "object", "description": "在运行邮箱验证时存在。", "properties": { "is_breached": { "type": "boolean", "example": false }, "is_disposable": { "type": "boolean", "example": false }, "is_undeliverable": { "type": "boolean", "example": false }, "is_blocklisted": { "type": "boolean", "example": false } } } } }, "assignee": { "type": "object", "nullable": true, "description": "会话所分配到的控制台审核员，未分配给任何人时为 `null`。", "properties": { "email": { "type": "string", "format": "email" }, "assigned_at": { "type": "string", "format": "date-time", "nullable": true } } }, "waiting_since": { "type": "string", "format": "date-time", "nullable": true, "description": "会话开始等待审核的时间。除非会话为 `In Review`，否则为 `null`。" }, "sla_due_at": { "type": "string", "format": "date-time", "nullable": true, "description": "审核截止时间，依据在控制台中为您的应用设置的审核截止期限。除非会话为 `In Review` 且设置了截止期限，否则为 `null`。" }, "top_warnings": { "type": "array", "description": "会话中最重要的最多几条警告，用于快速初筛视图。完整列表见决策。", "items": { "type": "object", "properties": { "risk": { "type": "string", "description": "警告代码，例如 `FACE_MATCH_LOW_SIMILARITY`。" }, "feature": { "type": "string", "description": "触发该项的功能。" }, "log_type": { "type": "string", "nullable": true, "description": "`error` 或 `warning`；遗留条目为 `null`。" }, "short_description": { "type": "string" } } } }, "warnings_count": { "type": "integer", "description": "会话中的警告数量。" } } }, "BusinessSessionListItem": { "title": "KYB session row (session_kind: business)", "type": "object", "description": "企业验证（KYB）会话的摘要行。仅在 `session_kind` 为 `business` 或 `all` 时返回。", "required": [ "session_id", "session_kind", "session_number", "status", "vendor_data", "created_at", "workflow_id", "workflow_type", "workflow_label", "company_name", "registration_number", "country" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "企业验证会话的唯一标识符。", "example": "8a1f63c2-1b9e-4f3a-9c41-2f6a1f0b7d52" }, "session_kind": { "type": "string", "enum": [ "business" ], "description": "行区分符。对于 KYB 行始终为 `\"business\"`。", "example": "business" }, "session_number": { "type": "integer", "description": "您应用内该企业会话便于人类阅读的序号。独立于 KYC 会话进行编号。", "example": 42 }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "总体会话状态。请参阅[验证状态](/zh/integration/verification-statuses)页面。", "example": "Approved" }, "vendor_data": { "type": "string", "nullable": true, "description": "您为企业指定的自身标识符，将完全按照创建会话时发送的内容原样返回。", "example": "your-company-id-77" }, "created_at": { "type": "string", "format": "date-time", "description": "创建会话时的 UTC 时间戳。", "example": "2026-06-08T09:14:02.118450Z" }, "workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "创建此会话所使用工作流的标识符。", "example": "9f9b1234-aaaa-bbbb-cccc-1234567890ab" }, "workflow_type": { "type": "string", "nullable": true, "description": "工作流类型。企业工作流为 `kyb`。", "example": "kyb" }, "workflow_label": { "type": "string", "nullable": true, "description": "工作流的显示名称。", "example": "Standard KYB" }, "company_name": { "type": "string", "nullable": true, "description": "正在验证的企业名称，来源于与该会话关联的登记机构企业。在选择企业之前为 `null`。", "example": "Acme Holdings S.L." }, "registration_number": { "type": "string", "nullable": true, "description": "与会话关联的登记公司的企业注册号。", "example": "B12345678" }, "country": { "type": "string", "nullable": true, "description": "与会话关联的登记公司的国家/地区代码。", "example": "ES" } } }, "TransactionVerificationSessionAction": { "title": "Verification session", "type": "object", "properties": { "type": { "type": "string", "enum": [ "verification_session" ] }, "url": { "type": "string", "format": "uri", "description": "供终端用户打开的托管验证 URL。" }, "session_id": { "type": "string", "format": "uuid", "description": "验证会话 ID。" }, "session_token": { "type": "string", "description": "会话 token，移动端 SDK 用于原生启动流程。" }, "status": { "type": "string", "description": "验证会话状态。" } }, "required": [ "type", "url" ] }, "TransactionWalletOwnershipAction": { "title": "Wallet ownership", "type": "object", "properties": { "type": { "type": "string", "enum": [ "wallet_ownership" ] }, "url": { "type": "string", "format": "uri", "description": "托管钱包所有权微件 URL。请在真实浏览器环境中打开：在移动端请使用 SFSafariViewController 或 Chrome Custom Tab，切勿使用嵌入式 webview。" }, "widget_session_id": { "type": "string", "format": "uuid", "description": "钱包所有权小部件会话 ID。" }, "expires_at": { "type": "string", "format": "date-time", "description": "小组件会话过期的时间。" } }, "required": [ "type", "url" ] }, "TransactionRuleActionAddScore": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "add_score" ] }, "value": { "type": "integer", "description": "添加到交易风险评分中的点数。可能为负数。" } }, "description": "为交易的累计风险评分增加分值；总分将通过应用的审核/拒绝阈值决定状态。" }, "TransactionRuleActionChangeStatus": { "type": "object", "required": [ "type", "value" ], "properties": { "type": { "type": "string", "enum": [ "change_status" ] }, "value": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "无论评分如何均立即设置的状态。别名键：status。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "当值为 AWAITING_USER 时为必填项：要求主体完成的验证工作流。别名键：remediation_workflow_id。规则触发时，Didit 会为主体创建一个托管的整改会话。" } }, "description": "直接设置交易状态。在所有匹配的规则中，DECLINED 始终优先。" }, "TransactionRuleActionAddTags": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "add_tags" ] }, "tag_uuid": { "type": "string", "format": "uuid", "description": "要附加的现有应用标签。" }, "tag_name": { "type": "string", "description": "要附加的标签名称；首次使用时创建（以大写形式存储）。请提供 tag_uuid 或 tag_name。" }, "tag_color": { "type": "string", "description": "当 tag_name 创建新标签时使用的十六进制颜色，例如 #007AFE。" } }, "description": "将应用标签关联至匹配的交易。" }, "TransactionRuleActionAddNote": { "type": "object", "required": [ "type", "note" ], "properties": { "type": { "type": "string", "enum": [ "add_note" ] }, "note": { "type": "string", "description": "附加到交易的备注文本（作者：Rule Engine）。别名键：值。" } }, "description": "将自动化分析师备注关联至匹配的交易。" }, "TransactionRuleActionAddToList": { "type": "object", "required": [ "type", "list_id" ], "properties": { "type": { "type": "string", "enum": [ "add_to_list" ] }, "list_id": { "type": "string", "format": "uuid", "description": "用于添加主体 vendor_data 的列表。" } }, "description": "将主体的 vendor_data 添加到黑名单、白名单或自定义名单中。" }, "TransactionRuleActionOpenCase": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "open_case" ] }, "blueprint": { "type": "string", "format": "uuid", "description": "案件蓝图 UUID；默认使用应用的默认蓝图。" }, "grouping": { "type": "string", "enum": [ "by_applicant", "by_rule_and_applicant" ], "description": "重复匹配是归入按申请人划分的单个案件，还是按规则+申请人划分的单个案件。" }, "attach_matched_transaction": { "type": "boolean", "description": "将匹配的交易关联至该案件。" } }, "description": "打开（或添加至）调查案件。对于每条规则，仅应用第一个 open_case 操作。" }, "KYBRegistrySearchResults": { "type": "object", "properties": { "companies": { "type": "array", "items": { "type": "object", "properties": { "kyb_response_id": { "type": "string", "nullable": true, "description": "该候选对象的句柄。将其传递给 `POST /v3/kyb/select/` 以检索完整档案。该句柄为临时性质且仅对本次搜索有效：请勿长期存储；重新搜索可获取新句柄。", "example": "69aeeb95febb0f1704042259" }, "name": { "type": "string", "nullable": true, "description": "注册公司名称。", "example": "Tesco PLC" }, "registration_number": { "type": "string", "nullable": true, "description": "公司登记注册号。", "example": "00445790" }, "status": { "type": "string", "nullable": true, "description": "归一化的企业登记状态（例如 `active`、`dissolved`、`inactive`、`struck off`）。", "example": "active" }, "type": { "type": "string", "nullable": true, "description": "公司登记机构报告的法律形式。", "example": "Public Limited Company" }, "registered_address": { "type": "string", "nullable": true, "description": "候选公司的注册地址（当登记机构返回该地址时）。可结合注册号使用该地址来区分同名公司：在美国，候选公司可能列在其实际运营所在的州，而非您搜索的州。", "example": "Tesco House, Shire Park, Kestrel Way, Welwyn Garden City, AL7 1GA" }, "risk_level": { "type": "string", "nullable": true, "description": "公司登记所报告的风险等级（如可用）。搜索时通常为 `null`。" }, "fetch_status": { "type": "string", "nullable": true, "description": "对于搜索候选对象始终为 `pending` — 仅当您选择该候选对象时，才会获取完整的公司资料（并进行计费）。", "example": "pending" } } }, "description": "去重后的候选人列表。当 `search_resolved=false`（Webhook 模式）或未匹配到任何内容时为空。" }, "pagination": { "type": "object", "properties": { "total": { "type": "integer", "description": "返回的候选人数量。" }, "page": { "type": "integer" }, "per_page": { "type": "integer", "example": 25 } } }, "search_status": { "type": "string", "nullable": true, "enum": [ "pending", "resolved" ], "description": "公司登记搜索生命周期状态。" }, "search_resolved": { "type": "boolean", "description": "候选名单最终确定后为 `true`。" } } }, "KYBRegistryCandidateRequest": { "type": "object", "required": [ "kyb_response_id" ], "properties": { "kyb_response_id": { "type": "string", "maxLength": 1024, "description": "来自 `POST /v3/kyb/search/` 的候选句柄（`kyb_registry.companies[].kyb_response_id`）。临时有效：在生成它的搜索之后不久使用。句柄可能很长，因此请严格按返回的原样存储和发送该值，不要修剪或假定其长度。", "example": "69aeeb95febb0f1704042259" }, "vendor_data": { "type": "string", "description": "您为此企业指定的标识符；将原样返回并与企业会话一起存储。" }, "metadata": { "type": "object", "nullable": true, "description": "随企业会话一同存储并回显的自由格式 JSON。" }, "save_api_request": { "type": "boolean", "default": true, "description": "必须为 `true`（默认值）。KYB 公司登记查询始终会持久化保存，以便跟踪计费和检索；传 `false` 将返回 `400`。" } } }, "WebhookEventEnvelope": { "type": "object", "description": "无论事件类型为何，Didit 都会添加到每个已签名的 Webhook 投递中的字段。读取 `webhook_type` 即可了解您收到了哪个 payload。", "required": [ "event_id", "webhook_type", "timestamp", "created_at", "application_id", "environment" ], "properties": { "event_id": { "type": "string", "format": "uuid", "description": "事件的标识符。每个目标都会收到相同的值，且重新投递时保持不变，因此可用于去重。" }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "timestamp": { "type": "integer", "description": "本次投递签名的 Unix 时间（以秒为单位）。等于 `X-Timestamp` 请求头；重新投递会携带新值。" }, "created_at": { "type": "integer", "description": "产生事件的变更所对应的 Unix 时间（以秒为单位）。" }, "application_id": { "type": "string", "format": "uuid", "description": "该事件所属的应用。" }, "environment": { "type": "string", "enum": [ "live", "sandbox" ], "description": "沙盒会话和沙盒应用对应 `sandbox`，否则为 `live`。" } } }, "SessionWebhookEventData": { "type": "object", "description": "`status.updated` 和 `data.updated` 的会话字段。可选字段在不适用时会被省略，绝不会作为 `null` 发送。企业（KYB）会话会添加 `business_session_id`、`session_kind` 和 `vendor_business_id`。", "required": [ "session_id", "status", "sandbox_scenario" ], "properties": { "session_id": { "type": "string", "format": "uuid", "description": "验证会话。" }, "business_session_id": { "type": "string", "format": "uuid", "description": "仅限企业验证（KYB）会话：与 `session_id` 相同的值。" }, "session_kind": { "type": "string", "enum": [ "business" ], "description": "仅适用于企业验证（KYB）会话。用户验证（KYC）会话事件不包含顶层 `session_kind`；请改读 `decision.session_kind`。" }, "status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "变更后的会话状态。" }, "trigger": { "type": "string", "description": "在事件非验证流本身产生时存在，例如 `manual_review`、`manual_step_update`、`ongoing_monitoring`、`webhook_reconciliation`（由于首个最终 Webhook 未能成功创建而重新发送的 `status.updated`，因此您可能会收到已获取决策的重复事件：请根据 `session_id` 和 `status` 进行去重）、`manual_webhook_recovery`、`kyb_registry_change`、`biometric_retention`（在会话的活体生物识别数据按计划删除时发送的 `data.updated`）或 `console_*` 编辑，如 `console_registry_edit`、`console_key_people_skip` 或 `console_key_people_regenerate`。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "该会话的工作流。当会话没有工作流时省略。" }, "workflow_version": { "type": "integer", "description": "会话运行的工作流版本。与 `workflow_id` 一同发送。" }, "vendor_data": { "type": "string", "description": "您针对该会话的 `vendor_data`。为空时省略。" }, "vendor_business_id": { "type": "string", "description": "仅限企业验证（KYB）会话：该会话所属的企业。无企业时省略。" }, "metadata": { "type": "object", "additionalProperties": true, "description": "您的会话 `metadata`。为空时省略。" }, "decision": { "$ref": "#/components/schemas/SessionDecision" }, "resubmit_info": { "type": "object", "description": "仅当 `status` 为 `Resubmitted` 时提供：用户必须重新执行的步骤及原因。", "required": [ "nodes_to_resubmit", "reasons" ], "properties": { "nodes_to_resubmit": { "type": "array", "items": { "type": "object", "required": [ "node_id", "feature" ], "properties": { "node_id": { "type": "string", "description": "在会话的工作流定义中显示的节点标识符（例如 `feature_ocr`、`feature_liveness`）。", "example": "feature_poa" }, "feature": { "type": "string", "description": "节点的功能类型，例如 `OCR`、`LIVENESS` 或 `PROOF_OF_ADDRESS`。", "example": "PROOF_OF_ADDRESS" } } }, "description": "用户必须重做的工作流步骤。与[更新状态](#patch-/v3/session/-sessionId-/update-status/)中的 `nodes_to_resubmit` 相同的 `{node_id, feature}` 条目。" }, "reasons": { "type": "object", "additionalProperties": true, "description": "`nodes_to_resubmit` 中每个 `node_id` 对应的原因。" } } }, "sandbox_scenario": { "type": "string", "nullable": true, "description": "在沙盒会话上预设的模拟结果，或 `null`。生产环境会话始终为 `null`。" } } }, "SessionStatusUpdatedEvent": { "description": "验证会话状态发生变更。`decision` 仅在状态为 `Approved`、`Declined`、`In Review` 和 `Abandoned` 时发送；对于使用 Webhook 版本 3（默认）的目标，其结构与 `GET /v3/session/{sessionId}/decision/` 相同；对于版本 1 或版本 2 的目标，则采用较早的精简结构。企业会话始终接收版本 3 的企业决策。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "$ref": "#/components/schemas/SessionWebhookEventData" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "status.updated" ], "description": "始终为 `status.updated`。" } }, "required": [ "webhook_type" ] } ] }, "SessionDataUpdatedEvent": { "description": "验证会话的数据在状态未发生变化的情况下发生变更，例如在人工审核编辑、步骤覆盖或持续监控重新筛查之后。`decision` 仅针对 `Approved`、`Declined`、`In Review` 和 `Abandoned` 发送；对于 Webhook 版本 3（默认）的目标，其格式与 `GET /v3/session/{sessionId}/decision/` 相同，对于版本 1 或版本 2 的目标，则采用较早的精简格式。企业会话始终接收版本 3 的企业决策。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "$ref": "#/components/schemas/SessionWebhookEventData" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "data.updated" ], "description": "始终为 `data.updated`。" } }, "required": [ "webhook_type" ] } ] }, "UserStatusUpdatedEvent": { "description": "用户状态发生变更。创建用户时不会发送。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "user.status.updated" ], "description": "始终为 `user.status.updated`。" }, "vendor_user_id": { "type": "string", "format": "uuid", "description": "事件所涉及的用户。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您针对用户的 `vendor_data`，或为 `null`。" }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "变更后的用户状态。" }, "previous_status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "变更前的状态。" } }, "required": [ "webhook_type", "vendor_user_id", "vendor_data", "status", "previous_status" ] } ] }, "UserDataUpdatedEvent": { "description": "用户的字段已更改。创建用户时不会发送。一次保存可能同时产生状态事件和数据事件。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "user.data.updated" ], "description": "始终为 `user.data.updated`。" }, "vendor_user_id": { "type": "string", "format": "uuid", "description": "事件所涉及的用户。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您针对用户的 `vendor_data`，或为 `null`。" }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "变更后的用户状态。" }, "changed_fields": { "type": "array", "items": { "type": "string", "enum": [ "vendor_data", "display_name", "full_name", "date_of_birth", "metadata", "portrait_image", "issuing_states", "approved_emails", "approved_phones", "features", "session_count", "approved_count", "declined_count", "in_review_count", "first_session_at", "last_session_at" ] }, "description": "发生更改的字段名称。" }, "changes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "previous": { "nullable": true, "description": "变更前的值。日期为 ISO 8601 格式的字符串。" }, "current": { "nullable": true, "description": "变更后的值。日期为 ISO 8601 格式的字符串。" } } }, "description": "每个已更改字段的先前值和当前值，以字段名称为键。值可能包含个人数据（姓名、出生日期、肖像链接、邮箱、电话号码）；请妥善处理。" } }, "required": [ "webhook_type", "vendor_user_id", "vendor_data", "status", "changed_fields", "changes" ] } ] }, "BusinessStatusUpdatedEvent": { "description": "企业状态发生变更。创建企业时不会发送。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "business.status.updated" ], "description": "始终为 `business.status.updated`。" }, "vendor_business_id": { "type": "string", "format": "uuid", "description": "事件所涉及的企业。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您针对企业的 `vendor_data`，或为 `null`。" }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "变更后的企业状态。" }, "previous_status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "变更前的状态。" } }, "required": [ "webhook_type", "vendor_business_id", "vendor_data", "status", "previous_status" ] } ] }, "BusinessDataUpdatedEvent": { "description": "企业的字段已更改。创建企业时不会发送。一次保存可能同时产生状态事件和数据事件。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "business.data.updated" ], "description": "始终为 `business.data.updated`。" }, "vendor_business_id": { "type": "string", "format": "uuid", "description": "事件所涉及的企业。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您针对企业的 `vendor_data`，或为 `null`。" }, "status": { "type": "string", "enum": [ "ACTIVE", "IN_REVIEW", "FLAGGED", "BLOCKED" ], "description": "变更后的企业状态。" }, "changed_fields": { "type": "array", "items": { "type": "string", "enum": [ "vendor_data", "display_name", "metadata", "legal_name", "registration_number", "country_code", "session_count", "approved_count", "declined_count", "in_review_count", "features", "first_session_at", "last_session_at" ] }, "description": "发生更改的字段名称。" }, "changes": { "type": "object", "additionalProperties": { "type": "object", "properties": { "previous": { "nullable": true, "description": "变更前的值。日期为 ISO 8601 格式的字符串。" }, "current": { "nullable": true, "description": "变更后的值。日期为 ISO 8601 格式的字符串。" } } }, "description": "每个已更改字段的先前值和当前值，以字段名称为键。" } }, "required": [ "webhook_type", "vendor_business_id", "vendor_data", "status", "changed_fields", "changes" ] } ] }, "TransactionCreatedEvent": { "description": "交易已创建并完成筛查。仅针对生产环境应用发送。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "transaction.created" ], "description": "始终为 `transaction.created`。" }, "transaction_id": { "type": "string", "format": "uuid", "description": "Didit 的交易标识符。" }, "txn_id": { "type": "string", "nullable": true, "description": "您在创建时提供的 `transaction_id`，或为 `null`。" }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "变更后的监控状态。" }, "score": { "type": "integer", "description": "规则累计的风险评分。" }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "风险严重程度，在规则或提供商赋值前为 `null`。" }, "amount": { "type": "string", "description": "作为十进制字符串的交易金额。与 API 不同，它未经过归一化，因此可以带有末尾零（最多 18 位小数）。" }, "currency": { "type": "string", "description": "`amount` 的货币代码或加密资产符号。" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "相对于主体的方向。" }, "action_required": { "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/TransactionVerificationSessionAction" }, { "$ref": "#/components/schemas/TransactionWalletOwnershipAction" } ], "discriminator": { "propertyName": "type", "mapping": { "verification_session": "#/components/schemas/TransactionVerificationSessionAction", "wallet_ownership": "#/components/schemas/TransactionWalletOwnershipAction" } }, "description": "待处理的终端用户操作，或 `null`。与交易上的 `action_required` 相同对象；`session_token` 属于凭证，切勿记录到日志中。" } }, "required": [ "webhook_type", "transaction_id", "txn_id", "status", "score", "severity", "amount", "currency", "direction", "action_required" ] } ] }, "TransactionStatusUpdatedEvent": { "description": "交易状态已更改，原因来自规则、审核或终端用户操作。仅针对生产环境应用发送。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "transaction.status.updated" ], "description": "始终为 `transaction.status.updated`。" }, "transaction_id": { "type": "string", "format": "uuid", "description": "Didit 的交易标识符。" }, "txn_id": { "type": "string", "nullable": true, "description": "您在创建时提供的 `transaction_id`，或为 `null`。" }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "变更后的监控状态。" }, "score": { "type": "integer", "description": "规则累计的风险评分。" }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "风险严重程度，在规则或提供商赋值前为 `null`。" }, "amount": { "type": "string", "description": "作为十进制字符串的交易金额。与 API 不同，它未经过归一化，因此可以带有末尾零（最多 18 位小数）。" }, "currency": { "type": "string", "description": "`amount` 的货币代码或加密资产符号。" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "相对于主体的方向。" }, "action_required": { "type": "object", "nullable": true, "oneOf": [ { "$ref": "#/components/schemas/TransactionVerificationSessionAction" }, { "$ref": "#/components/schemas/TransactionWalletOwnershipAction" } ], "discriminator": { "propertyName": "type", "mapping": { "verification_session": "#/components/schemas/TransactionVerificationSessionAction", "wallet_ownership": "#/components/schemas/TransactionWalletOwnershipAction" } }, "description": "待处理的终端用户操作，或 `null`。与交易上的 `action_required` 相同对象；`session_token` 属于凭证，切勿记录到日志中。" } }, "required": [ "webhook_type", "transaction_id", "txn_id", "status", "score", "severity", "amount", "currency", "direction", "action_required" ] } ] }, "TravelRuleStatusUpdatedEvent": { "description": "Travel Rule 交换状态已变更。在直到并包括 `FINISHED`、`CANCELLED` 或 `EXPIRED` 的每次状态转换时发送，此后绝不发送。针对生产环境应用发送；对于 Travel Rule 交换，也会针对沙盒应用发送（`environment: sandbox`）。没有顶级 `status`。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "travel_rule.status.updated" ], "description": "始终为 `travel_rule.status.updated`。" }, "transaction_id": { "type": "string", "format": "uuid", "description": "该兑换所属的交易。" }, "txn_id": { "type": "string", "nullable": true, "description": "您在创建时提供的 `transaction_id`，或为 `null`。" }, "travel_rule_status": { "type": "string", "enum": [ "AWAITING_COUNTERPARTY", "ON_HOLD", "COMPLETED", "FINISHED", "CANCELLED", "EXPIRED", "COUNTERPARTY_MISMATCHED_DATA", "COUNTERPARTY_VASP_NOT_FOUND", "COUNTERPARTY_VASP_NOT_REACHABLE", "UNCONFIRMED_OWNERSHIP", "COUNTERPARTY_VASP_GENERAL_DECLINE", "NOT_ENOUGH_COUNTERPARTY_DATA", "NOT_APPLICABLE" ], "description": "变更后的兑换状态。" }, "rail": { "type": "string", "enum": [ "", "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "TEST_VASP" ], "description": "交易所运行的网络，如果无法解析则为空字符串。`TEST_VASP` 是 Didit Test VASP 应答的沙盒转账。" }, "test_vasp": { "type": "boolean", "description": "仅在 Didit Test VASP 响应的沙盒转账中存在且为 `true`。" }, "test_vasp_scenario": { "type": "string", "description": "仅与 `test_vasp` 一同存在：决定结果的沙盒场景，或为空字符串。" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "转账方向。" } }, "required": [ "webhook_type", "transaction_id", "txn_id", "travel_rule_status", "rail", "direction" ] } ] }, "WorkflowComplianceChangedEvent": { "description": "已发布工作流的合规状态在重新评估后发生了变更。每个工作流触发一个事件。不存在顶级 `status`。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "workflow.compliance_changed" ], "description": "始终为 `workflow.compliance_changed`。" }, "workflow_id": { "type": "string", "format": "uuid", "description": "已变更的工作流。" }, "workflow_version": { "type": "integer", "description": "已评估的版本。" }, "workflow_label": { "type": "string", "nullable": true, "description": "工作流的显示名称。" }, "transition": { "type": "object", "required": [ "from", "to" ], "properties": { "from": { "type": "string", "enum": [ "compliant", "gaps_detected", "pending_change", "unknown_coverage", "not_evaluated" ], "description": "重新评估前的状态。" }, "to": { "type": "string", "enum": [ "compliant", "gaps_detected", "pending_change", "unknown_coverage", "not_evaluated" ], "description": "重新评估后的状态。" } } }, "severity": { "type": "string", "enum": [ "actionable", "indicative", "informative" ], "description": "`actionable` 表示检测到缺口，`indicative` 表示待处理的变更，`informative` 表示缺口已解决。" }, "kb_version": { "type": "string", "description": "所使用的监管知识库版本。" } }, "required": [ "webhook_type", "workflow_id", "workflow_version", "workflow_label", "transition", "severity", "kb_version" ] } ] }, "WebhookEventPayload": { "description": "已签名的 Webhook 投递的正文，由 `webhook_type` 区分。`activity.created` 可以被订阅，但目前不会发送。请将任何其他 `webhook_type` 视为新的事件类型并保留原始正文。", "oneOf": [ { "$ref": "#/components/schemas/SessionStatusUpdatedEvent" }, { "$ref": "#/components/schemas/SessionDataUpdatedEvent" }, { "$ref": "#/components/schemas/UserStatusUpdatedEvent" }, { "$ref": "#/components/schemas/UserDataUpdatedEvent" }, { "$ref": "#/components/schemas/BusinessStatusUpdatedEvent" }, { "$ref": "#/components/schemas/BusinessDataUpdatedEvent" }, { "$ref": "#/components/schemas/TransactionCreatedEvent" }, { "$ref": "#/components/schemas/TransactionStatusUpdatedEvent" }, { "$ref": "#/components/schemas/TravelRuleStatusUpdatedEvent" }, { "$ref": "#/components/schemas/WorkflowComplianceChangedEvent" }, { "$ref": "#/components/schemas/TransactionRuleSuggestionsCreatedEvent" } ], "discriminator": { "propertyName": "webhook_type", "mapping": { "status.updated": "#/components/schemas/SessionStatusUpdatedEvent", "data.updated": "#/components/schemas/SessionDataUpdatedEvent", "user.status.updated": "#/components/schemas/UserStatusUpdatedEvent", "user.data.updated": "#/components/schemas/UserDataUpdatedEvent", "business.status.updated": "#/components/schemas/BusinessStatusUpdatedEvent", "business.data.updated": "#/components/schemas/BusinessDataUpdatedEvent", "transaction.created": "#/components/schemas/TransactionCreatedEvent", "transaction.status.updated": "#/components/schemas/TransactionStatusUpdatedEvent", "travel_rule.status.updated": "#/components/schemas/TravelRuleStatusUpdatedEvent", "workflow.compliance_changed": "#/components/schemas/WorkflowComplianceChangedEvent", "transaction_rule_suggestions.created": "#/components/schemas/TransactionRuleSuggestionsCreatedEvent" } } }, "KYBRegistrySearchResolvedCallback": { "type": "object", "description": "一旦登记查询解析完成，发送至 `POST /v3/kyb/search/` 的 `webhook_url` 的回调正文。此回调未签名：请求带有 `X-Didit-Unsigned-Callback: true` 且不包含任何签名请求头，因此请通过将 `request_id` 与您发起的查询进行比对来确认。使用 `event_type`，而非 `webhook_type`。", "required": [ "event_id", "event_type", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at" ], "properties": { "event_id": { "type": "string", "format": "uuid", "description": "回调的标识符。" }, "event_type": { "type": "string", "enum": [ "kyb.registry_search.resolved" ], "description": "始终为 `kyb.registry_search.resolved`。" }, "request_id": { "type": "string", "format": "uuid", "description": "`POST /v3/kyb/search/` 返回的 `request_id`。" }, "vendor_data": { "type": "string", "nullable": true, "description": "回显您发送的 `vendor_data`。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "您发送的 `metadata` 回显。" }, "search_status": { "type": "string", "description": "当前始终为 `resolved`。" }, "search_resolved": { "type": "boolean", "description": "当 `search_status` 为 `resolved` 时为 `true`。" }, "kyb_registry": { "$ref": "#/components/schemas/KYBRegistrySearchResults" }, "timestamp": { "type": "integer", "description": "回调进入队列时的 Unix 时间（以秒为单位）。" }, "created_at": { "type": "integer", "description": "回调进入队列时的 Unix 时间（以秒为单位）。" } } }, "AMLScreening": { "type": "object", "properties": { "node_id": { "type": "string", "description": "工作流图谱中该 AML 步骤的唯一标识符。" }, "status": { "type": "string", "description": "此 AML 筛查的功能级状态。独立于顶级会话的 `status`：会话可以达成其总体决策，而单个功能仍保持 `In Review`。", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ] }, "total_hits": { "type": "integer", "description": "找到的匹配总数" }, "entity_type": { "type": "string", "description": "被筛查实体的类型：个人或企业" }, "hits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Didit 对命中的稳定标识符：`hit_` 后跟 24 个十六进制字符。再次对主体进行筛查时，相同的匹配实体保留相同的 `id`。在调用 AML 命中审核 endpoint 时作为 `hit_id` 传递。" }, "url": { "type": "string", "format": "uri", "description": "匹配项的来源 URL" }, "match": { "type": "boolean", "description": "这是否为已确认的匹配项" }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 1, "description": "已弃用的加权匹配分数，取值范围为 0-1（例如 `0.73`）。请改用 `match_score`（0-100）。", "deprecated": true }, "target": { "type": "boolean", "nullable": true, "description": "匹配的实体是否为名录收录的直接目标（而非关联方）。来源未指定时为 `null`。" }, "caption": { "type": "string", "description": "匹配项的说明或标题" }, "datasets": { "type": "array", "items": { "type": "string", "enum": [ "PEP", "PEP Level 1", "PEP Level 2", "PEP Level 3", "PEP Level 4", "Sanctions", "Adverse Media", "Warnings and Regulatory Enforcement", "Fitness and Probity", "SIP", "SIE", "Insolvency", "Other Lists" ] }, "description": "发现匹配项的数据集类别列表。指明该实体是否出现在政治公众人物名单（含等级）、制裁名单数据库、负面新闻、警告/监管执法或其他合规数据集中。当实体的来源未指明这些类别中的任何一项时，为 `Other Lists`。" }, "features": { "type": "object", "nullable": true, "description": "匹配项的附加特征" }, "rca_name": { "type": "string", "description": "RCA 名称（如果适用）" }, "last_seen": { "type": "string", "format": "date-time", "description": "最后一次发现匹配项的日期" }, "risk_view": { "type": "object", "properties": { "crimes": { "type": "object", "properties": { "score": { "type": "integer" }, "weightage": { "type": "integer" }, "risk_level": { "type": "string" }, "risk_scores": { "type": "object" } } }, "countries": { "type": "object", "properties": { "score": { "type": "integer" }, "weightage": { "type": "integer" }, "risk_level": { "type": "string" }, "risk_scores": { "type": "object" } } }, "categories": { "type": "object", "properties": { "score": { "type": "integer" }, "weightage": { "type": "integer" }, "risk_level": { "type": "string" }, "risk_scores": { "type": "object" } } }, "custom_list": { "type": "object" } } }, "first_seen": { "type": "string", "format": "date-time", "description": "首次发现匹配项的日期" }, "properties": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string" } }, "alias": { "type": "array", "items": { "type": "string" } }, "notes": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string", "nullable": true }, "gender": { "type": "array", "items": { "type": "string" } }, "height": { "type": "string", "nullable": true }, "topics": { "type": "string", "nullable": true }, "weight": { "type": "string", "nullable": true }, "address": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "website": { "type": "string", "nullable": true }, "eyeColor": { "type": "string", "nullable": true }, "keywords": { "type": "string", "nullable": true }, "lastName": { "type": "array", "items": { "type": "string" } }, "position": { "type": "string", "nullable": true }, "religion": { "type": "string", "nullable": true }, "birthDate": { "type": "array", "items": { "type": "string" } }, "education": { "type": "array", "items": { "type": "string" } }, "ethnicity": { "type": "string", "nullable": true }, "firstName": { "type": "array", "items": { "type": "string" } }, "hairColor": { "type": "string", "nullable": true }, "weakAlias": { "type": "string", "nullable": true }, "birthPlace": { "type": "array", "items": { "type": "string" } }, "modifiedAt": { "type": "string", "nullable": true }, "wikidataId": { "type": "string", "nullable": true }, "citizenship": { "type": "string", "nullable": true }, "nationality": { "type": "string", "nullable": true } } }, "match_score": { "type": "number", "description": "根据姓名相似度、出生日期和国家/地区匹配计算得出的加权身份置信度分数（0-100）。用于确定命中是误报还是可能匹配。", "format": "float", "nullable": true }, "risk_score": { "type": "number", "description": "主体风险评分（0-100）。用于根据非误报命中项中的最高 risk_score 确定最终 AML 状态（Approved/In Review/Declined）。" }, "review_status": { "type": "string", "description": "此命中项的审核状态。可以为 'Unreviewed'、'Confirmed Match'、'False Positive' 或 'Inconclusive'。", "enum": [ "Unreviewed", "Confirmed Match", "False Positive", "Inconclusive" ] }, "score_breakdown": { "type": "object", "description": "match_score 的详细计算明细。", "properties": { "name_score": { "type": "integer", "description": "原始姓名相似度百分比（0-100）。" }, "name_weight": { "type": "integer", "description": "配置中姓名的原始权重（0-100）。" }, "name_weight_normalized": { "type": "number", "description": "针对缺失数据重新加权后的姓名归一化权重（0-100）。" }, "name_contribution": { "type": "number", "description": "姓名对总分的贡献点数。" }, "dob_score": { "type": "integer", "description": "出生日期匹配分数（-100 到 100）。" }, "dob_weight": { "type": "integer", "description": "配置中出生日期的原始权重（0-100）。" }, "dob_weight_normalized": { "type": "number", "description": "针对缺失数据重新加权后的出生日期归一化权重（0-100）。" }, "dob_contribution": { "type": "number", "description": "出生日期对总分的贡献点数。" }, "country_score": { "type": "integer", "description": "国家/地区匹配分数（-100 到 100）。" }, "country_weight": { "type": "integer", "description": "配置中国家/地区的原始权重（0-100）。" }, "country_weight_normalized": { "type": "number", "description": "针对缺失数据重新加权后的国家/地区归一化权重（0-100）。" }, "country_contribution": { "type": "number", "description": "国家/地区对总分的贡献点数。" }, "document_number_match_type": { "type": "string", "description": "证件号码“Golden Key”评估的结果。", "enum": [ "MATCH", "NEUTRAL", "HARD_MISMATCH" ] }, "document_number_effect": { "type": "string", "description": "证件号码对评分影响的便于人类阅读的描述。" }, "total_score": { "type": "integer", "description": "最终加权匹配分数（0-100）。" } } }, "pep_matches": { "type": "array", "items": { "type": "object", "properties": { "aliases": { "type": "array", "items": { "type": "string" } }, "education": { "type": "array", "items": { "type": "string" } }, "list_name": { "type": "string" }, "publisher": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "description": { "type": "string" }, "matched_name": { "type": "string" }, "pep_position": { "type": "string" }, "date_of_birth": { "type": "string" }, "other_sources": { "type": "array", "items": { "type": "string" } }, "place_of_birth": { "type": "string" } } } }, "linked_entities": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "array", "items": { "type": "string" } }, "active": { "type": "array", "items": { "type": "string" } }, "status": { "type": "array", "items": { "type": "string" } }, "details": { "type": "array", "items": { "type": "string" } }, "relation": { "type": "array", "items": { "type": "string" } } } } }, "warning_matches": { "type": "array", "description": "警告和监管执法匹配项列表。包括来自以下类别的条目：Warning、SIP、Warnings and Regulatory Enforcement、Fitness and Probity、SIE 以及 Insolvency。", "items": { "type": "object", "properties": { "list_name": { "type": "string", "description": "警告名单发布者的名称" }, "matched_name": { "type": "string", "description": "在警告名单中匹配到的名称" }, "description": { "type": "string", "description": "警告条目说明" }, "publisher": { "type": "string", "description": "警告的发布者或来源" }, "source_url": { "type": "string", "format": "uri", "description": "警告来源的 URL" }, "other_sources": { "type": "array", "items": { "type": "string" }, "description": "其他来源 URL" }, "countries": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "与该警告关联的国家/地区" }, "created_at": { "type": "string", "nullable": true, "description": "警告条目创建的日期" }, "updated_at": { "type": "string", "nullable": true, "description": "警告条目上次更新的日期" }, "additional_data": { "type": "object", "description": "来自警告数据源的其他数据。可能包含带有 `case_details` 数组的 `data` 对象。", "properties": { "data": { "type": "object", "properties": { "case_details": { "type": "array", "description": "与此匹配项相关的警告案件详情", "items": { "type": "object", "properties": { "case_type": { "type": "string", "description": "警告案件的类型", "enum": [ "Accusation", "Arrest", "Bribery", "Criminal", "Fraud", "Illegal Fundraising", "Non-conviction Terror", "Proclaimed Offender", "Regulatory Enforcement", "Terrorism", "Terrorism-related", "Terrorism-related listing" ] } } } } } } } } } } }, "sanction_matches": { "type": "array", "description": "为此实体找到的制裁名单匹配项列表。", "items": { "type": "object", "properties": { "list_name": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "制裁名单的名称" }, "matched_name": { "type": "string", "description": "在制裁名单中匹配到的名称" }, "description": { "type": "string", "description": "制裁条目说明" }, "reason": { "type": "string", "nullable": true, "description": "该实体受到制裁的自由文本原因。由制裁名单中的原因条目拼接而成。示例：'Executive Order 13224 (Terrorism)'、'Support for actions undermining Ukraine's sovereignty'、'Listed due to national security concerns。'" }, "source_url": { "type": "string", "format": "uri", "description": "制裁来源的 URL" }, "other_sources": { "type": "array", "items": { "type": "string" }, "description": "其他来源 URL" }, "details": { "type": "array", "items": { "type": "string" }, "description": "关于制裁的其他详情" }, "legal_basis": { "type": "array", "items": { "type": "string" }, "description": "制裁的法律依据" }, "listed_on": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "该实体被列入名单的日期" }, "sanction_list": { "type": "array", "items": { "type": "string" }, "nullable": true, "description": "制裁名单标识符" }, "sanction_program": { "type": "array", "items": { "type": "string" }, "description": "该实体所列入的制裁项目" }, "sanctioning_authority": { "type": "array", "items": { "type": "string" }, "description": "实施制裁的机构" }, "updated_on": { "type": "array", "items": { "type": "string" }, "description": "制裁条目最后更新的日期" }, "additional_data": { "type": "object", "description": "未在主要字段中捕获的来自制裁数据源的其他数据" } } } }, "adverse_media_details": { "type": "object", "properties": { "sentiment": { "type": "string" }, "entity_type": { "type": "string" }, "sentiment_score": { "type": "integer" }, "adverse_keywords": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "adverse_media_matches": { "type": "array", "items": { "type": "object", "properties": { "country": { "type": "string" }, "summary": { "type": "string" }, "headline": { "type": "string" }, "sentiment": { "type": "string" }, "thumbnail": { "type": "string", "format": "uri" }, "source_url": { "type": "string", "format": "uri" }, "author_name": { "type": "string", "nullable": true }, "other_sources": { "type": "array", "items": { "type": "string" } }, "adverse_keywords": { "type": "array", "items": { "type": "string" } }, "sentiment_score": { "type": "integer" }, "publication_date": { "type": "string", "format": "date-time" } } } }, "additional_information": { "type": "object" } } } }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "综合 AML 筛查分数：所有命中项中的最高风险评分（浮点数，0-100）。计算完成前为 `null`。" }, "screened_data": { "type": "object", "properties": { "full_name": { "type": "string" }, "nationality": { "type": "string" }, "date_of_birth": { "type": "string", "format": "date" }, "document_number": { "type": "string", "nullable": true } } }, "is_ongoing_monitoring_enabled": { "type": "boolean", "description": "该筛查是否启用了持续 AML 监控。如果为 `true`，系统将定期对该实体重新筛查，且任何新的命中都会更新报告。" }, "next_ongoing_monitoring_bill_date": { "type": "string", "format": "date", "nullable": true, "description": "此持续监控订阅下次计费的日期（YYYY-MM-DD）。当 `is_ongoing_monitoring_enabled = true` 时，计算方式为上次持续监控计费日期加上 365 天；否则为 `null`。这是计费日期，并非筛查日期，筛查日期请使用 `last_ongoing_screening_at`。" }, "last_ongoing_screening_at": { "type": "string", "format": "date-time", "nullable": true, "description": "持续监控上次完成对该记录重新筛查的时间，无论结果是否发生变化。如果该记录从未被重新筛查过，则为 `null`；绝不会从启用日期或计费日期进行回填。" }, "last_ongoing_screening_datasets_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "提供商在进行该次筛查时报告的最新 AML 数据集更新日期。提供商未报告数据集日期时为 `null`；绝不进行估算。" }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACEMATCH", "PROOF_OF_ADDRESS", "PHONE", "EMAIL", "AML", "LOCATION", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "GEOLOCATION", "SIGNATURE" ], "description": "生成此警告的功能。该值标识警告所属的功能块。在 AML 筛查中，这通常是 `AML`，但上述枚举在决策 payload 的所有功能警告中具有权威性。" }, "risk": { "type": "string" }, "additional_data": { "type": "object", "nullable": true }, "log_type": { "type": "string" }, "short_description": { "type": "string" }, "long_description": { "type": "string" }, "node_id": { "type": "string", "description": "生成此警告的工作流图节点 ID" } } } } } }, "MonitoringEvent": { "type": "object", "description": "由列表和主体时间线 endpoint 返回的一条已存储监控事件。受限证据（payload、设备上下文、规则证据）仅通过 `GET /v3/events/{event_uuid}/` 返回。", "required": [ "event_uuid", "event_id", "event_category", "action_type", "occurred_at", "received_at", "status", "score", "subject_vendor_data", "subject_entity_type", "subject_uuid", "counterparty_vendor_data", "session_id", "device_fingerprint", "ip_address", "ip_country", "amount", "currency", "game_id", "round_id", "bonus_id", "affiliate_code", "payment_reference_id", "retention_class", "rules_matched_count", "correlation_pending", "is_droppable" ], "properties": { "event_uuid": { "type": "string", "format": "uuid", "description": "事件的 Didit 标识符。在获取和删除调用中将其用作 `{event_uuid}`。" }, "event_id": { "type": "string", "maxLength": 128, "description": "您自己的标识符，即您发送的幂等性密钥。" }, "event_category": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ], "description": "事件类别。" }, "action_type": { "type": "string", "maxLength": 128, "description": "该类别中发生的情况，与您发送的内容一致。" }, "occurred_at": { "type": "string", "format": "date-time", "description": "事件在您方发生的时间。" }, "received_at": { "type": "string", "format": "date-time", "description": "Didit 接受该事件的时间。" }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "`ACCEPTED`：已存储，没有匹配的规则改变其状态（大多数事件的常规响应，在不运行任何规则的沙盒应用中始终为此响应）。`APPROVED`：规则命中且评分低于您的审核阈值。`IN_REVIEW`：规则使评分超过审核阈值或直接设置了该状态。`DECLINED`：规则将其拒绝或评分超过了您的拒绝阈值。" }, "score": { "type": "integer", "description": "累积规则分数。从 0 开始；规则的 `add_score` 操作会改变该分数（允许负增量）。" }, "subject_vendor_data": { "type": "string", "maxLength": 255, "description": "事件的 `subject.vendor_data`：您为该用户或公司设置的 id。" }, "subject_entity_type": { "type": "string", "description": "`individual` 或 `company`：`subject_vendor_data` 所指的主体类型。", "example": "individual" }, "subject_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "事件解析关联到的用户（个人）或企业的 UUID，如果该记录已不存在则为 null。" }, "counterparty_vendor_data": { "type": "string", "nullable": true, "description": "P2P 事件的另一方参与者（从 `payload.counterparty_vendor_data` 提升）。", "maxLength": 255 }, "session_id": { "type": "string", "nullable": true, "description": "随事件发送的 `session.session_id`。", "maxLength": 255 }, "device_fingerprint": { "type": "string", "nullable": true, "description": "随事件一同发送的 `device_context.fingerprint`。", "maxLength": 255 }, "ip_address": { "type": "string", "nullable": true, "description": "事件的 IP 地址。在服务器通道上，这是您发送的 `device_context.network_context.ip_address`；在设备通道上，它是请求的 IP。", "maxLength": 64 }, "ip_country": { "type": "string", "nullable": true, "description": "通过 IP 信息增强获取的 `ip_address` 国家/地区代码；如果地址未进行信息增强（缺失、私有或地址尚不可知的低价值遥测数据），则为 null。", "example": "ES" }, "amount": { "type": "string", "nullable": true, "description": "保留 18 位小数的十进制字符串形式的金额，按优先级依次取自 `transaction_context.amount`、`payload.amount` 或 `payload.stake_amount`。", "example": "250.000000000000000000" }, "currency": { "type": "string", "nullable": true, "description": "来自 `transaction_context.currency` 或 `payload.currency` 的货币。", "maxLength": 10 }, "game_id": { "type": "string", "nullable": true, "description": "从 `payload.game_id` 提取。", "maxLength": 128 }, "round_id": { "type": "string", "nullable": true, "description": "从 `payload.round_id` 提取。", "maxLength": 128 }, "bonus_id": { "type": "string", "nullable": true, "description": "由 `payload.bonus_id` 提升而来。", "maxLength": 128 }, "affiliate_code": { "type": "string", "nullable": true, "description": "由 `payload.affiliate_code` 提升而来。", "maxLength": 128 }, "payment_reference_id": { "type": "string", "nullable": true, "description": "来自 `transaction_context.payment_reference_id` 或 `payload.payment_reference_id` 的付款参考编号。", "maxLength": 255 }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "数据保留类别。支付和争议事件为 `monetary_or_compliance`；安全与理性博彩事件为 `risk_relevant`；`session.page_view`、`session.sdk_heartbeat`、`session.sdk_loaded`、`session.device_seen`、`session.bot_signal_observed`、`bonus.promotion_viewed` 和 `affiliate.referral_clicked` 为 `low_value`；其他所有事件为 `standard`。命中生效规则的事件将被提升为 `risk_relevant`（绝不降级）。" }, "rules_matched_count": { "type": "integer", "minimum": 0, "description": "与该事件匹配的规则数量，包括处于 `TEST` 模式的规则（该模式仅记录证据但不执行任何操作）。" }, "correlation_pending": { "type": "boolean", "description": "当此事件仍需运行异步规则（跨主体关联，或时长超过 24 小时的序列）时为 `true`。它会在数分钟内处理完成，并就地更新 `status`、`score` 和 `rules_matched_count`。" }, "is_droppable": { "type": "boolean", "description": "处于背压状态下的 SDK 是否可以丢弃此类事件。对于所有 `security`、`payment`、`dispute` 和 `responsible_gambling` 事件，以及 `gameplay.bet_placed`、`gameplay.bet_settled` 和 `gameplay.p2p_settlement` 事件，此项均为 `false`。" } } }, "MonitoringEventDetail": { "description": "包含完整封装、增强信息和规则证据的单条监控事件。包含 `MonitoringEvent` 的所有字段以及下列字段。", "allOf": [ { "$ref": "#/components/schemas/MonitoringEvent" }, { "type": "object", "required": [ "payload", "custom_values", "device_context", "field_sources", "session_sequence", "table_id", "hand_id", "match_id", "market_id", "side", "role", "net_result_amount", "payment_fingerprint", "instrument_reference_hash", "withdrawal_address_hash", "dispute_id", "chargeback_id", "changed_field", "identity_match_ref", "schema_version", "expires_at", "rules_evaluated_count", "rule_runs", "ip_enrichment", "subject_profile", "tags" ], "properties": { "payload": { "type": "object", "additionalProperties": true, "description": "您在 `payload` 中发送的类别字段。" }, "custom_values": { "type": "object", "additionalProperties": true, "description": "您发送的标量 `custom_values`。当 IP 丰富化功能标记该地址且您未设置这些值时，Didit 会添加 `vpn_or_proxy_detected: true` 或 `is_data_center: true`。" }, "device_context": { "type": "object", "additionalProperties": true, "description": "存储的设备上下文：您的 `device_context`（在发送时包含 `fingerprint`、`persistent_device_id` 和 `bot_score`），对于您留空的键，会通过 IP 丰富化补充 `network_context`（`ip_country`、`ip_country_code`、`ip_city`、`asn_number`、`asn_organization`、`is_vpn_or_tor`、`is_data_center`、`proxy_type`、`connection_type`）。" }, "field_sources": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "customer", "sdk", "server" ] }, "description": "溯源字段路径：`customer`（由您的后端发送）、`sdk`（通过设备通道发送）或 `server`（由 Didit 派生，例如 `received_at` 和富化网络字段）。在根据匹配结果采取操作前请检查该字段。" }, "session_sequence": { "type": "integer", "format": "int64", "nullable": true, "description": "随事件发送的 `session.sequence`。" }, "table_id": { "type": "string", "nullable": true, "description": "从 `payload.table_id` 提取。", "maxLength": 128 }, "hand_id": { "type": "string", "nullable": true, "description": "从 `payload.hand_id` 提取。", "maxLength": 128 }, "match_id": { "type": "string", "nullable": true, "description": "从 `payload.match_id` 提取。", "maxLength": 128 }, "market_id": { "type": "string", "nullable": true, "description": "从 `payload.market_id` 提取。", "maxLength": 128 }, "side": { "type": "string", "nullable": true, "description": "从 `payload.side` 提取。", "maxLength": 64 }, "role": { "type": "string", "nullable": true, "description": "从 `payload.role` 提取。", "maxLength": 64 }, "net_result_amount": { "type": "string", "nullable": true, "description": "从 `payload.net_result_amount` 提取，为保留 18 位小数的十进制字符串。", "example": "-120.000000000000000000" }, "payment_fingerprint": { "type": "string", "nullable": true, "description": "从 `payload.payment_fingerprint` 提取。", "maxLength": 255 }, "instrument_reference_hash": { "type": "string", "nullable": true, "description": "从 `payload.instrument_reference_hash` 提取。", "maxLength": 255 }, "withdrawal_address_hash": { "type": "string", "nullable": true, "description": "从 `payload.withdrawal_address_hash`（或 `payload.destination_reference_hash`）提取。", "maxLength": 255 }, "dispute_id": { "type": "string", "nullable": true, "description": "从 `payload.dispute_id` 提取。", "maxLength": 255 }, "chargeback_id": { "type": "string", "nullable": true, "description": "从 `payload.chargeback_id` 提取。", "maxLength": 255 }, "changed_field": { "type": "string", "nullable": true, "description": "从 `payload.changed_field` 提取（安全变更事件）。", "maxLength": 128 }, "identity_match_ref": { "type": "string", "nullable": true, "description": "从 `payload.identity_match_ref` 提取（负责任博彩登记库匹配）。", "maxLength": 255 }, "schema_version": { "type": "integer", "description": "事件信封模式的版本。当前为 `1`。", "example": 1 }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "事件根据其保留类别到期并被删除的时间：`occurred_at` 加上类别周期（默认 14、30 或 90 天，可按应用调整）。对于遵循交易保留规则的 `monetary_or_compliance` 事件为 Null。" }, "rules_evaluated_count": { "type": "integer", "minimum": 0, "description": "针对此事件评估的事件规则数量。" }, "rule_runs": { "type": "array", "description": "与该事件匹配的每条规则，最新的排在最前。", "items": { "$ref": "#/components/schemas/MonitoringEventRuleRun" } }, "ip_enrichment": { "type": "object", "nullable": true, "description": "事件 IP 地址的丰富化信息，如果未对该地址进行丰富化则为 null。参见 [IP 丰富化](https://docs.didit.me/zh/transaction-monitoring/ip-enrichment)。", "properties": { "ip_country_code": { "type": "string", "nullable": true, "description": "地址的国家/地区代码。" }, "ip_city": { "type": "string", "nullable": true, "description": "地址所在城市。" }, "asn_number": { "type": "integer", "nullable": true, "description": "自治系统编号（ASN）。" }, "asn_organization": { "type": "string", "nullable": true, "description": "运营该自治系统的组织。" }, "is_vpn_or_tor": { "type": "boolean", "description": "该地址是否为已知的 VPN 或 Tor 出口节点。" }, "is_data_center": { "type": "boolean", "description": "该地址是否属于托管或数据中心网络。" }, "proxy_type": { "type": "string", "nullable": true, "description": "地址的代理分类，为不透明字符串，或为 null。" }, "last_enriched_at": { "type": "string", "format": "date-time", "nullable": true, "description": "该地址上次丰富数据的时间。" } }, "required": [ "ip_country_code", "ip_city", "asn_number", "asn_organization", "is_vpn_or_tor", "is_data_center", "proxy_type", "last_enriched_at" ] }, "subject_profile": { "type": "object", "nullable": true, "description": "主体的已缓存邮箱和电话风险信号，当主体不存在画像时为 null。", "properties": { "email_risk_score": { "type": "integer", "nullable": true, "description": "邮箱风险评分。" }, "email_deliverability": { "type": "string", "nullable": true, "description": "邮箱可投递性判定结果。" }, "email_is_disposable": { "type": "boolean", "nullable": true, "description": "该邮箱地址是否为一次性邮箱。" }, "email_is_breached": { "type": "boolean", "nullable": true, "description": "该邮箱地址是否出现在已知的数据泄露事件中。" }, "email_social_count": { "type": "integer", "nullable": true, "description": "与该邮箱地址关联的在线账户数量。" }, "email_social_providers": { "type": "array", "items": { "type": "string" }, "description": "找到与该邮箱地址关联的账户的在线服务名称。" }, "phone_risk_score": { "type": "integer", "nullable": true, "description": "电话风险评分。" }, "phone_line_type": { "type": "string", "nullable": true, "description": "电话线路类型。" }, "phone_carrier": { "type": "string", "nullable": true, "description": "电话运营商名称。" }, "phone_social_count": { "type": "integer", "nullable": true, "description": "与该电话号码关联的在线账户数量。" }, "phone_social_providers": { "type": "array", "items": { "type": "string" }, "description": "找到与该电话号码关联的账户的在线服务名称。" }, "source_provider": { "type": "string", "nullable": true, "description": "档案来源的不透明标识符。" }, "last_enriched_at": { "type": "string", "format": "date-time", "nullable": true, "description": "档案最后一次刷新的时间。" } }, "required": [ "email_risk_score", "email_deliverability", "email_is_disposable", "email_is_breached", "email_social_count", "email_social_providers", "phone_risk_score", "phone_line_type", "phone_carrier", "phone_social_count", "phone_social_providers", "source_provider", "last_enriched_at" ] }, "tags": { "type": "array", "items": { "type": "string" }, "description": "附加到事件的标签名称（规则 `add_tags` 操作）。" } } } ] }, "MonitoringEventRuleRun": { "type": "object", "properties": { "rule_uuid": { "type": "string", "format": "uuid", "description": "交易监控规则的 UUID。" }, "rule_title": { "type": "string", "description": "规则的标题。" }, "library_key": { "type": "string", "nullable": true, "description": "规则从规则库安装时的库密钥，否则为 null。" }, "matched": { "type": "boolean", "description": "始终为 `true`：仅记录匹配的运行。" }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "规则运行时的模式。`TEST` 运行会记录证据，但不应用任何操作。" }, "is_async": { "type": "boolean", "description": "当本次运行来自异步关联轮次而非摄取请求时为 `true`。" }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "规则的严重程度。对于 `TEST` 运行以及没有严重程度的规则，该值为 Null。" }, "score_delta": { "type": "integer", "description": "本次运行对事件评分的改变幅度（`TEST` 运行为 0）。" }, "action_summary": { "type": "string", "nullable": true, "description": "所应用操作的简短摘要，例如 `score +40; add_tag:VPN_LOGIN`。未应用任何操作时为 null。" }, "matched_payload": { "type": "array", "description": "匹配的条件和聚合。条件条目包含 `field`、`operator`、`expected_value`、`current_value`、`matched`、`group_index`、`group_logic` 以及 `field_source`（`server`、`sdk` 或 `customer`）；聚合条目包含 `metric`、`field`、`operator`、`expected_value`、`computed_value`、`window`、`filters`、`matched` 和 `sample_references`。", "items": { "type": "object", "additionalProperties": true } }, "created_at": { "type": "string", "format": "date-time", "description": "规则运行记录的时间。" } }, "required": [ "rule_uuid", "rule_title", "library_key", "matched", "mode", "is_async", "severity", "score_delta", "action_summary", "matched_payload", "created_at" ] }, "MonitoringEventPage": { "type": "object", "description": "一页监控事件，按 `occurred_at` 由新到旧排序。", "required": [ "count", "next", "previous", "results" ], "properties": { "count": { "type": "integer", "description": "匹配事件的数量，不超过 100 时为精确值，超过 100 时上限为 100。请勿据此计算页数；请跟随 `next` 直至其为 null。" }, "next": { "type": "string", "format": "uri", "nullable": true, "description": "下一页的 URL，最后一页为 null。" }, "previous": { "type": "string", "format": "uri", "nullable": true, "description": "上一页的 URL，第一页为 null。" }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringEvent" } } } }, "MonitoringEventCreateRequest": { "type": "object", "description": "事件信封，每个类别均相同。支持 camelCase 别名：`eventId`、`eventCategory`（或 `category`）、`actionType`、`occurredAt`、`timeZone`（或 `zoneId`）、`deviceContext`（或 `device`）、`transactionContext`、`customValues`（或 `props`）；在 `subject` 内支持：`vendorData`、`entityType`、`fullName`；在 `session` 内支持：`sessionId`、`pageUrl`；在 `transaction_context` 内支持：`paymentReferenceId`。", "required": [ "event_id", "event_category", "action_type", "occurred_at", "subject" ], "properties": { "event_id": { "type": "string", "maxLength": 128, "description": "您对事件的标识符，在每个应用中唯一。它是幂等性密钥：在其下重新发送相同的 `event_category`、`action_type`、`occurred_at`、`subject.vendor_data` 和 `payload` 将被视为重放，任何不同则会导致冲突。", "example": "login-2026-10-17-000001" }, "event_category": { "type": "string", "enum": [ "auth", "session", "gameplay", "bonus", "affiliate", "payment", "dispute", "security", "responsible_gambling", "custom" ], "description": "事件类别。", "example": "auth" }, "action_type": { "type": "string", "minLength": 1, "maxLength": 128, "description": "该类别中发生的情况。开放词汇；[事件摄入](https://docs.didit.me/zh/transaction-monitoring/events)中列出的托管操作（例如 `login`、`deposit_completed`、`chargeback_opened`）会启用类型化验证和托管规则字段。首尾空格会被去除。", "example": "login" }, "occurred_at": { "type": "string", "format": "date-time", "description": "事件在您方发生的时间，ISO 8601 格式（无偏移量的值视为 UTC）。不能早于过去 7 天，也不能晚于未来 5 分钟。", "example": "2026-10-17T09:15:02.481Z" }, "time_zone": { "type": "string", "nullable": true, "maxLength": 64, "description": "您所在一侧事件发生时的时区，例如 `Europe/Madrid`。与事件一同存储；读取 endpoint 不会返回。" }, "subject": { "type": "object", "description": "事件所属的用户或公司。它会解析为您的应用中具有此 `vendor_data` 的用户（或公司）；若不存在则会创建一个。", "required": [ "vendor_data" ], "properties": { "vendor_data": { "type": "string", "minLength": 1, "maxLength": 255, "description": "您对主体的 ID。", "example": "user-42" }, "entity_type": { "type": "string", "maxLength": 32, "default": "individual", "description": "`company` 将主体解析为企业；任何其他值（默认 `individual`）将其解析为个人。同一个 `vendor_data` 可以分别指代一个企业和一个个人。", "example": "individual" }, "full_name": { "type": "string", "nullable": true, "maxLength": 512, "description": "显示名称，仅在此事件创建用户或企业时使用。" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "已验证为邮箱地址；不会存储在事件中。" }, "phone": { "type": "string", "nullable": true, "maxLength": 32, "description": "已验证；不会存储在事件中。" }, "country": { "type": "string", "nullable": true, "maxLength": 3, "description": "已验证；不会存储在事件中。" } } }, "business": { "type": "object", "description": "事件所属的企业（当与主体不同时）。仅读取 `vendor_data`。", "additionalProperties": true, "properties": { "vendor_data": { "type": "string", "maxLength": 255, "description": "您对企业的 ID。可作为 `business_vendor_data` 进行过滤。", "example": "merchant-7" } } }, "session": { "type": "object", "description": "您针对该事件的会话上下文。", "properties": { "session_id": { "type": "string", "nullable": true, "maxLength": 255, "description": "您的会话标识符。可作为 `session_id` 进行过滤和返回。" }, "sequence": { "type": "integer", "nullable": true, "description": "事件在会话中的位置。以 `session_sequence` 返回。" }, "page_url": { "type": "string", "nullable": true, "maxLength": 2048, "description": "已验证；不会存储在事件中。" }, "referrer": { "type": "string", "nullable": true, "maxLength": 2048, "description": "已验证；不会存储在事件中。" } } }, "device_context": { "type": "object", "additionalProperties": true, "description": "设备与网络上下文，按发送原样存储并通过 `GET /v3/events/{event_uuid}/` 返回。在此服务器通道上，Didit 无法看到终端用户的连接，因此规则进行丰富并使用的 IP 是您发送的 `network_context.ip_address`。", "properties": { "fingerprint": { "type": "string", "maxLength": 255, "description": "设备指纹。可通过 `device_fingerprint` 进行过滤。" }, "persistent_device_id": { "type": "string", "maxLength": 255, "description": "您的持久化设备标识符。" }, "bot_score": { "type": "integer", "description": "来自您自有检测的机器人评分，为整数。" }, "network_context": { "type": "object", "additionalProperties": true, "properties": { "ip_address": { "type": "string", "maxLength": 64, "description": "终端用户的地址。公网地址按每个唯一地址丰富化一次。", "example": "203.0.113.42" } } } } }, "transaction_context": { "type": "object", "description": "金额上下文。此处的非空值也会满足操作所需的 payload 键。", "properties": { "amount": { "type": "string", "nullable": true, "description": "以十进制字符串表示的金额（亦可接受数字）。", "example": "1000.00" }, "currency": { "type": "string", "nullable": true, "maxLength": 10, "description": "货币代码。" }, "direction": { "type": "string", "nullable": true, "maxLength": 16, "description": "资金流动方向，例如 `inbound` 或 `outbound`。" }, "payment_reference_id": { "type": "string", "nullable": true, "maxLength": 255, "description": "您的付款参考编号。可作为 `payment_reference_id` 进行过滤。" } } }, "payload": { "type": "object", "additionalProperties": true, "description": "类别的领域字段，JSON 编码后最多 16384 字节。部分操作需要指定键（在 `payload` 或 `transaction_context` 中）：`gameplay.p2p_settlement` 需要 `game_id`、`counterparty_vendor_data`、`stake_amount`、`net_result_amount`、`role` 以及 `hand_id`、`round_id`、`match_id` 之一；`gameplay.bet_placed` 和 `gameplay.bet_settled` 需要 `game_id`；`payment.deposit_initiated`、`payment.deposit_completed`、`payment.withdrawal_requested` 和 `payment.withdrawal_completed` 需要 `payment_reference_id`、`amount`、`currency`、`payment_method`、`status`；`payment.withdrawal_address_changed` 需要 `withdrawal_address_hash`；`dispute.chargeback_opened`、`dispute.chargeback_won` 和 `dispute.chargeback_lost` 需要 `payment_reference_id` 以及 `dispute_id`、`chargeback_id` 之一；`session.bot_signal_observed` 需要 `telemetry_schema_version` 以及 `bot_score`、`actions_per_minute`、`timing_variance_ms`、`pointer_entropy`、`keystroke_entropy`、`reaction_time_ms_p50` 之一；`responsible_gambling.self_exclusion_match` 需要 `registry_source`、`exclusion_status`、`identity_match_ref`。以 `_changed` 结尾的每个 `security` 操作都需要 `changed_field`，并且当字段为 `password`、`mfa_method`、`mfa`、`email`、`phone`、`withdrawal_address`、`payout_method` 或 `api_key` 时，还需要 `previous_reference_hash` 或 `new_reference_hash`。请发送哈希和引用，切勿发送卡号、完整提现地址、密码哈希或 MFA 密钥。" }, "custom_values": { "type": "object", "description": "最多 100 个自定义键，可在规则中通过 `custom_values.` 寻址。值必须为标量（字符串、数字、布尔值或 null）；不支持嵌套对象和数组。", "additionalProperties": { "nullable": true, "oneOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" } ] } } }, "example": { "event_id": "login-2026-10-17-000001", "event_category": "auth", "action_type": "login", "occurred_at": "2026-10-17T09:15:02.481Z", "time_zone": "Europe/Madrid", "subject": { "vendor_data": "user-42", "entity_type": "individual" }, "session": { "session_id": "web-session-abc", "sequence": 142 }, "device_context": { "fingerprint": "fp-a8c1", "network_context": { "ip_address": "203.0.113.42" } }, "payload": { "method": "password" }, "custom_values": { "vip_tier": "gold" } } }, "MonitoringEventIngestResult": { "type": "object", "description": "接收单个事件的结果。新事件与幂等重放返回相同的结构。", "required": [ "event_uuid", "event_id", "status", "score", "rules_evaluated_count", "rules_matched_count", "correlation_pending", "retention_class", "expires_at", "idempotent_replay", "rule_matches" ], "properties": { "event_uuid": { "type": "string", "format": "uuid", "description": "已存储事件的 Didit 标识符。" }, "event_id": { "type": "string", "description": "您的 `event_id`。" }, "status": { "type": "string", "enum": [ "ACCEPTED", "APPROVED", "IN_REVIEW", "DECLINED" ], "description": "实时规则运行后的状态。请参阅 `MonitoringEvent.status`。" }, "score": { "type": "integer", "description": "实时规则运行后的分数。" }, "rules_evaluated_count": { "type": "integer", "minimum": 0, "description": "请求中评估的事件规则数量。沙盒应用中为 0，因为沙盒中不运行规则。" }, "rules_matched_count": { "type": "integer", "minimum": 0, "description": "匹配的规则数量，包括处于 `TEST` 模式的规则。" }, "correlation_pending": { "type": "boolean", "description": "当异步规则仍需运行时为 `true`。请在几分钟后调用 `GET /v3/events/{event_uuid}/` 以获取最终的 `status` 和 `score`。" }, "retention_class": { "type": "string", "enum": [ "low_value", "standard", "risk_relevant", "monetary_or_compliance" ], "description": "数据保留类别（在由命中规则提升后）。" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "事件根据其保留类别到期并被删除的时间。对于 `monetary_or_compliance`（支付和争议）事件为 Null。" }, "idempotent_replay": { "type": "boolean", "description": "当具有此 `event_id` 且内容相同的事件已被存储时为 `true`；返回的值为已存储事件的值，且不会再次运行任何规则。" }, "rule_matches": { "type": "array", "description": "匹配该事件的规则。", "items": { "type": "object", "required": [ "rule_id", "library_key", "mode", "is_async" ], "properties": { "rule_id": { "type": "string", "format": "uuid", "description": "规则的 UUID。" }, "library_key": { "type": "string", "nullable": true, "description": "规则从规则库安装时的库密钥，否则为 null。" }, "mode": { "type": "string", "enum": [ "ACTIVE", "TEST" ], "description": "`TEST` 规则会记录匹配，但不应用任何操作。" }, "is_async": { "type": "boolean", "description": "当比对结果来自异步轮次时为 `true`。" } } } } } }, "ComplianceList": { "type": "object", "description": "某个应用的黑名单、白名单或自定义名单。", "required": [ "uuid", "name", "description", "list_type", "entry_type", "is_system", "entry_count", "last_entry_added_at", "created_at", "updated_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "名单标识符。在名单和条目 endpoint 中用作 `list_uuid`，并在带有 `value_type: \"list\"` 的工作流或交易规则条件中用作值。" }, "name": { "type": "string", "maxLength": 255, "description": "名单名称，在应用的各个名单中具有唯一性。" }, "description": { "type": "string", "description": "自由文本描述。未设置时为空字符串。" }, "list_type": { "type": "string", "enum": [ "blocklist", "allowlist", "custom" ], "description": "`blocklist`：匹配会拒绝会话或交易（仅限系统名单，每种条目类型一个）。`allowlist`：匹配的项目受信任，例如人脸白名单会跳过重复人脸操作；绝不会覆盖黑名单匹配。`custom`：用于工作流和交易规则条件（`value_type: \"list\"`）。" }, "entry_type": { "type": "string", "enum": [ "face", "document", "phone", "email", "ip_address", "device_fingerprint", "wallet_address", "bank_account", "country", "user", "business", "key" ], "description": "该名单包含的内容：`face`、`document`（证件号码）、`phone`、`email`、`ip_address`（地址或 CIDR 范围）、`device_fingerprint`、`wallet_address`、`bank_account`、`country`（ISO 3166-1 alpha-3）、`user` 或 `business`（您的 `vendor_data`），或 `key`（任意字符串）。它决定了条目值的验证和匹配方式。" }, "is_system": { "type": "boolean", "description": "`true` 表示由 Didit 预配的名单：每种条目类型一个黑名单（`face`、`document`、`phone`、`email`、`ip_address`、`device_fingerprint`、`wallet_address`、`bank_account`、`user`、`business`）、**High Risk Countries** 自定义名单以及系统白名单。系统名单无法重命名、编辑或删除；您可以添加和删除其中的条目。" }, "entry_count": { "type": "integer", "minimum": 0, "description": "当前列表中条目的数量。" }, "last_entry_added_at": { "type": "string", "format": "date-time", "nullable": true, "description": "添加最新当前条目的时间。名单为空时为 `null`。" }, "created_at": { "type": "string", "format": "date-time", "description": "名单创建时间。" }, "updated_at": { "type": "string", "format": "date-time", "description": "名单最后更新时间。" } } }, "ComplianceListEntry": { "type": "object", "description": "列表中的一个值。", "required": [ "uuid", "value", "display_label", "comment", "added_by", "reference_session_id", "reference_session_number", "reference_session_type", "reference_object_uuid", "metadata", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "条目标识符。在“删除列表条目”中用作 `entry_uuid`。" }, "value": { "type": "string", "description": "列入名单的值：E.164 格式的电话号码、邮箱地址、证件号码、IP 地址或 CIDR 范围、设备指纹、钱包地址、银行账户、ISO 3166-1 alpha-3 国家/地区代码、`vendor_data`、`key` 名单上的任意字符串，或人脸名单上已存储人脸的 UUID。除电话号码和国家/地区代码外，您发送的值均以小写形式存储。匹配不区分大小写。" }, "display_label": { "type": "string", "nullable": true, "maxLength": 512, "description": "便于人类阅读的标签。当您未提供时，Didit 会为从会话中获取的条目自动填充该标签（例如持有人姓名和证件号码）。" }, "comment": { "type": "string", "description": "自由文本备注。未设置时为空字符串。" }, "added_by": { "type": "string", "nullable": true, "description": "添加此条目的主体：`api`（API 密钥）、控制台用户的邮箱地址或 `console`、`system` 或 `migration`（Didit 创建的条目），或者 `rule`（交易或监控规则操作）。" }, "reference_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "该条目来源的验证会话。如果条目是按值添加的，则为 `null`。" }, "reference_session_number": { "type": "integer", "nullable": true, "description": "控制台中显示的该会话在应用范围内的编号。" }, "reference_session_type": { "type": "string", "nullable": true, "enum": [ "kyc", "kyb", null ], "description": "个人验证会话为 `kyc`，企业验证会话为 `kyb`，不存在会话时为 `null`。" }, "reference_object_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "该条目代表的记录：从会话中读取的人脸、证件、电话或邮箱记录，通过“向列表上传人脸”创建的人脸，或您发送的 UUID（例如交易 UUID 或用户的 `didit_internal_id`）。" }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true, "description": "额外上下文。包含 Didit 设置的键（在此列出）并合并您在创建条目时发送的任何 `metadata`，按存储原样返回。无内容时为 `null`。", "properties": { "reference_image_url": { "type": "string", "description": "人脸条目：短期有效的签名 URL，每次调用都会重新签发；对于没有 `media: read` 权限的作用域 API 密钥为 `null`。当没有图像属于该条目时不存在。" }, "front_image_url": { "type": "string", "description": "包含证件正面图像的证件条目：短期有效签名 URL，每次调用都会重新签发；对于缺少 `media: read` 权限的有作用域 API 密钥，该值为 `null`。" }, "full_name": { "type": "string", "description": "从会话中提取的证件条目：持有人姓名。" }, "issuing_state": { "type": "string", "description": "从会话中提取的证件条目：ISO 3166-1 alpha-3 签发国家/地区。" }, "document_type": { "type": "string", "description": "从会话中提取的证件条目：证件类型代码，例如 `P`、`ID` 或 `DL`。" }, "region": { "type": "string", "description": "从会话中提取的证件条目：地方签发证件的签发州或省份，不适用时为空。不会由“将会话条目添加到黑名单”操作设置此项。" }, "document_number": { "type": "string", "description": "从会话中提取的证件条目：证件号码。" }, "face_image_source": { "type": "string", "enum": [ "front_image_camera_front", "back_image_camera_front" ], "description": "取自证件拍摄自拍照的人脸条目：具体是哪张自拍照。对于活体检测人脸则不存在。" }, "reference_node_id": { "type": "string", "nullable": true, "description": "取自证件拍摄自拍照的人脸条目：该自拍照来源的身份证件验证节点。" }, "fingerprint_tier": { "type": "string", "nullable": true, "enum": [ "persistent_id", "composite_hash", "legacy_fp", "unknown", null ], "description": "从会话中获取的设备指纹条目：指纹的派生方式。`persistent_id` 用于标识单个设备；同一型号的设备可能会共享 `composite_hash` 和 `legacy_fp`。" }, "sandbox": { "type": "boolean", "description": "在沙盒应用中上传的人脸条目上为 `true`；此类条目不会匹配任何内容。" }, "reference_type": { "type": "string", "enum": [ "transaction", "vendor_user", "vendor_business" ], "description": "由您设置：`reference_object_uuid` 所指向的内容，以便控制台能够反向链接到该对象。" }, "reference_id": { "type": "string", "description": "由您设置：源记录的标识符。" } } }, "created_at": { "type": "string", "format": "date-time", "description": "条目添加的时间。" } } }, "BlocklistedItem": { "type": "object", "description": "验证会话中的一个黑名单人脸、身份证件、电话号码或邮箱地址。不适用于该项目 `type` 的字段为 `null`。", "required": [ "type", "session_id", "session_number", "blocklisted_at", "face_image", "document_type", "document_number", "front_image", "phone_number", "country_code", "email" ], "properties": { "type": { "type": "string", "enum": [ "face", "document", "phone", "email" ], "description": "被列入黑名单的内容。" }, "session_id": { "type": "string", "format": "uuid", "description": "该项所属的验证会话。" }, "session_number": { "type": "integer", "nullable": true, "description": "控制台中显示的该会话在应用范围内的编号。" }, "blocklisted_at": { "type": "string", "format": "date-time", "description": "该项最后被列入黑名单的时间。" }, "face_image": { "type": "string", "nullable": true, "description": "人脸条目：短期有效的签名 URL，每次调用都会重新签发；对于没有 `media: read` 权限的作用域 API 密钥为 `null`。当未存储参考图像时也为 `null`。" }, "document_type": { "type": "string", "nullable": true, "description": "证件条目：证件类型代码，例如 `P`（护照）、`ID`（国民身份证）、`DL`（驾照）或 `RP`（居留许可）。" }, "document_number": { "type": "string", "nullable": true, "description": "证件条目：证件号码，若证件无证件号码则为个人号码。" }, "front_image": { "type": "string", "nullable": true, "description": "证件条目：证件正面图像，短期有效签名 URL，每次调用都会重新签发；对于缺少 `media: read` 权限的有作用域 API 密钥，该值为 `null`。" }, "phone_number": { "type": "string", "nullable": true, "description": "电话条目：E.164 格式的电话号码。" }, "country_code": { "type": "string", "nullable": true, "description": "电话条目：该号码的 ISO 3166-1 alpha-2 国家/地区。" }, "email": { "type": "string", "nullable": true, "description": "邮箱项：邮箱地址。" } } }, "TransactionNote": { "type": "object", "description": "受监控交易的审核时间线上的一条备注。", "required": [ "uuid", "note", "actor_email", "actor_name", "metadata", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "备注标识符。" }, "note": { "type": "string", "description": "纯文本备注内容。" }, "actor_email": { "type": "string", "format": "email", "nullable": true, "description": "撰写备注或更改状态的 Console 用户的邮箱。通过 API 密钥创建的备注以及 Didit 自动添加的备注为 `null`。" }, "actor_name": { "type": "string", "nullable": true, "description": "Console 用户的显示名称（若未设置姓名则为其邮箱）。对于 Didit 自动添加的备注，显示为 `Rule Engine`。对于使用 API 密钥创建的备注，为 `null`。" }, "metadata": { "type": "object", "description": "区分不同的备注类型。通过 API 或控制台写入的备注包含 `mentioned_emails`。在控制台中执行的状态变更包含 `type: status_change` 以及 `previous_status`、`new_status`、`reason_code` 和 `reason_label`。Didit 添加的备注包含 `source`：规则的 `add_note` 操作对应 `rule_action`（附带 `rule_uuid`），而创建用户操作验证会话出现问题时则对应 `remediation_session`。", "properties": { "mentioned_emails": { "type": "array", "items": { "type": "string", "format": "email" }, "description": "被提及的组织成员，已转为小写并去重。未提及任何人时为空。" }, "type": { "type": "string", "enum": [ "status_change" ], "description": "在记录 Console 中进行的状态变更的备注中存在。" }, "previous_status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "变更前的状态。" }, "new_status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "变更后的状态。" }, "reason_code": { "type": "string", "nullable": true, "description": "随变更一起提供的原因代码。" }, "reason_label": { "type": "string", "nullable": true, "description": "随变更一起提供的原因标签。" }, "source": { "type": "string", "enum": [ "rule_action", "remediation_session" ], "description": "在 Didit 自动添加的备注中存在。" }, "rule_uuid": { "type": "string", "format": "uuid", "description": "其 `add_note` 操作写入了该备注的规则（带有 `source: rule_action`）。" } } }, "created_at": { "type": "string", "format": "date-time", "description": "备注存储的时间。" } } }, "TransactionSummary": { "type": "object", "description": "受监控交易的摘要，为 `GET /v3/transactions/` 列出的结构。使用 `uuid` 调用 `GET /v3/transactions/{transaction_id}/` 可获取相关方、警报和规则运行情况。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Didit 交易 UUID。在交易 endpoint 上将其用作 `{transaction_id}`。" }, "transaction_number": { "type": "integer", "nullable": true, "description": "控制台中显示的应用范围内序号。" }, "txn_id": { "type": "string", "nullable": true, "description": "您在创建调用中提供的自身标识符。每个应用唯一。" }, "transaction_type": { "type": "string", "description": "存储的类别：`finance`、`kyc`、`travelRule`、`userPlatformEvent`、`gamblingBet`、`gamblingLimitChange`、`gamblingBonusChange` 或 `auditTrailEvent`。" }, "action_type": { "type": "string", "description": "类别内的子类型，例如 `withdrawal`。" }, "status": { "type": "string", "enum": [ "APPROVED", "IN_REVIEW", "DECLINED", "AWAITING_USER" ], "description": "当前监控裁决结果。" }, "source": { "type": "string", "enum": [ "LIVE", "IMPORTED" ], "description": "提交用于监控的交易为 `LIVE`，历史导入的交易为 `IMPORTED`。" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "相对于主体的方向。" }, "amount": { "type": "string", "description": "去除末尾零的十进制字符串形式的金额（最多 18 位小数）。" }, "currency": { "type": "string", "description": "`amount` 的货币代码或加密资产符号。" }, "currency_type": { "type": "string", "nullable": true, "description": "已知时为 `fiat` 或 `crypto`。" }, "preferred_currency_amount": { "type": "string", "nullable": true, "description": "`amount` 在汇率可用时折算为应用的首选货币。" }, "preferred_currency_code": { "type": "string", "nullable": true, "description": "`preferred_currency_amount` 的货币。" }, "payment_details": { "type": "string", "nullable": true, "description": "自由文本付款参考号。" }, "txn_date": { "type": "string", "format": "date-time", "description": "交易发生的时间。" }, "created_at": { "type": "string", "format": "date-time", "description": "Didit 记录的时间。" }, "score": { "type": "integer", "description": "风险评分。数值越高风险越大。" }, "severity": { "type": "string", "nullable": true, "enum": [ "UNKNOWN", "LOW", "MEDIUM", "HIGH", "CRITICAL", null ], "description": "风险严重程度，在被设置之前为 `null`。" }, "decision_reason_code": { "type": "string", "nullable": true, "description": "当前 `status` 的机器可读原因。" }, "decision_reason_label": { "type": "string", "nullable": true, "description": "`decision_reason_code` 的便于人类阅读的标签。" }, "tags": { "type": "array", "description": "交易中的标签。", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "color": { "type": "string", "description": "十六进制颜色，例如 `#F59E0B`。" }, "description": { "type": "string", "nullable": true }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "Didit 预设或自定义标签。" } } } }, "subject_name": { "type": "string", "nullable": true, "description": "`APPLICANT` 方的姓名。" }, "subject_vendor_data": { "type": "string", "nullable": true, "description": "您针对申请人的 `vendor_data`。" }, "subject_type": { "type": "string", "nullable": true, "enum": [ "user", "business", null ], "description": "申请人是否关联到某个 Didit 用户或企业；若均未关联则为 `null`。" }, "subject_uuid": { "type": "string", "format": "uuid", "nullable": true, "description": "申请人关联的 Didit 用户或企业的 UUID。" }, "subject_country": { "type": "string", "nullable": true, "description": "申请人的国家/地区代码。" }, "counterparty_name": { "type": "string", "nullable": true, "description": "`COUNTERPARTY` 方的姓名（若有）。" }, "counterparty_vendor_data": { "type": "string", "nullable": true, "description": "您针对交易对手的 `vendor_data`。" }, "counterparty_country": { "type": "string", "nullable": true, "description": "交易对手的国家/地区代码。" }, "assigned_to_name": { "type": "string", "nullable": true, "description": "分配给该交易的 Console 审核员姓名。" }, "travel_rule_status": { "type": "string", "nullable": true, "description": "交易的 Travel Rule 转账状态，若无则为 `null`。" }, "application_id": { "type": "string", "format": "uuid", "description": "拥有该交易的应用。" }, "application_name": { "type": "string", "nullable": true, "description": "该应用的名称。" }, "organization_id": { "type": "string", "format": "uuid", "description": "拥有该应用的组织。" }, "organization_name": { "type": "string", "nullable": true, "description": "该组织的名称。" } } }, "ApplicationAnalyticsDataPoint": { "type": "object", "description": "单日的会话计数，按创建日期（UTC）划分。每个计数反映会话的当前状态。上一周期的数据点至少包含必填字段。", "required": [ "rounded_date", "total", "approved", "declined", "canceled", "pending" ], "properties": { "rounded_date": { "type": "string", "format": "date", "description": "日期，`YYYY-MM-DD`。" }, "total": { "type": "integer", "description": "当天创建的会话。" }, "approved": { "type": "integer", "description": "其中，状态为 `Approved` 或 `Kyc Expired` 的会话。" }, "declined": { "type": "integer", "description": "状态为 `Declined` 的会话。" }, "canceled": { "type": "integer", "description": "状态为 `Expired` 或 `Abandoned` 的会话。" }, "pending": { "type": "integer", "description": "状态为 `Not Started`、`In Progress` 或 `In Review` 的会话。" }, "in_review": { "type": "integer", "description": "状态为 `In Review` 的会话。" }, "expired": { "type": "integer", "description": "状态为 `Expired` 的会话。" }, "abandoned": { "type": "integer", "description": "状态为 `Abandoned` 的会话。" }, "in_progress": { "type": "integer", "description": "状态为 `In Progress` 的会话。" }, "not_started": { "type": "integer", "description": "状态为 `Not Started` 的会话。" }, "manually_approved": { "type": "integer", "description": "在工作流给出其他结论后，审核员予以通过的会话。" }, "manually_declined": { "type": "integer", "description": "在工作流给出其他结论后，审核员予以拒绝的会话。" } } }, "ApplicationAnalyticsRequestBreakdown": { "type": "object", "description": "该时间范围内的状态总计。上一周期的细分至少包含必填字段。", "required": [ "total_approved", "total_in_review", "total_declined", "total_canceled", "total_pending" ], "properties": { "total_approved": { "type": "integer", "description": "状态为 `Approved` 或 `Kyc Expired` 的会话。" }, "total_in_review": { "type": "integer", "description": "状态为 `In Review` 的会话。" }, "total_declined": { "type": "integer", "description": "状态为 `Declined` 的会话。" }, "total_canceled": { "type": "integer", "description": "状态为 `Expired` 或 `Abandoned` 的会话。" }, "total_pending": { "type": "integer", "description": "状态为 `Not Started`、`In Progress` 或 `In Review` 的会话（包含 `total_in_review`）。" }, "total_expired": { "type": "integer", "description": "状态为 `Expired` 的会话。" }, "total_abandoned": { "type": "integer", "description": "状态为 `Abandoned` 的会话。" }, "total_in_progress": { "type": "integer", "description": "状态为 `In Progress` 的会话。" }, "total_not_started": { "type": "integer", "description": "状态为 `Not Started` 的会话。" }, "total_manually_approved": { "type": "integer", "description": "已被审核员批准。" }, "total_manually_declined": { "type": "integer", "description": "已被审核员拒绝。" } } }, "ApplicationAnalyticsCountryCount": { "type": "object", "properties": { "country": { "type": "string", "description": "国家/地区名称。" }, "country_code": { "type": "string", "description": "两字母国家/地区代码。" }, "session_count": { "type": "integer", "description": "来自该国家/地区的会话。" } } }, "ApplicationAnalyticsLocationStats": { "type": "object", "properties": { "ip_countries": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsCountryCount" }, "description": "用户 IP 地址所属的国家/地区，按会话数降序排列。" }, "countries": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsCountryCount" }, "description": "与 `ip_countries` 相同的列表。" }, "id_countries": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsCountryCount" }, "description": "已验证身份证件的签发国家/地区，按会话数从多到少排序。" }, "conversion_by_country": { "type": "array", "description": "按证件签发国家/地区划分：已完成的会话（已通过、已拒绝或审核中）以及其中已通过的数量。已完成最多的排在最前。", "items": { "type": "object", "properties": { "country": { "type": "string" }, "country_code": { "type": "string" }, "finished": { "type": "integer" }, "approved": { "type": "integer" } } } }, "cities": { "type": "array", "description": "最多 100 个 IP 城市，按会话数从多到少排序。", "items": { "type": "object", "properties": { "location": { "type": "string", "description": "`City, Country`。" }, "session_count": { "type": "integer" }, "latitude": { "type": "number", "nullable": true }, "longitude": { "type": "number", "nullable": true } } } } } }, "ApplicationAnalyticsDemographicStats": { "type": "object", "properties": { "age_distribution": { "type": "object", "description": "来自身份证件的按年龄段划分的会话数。无数据时为空。", "properties": { "under_18": { "type": "integer" }, "18_24": { "type": "integer" }, "25_34": { "type": "integer" }, "35_44": { "type": "integer" }, "45_64": { "type": "integer" }, "65_plus": { "type": "integer" } }, "additionalProperties": { "type": "integer" } }, "gender_distribution": { "type": "object", "description": "按证件性别代码（`M`、`F` 或 `U`，未知）划分的会话数。", "additionalProperties": { "type": "integer" } } } }, "ApplicationAnalyticsDeviceDetails": { "type": "object", "description": "各项的前五名，会话数最多的排在前面。", "properties": { "device_models": { "type": "array", "description": "设备品牌：`Apple`、`Android`、`LG`，其余所有归类为 `Other`。", "items": { "type": "object", "properties": { "device": { "type": "string" }, "count": { "type": "integer" } } } }, "browsers": { "type": "array", "description": "浏览器：`Chrome`、`Safari`、`Didit App`、`Firefox`，其他所有归为 `Other`。", "items": { "type": "object", "properties": { "browser": { "type": "string" }, "count": { "type": "integer" } } } }, "operating_systems": { "type": "array", "description": "操作系统。", "items": { "type": "object", "properties": { "os": { "type": "string" }, "count": { "type": "integer" } } } } } }, "ApplicationAnalyticsWorkflowFunnel": { "type": "object", "description": "按工作流 ID 划分。`total` 为在该工作流上启动的会话数；`steps` 统计进入各个步骤的会话数（`OCR`、`LIVENESS`、`FACE_MATCH`、`AML`、`POA`、`PHONE`、`EMAIL`、`NFC`、`DATABASE_VALIDATION`、`QUESTIONNAIRE`、`IP_ANALYSIS`、`AGE_ESTIMATION`、`KYB_REGISTRY`、`KYB_DOCUMENTS`、`KYB_KEY_PEOPLE`）。进入步骤并不代表通过该步骤。", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "steps": { "type": "object", "additionalProperties": { "type": "object", "properties": { "reached": { "type": "integer" } } } } } } }, "ApplicationAnalyticsVerificationTimeStats": { "type": "object", "description": "用户进行验证所花费的活跃时间，忽略闲置间隔。无数据时为空对象。", "properties": { "overall_avg_seconds": { "type": "number", "description": "每次会话平均值，保留一位小数。" }, "overall_count": { "type": "integer", "description": "已测量的会话。" }, "per_feature": { "type": "object", "description": "按功能键划分，例如 `OCR` 或 `LIVENESS`。", "additionalProperties": { "type": "object", "properties": { "avg_seconds": { "type": "number" }, "total_seconds": { "type": "number" }, "count": { "type": "integer" } } } }, "per_sub_step": { "type": "object", "description": "按功能划分，然后按子步骤划分，例如 `front_id_photo`。", "additionalProperties": { "type": "object", "additionalProperties": { "type": "object", "properties": { "avg_seconds": { "type": "number" }, "total_seconds": { "type": "number" }, "count": { "type": "integer" } } } } } } }, "ApplicationAnalyticsResubmissionStats": { "type": "object", "properties": { "first_pass": { "type": "integer", "description": "未重新提交过的已结束会话。" }, "second": { "type": "integer", "description": "重新提交过一次的已结束会话。" }, "third_plus": { "type": "integer", "description": "重新提交过两次或以上的已结束会话。" }, "abandoned": { "type": "integer", "description": "已放弃的会话。" } } }, "ApplicationAnalyticsOriginalStatusStats": { "type": "object", "description": "工作流的自动判定结果，在任何审核员更改之前。", "properties": { "approved": { "type": "integer" }, "in_review": { "type": "integer" }, "declined": { "type": "integer" } } }, "ApplicationAnalyticsWarningStats": { "type": "object", "description": "按功能键划分（`ID_VERIFICATION`、`LIVENESS`、`FACEMATCH`、`AML`、`PROOF_OF_ADDRESS`、`PHONE`、`EMAIL`、`NFC`、`LOCATION`、`DATABASE_VALIDATION`、`QUESTIONNAIRE` 以及 KYB 功能）。`total` 为进入该功能的会话数；`risks` 统计各警告代码和等级对应的会话数。", "additionalProperties": { "type": "object", "properties": { "total": { "type": "integer" }, "risks": { "type": "object", "additionalProperties": { "type": "object", "properties": { "error": { "type": "integer" }, "warning": { "type": "integer" }, "information": { "type": "integer" } } } } } } }, "ApplicationAnalyticsDemographicPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "周期键：遵循 `grouping_mode`，按天为 `YYYY-MM-DD`，按周为周一对应的日期，按月为 `YYYY-MM`。" }, "age_distribution": { "type": "object", "additionalProperties": { "type": "integer" } }, "gender_distribution": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "ApplicationAnalyticsDevicePoint": { "type": "object", "properties": { "date": { "type": "string", "description": "周期键：遵循 `grouping_mode`，按天为 `YYYY-MM-DD`，按周为周一对应的日期，按月为 `YYYY-MM`。" }, "devices": { "type": "object", "additionalProperties": { "type": "integer" } }, "browsers": { "type": "object", "additionalProperties": { "type": "integer" } }, "operating_systems": { "type": "object", "additionalProperties": { "type": "integer" } } } }, "ApplicationAnalyticsVerificationTimePoint": { "type": "object", "properties": { "date": { "type": "string", "description": "周期键：遵循 `grouping_mode`，按天为 `YYYY-MM-DD`，按周为周一对应的日期，按月为 `YYYY-MM`。" }, "overall_avg": { "type": "number", "description": "每次会话平均活跃秒数。" }, "per_feature": { "type": "object", "description": "每项功能平均活跃秒数。", "additionalProperties": { "type": "number" } } } }, "ApplicationAnalyticsResubmissionPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "周期键：遵循 `grouping_mode`，按天为 `YYYY-MM-DD`，按周为周一对应的日期，按月为 `YYYY-MM`。" }, "first_pass": { "type": "integer" }, "second": { "type": "integer" }, "third_plus": { "type": "integer" }, "abandoned": { "type": "integer" } } }, "ApplicationAnalyticsOriginalStatusPoint": { "type": "object", "properties": { "date": { "type": "string", "description": "周期键：遵循 `grouping_mode`，按天为 `YYYY-MM-DD`，按周为周一对应的日期，按月为 `YYYY-MM`。" }, "approved": { "type": "integer" }, "in_review": { "type": "integer" }, "declined": { "type": "integer" } } }, "ApplicationAnalyticsSummary": { "type": "object", "description": "用户验证（KYC）摘要，在既未发送 `scope` 也未发送 `widget_keys` 时返回。", "required": [ "data_points", "request_breakdown", "previous_data_points", "previous_request_breakdown", "conversion_rate", "location_stats", "demographic_stats", "device_details", "workflow_funnel_stats", "verification_time_stats", "resubmission_stats", "warning_stats", "original_status_stats", "grouping_mode", "demographic_time_series", "device_time_series", "verification_time_time_series", "resubmission_time_series", "original_status_time_series" ], "properties": { "data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" }, "description": "每天一个数据点，从该范围内第一个有会话的日期到 `end_date`。无论 `grouping_mode` 为何，始终按天计算。" }, "request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "previous_data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" }, "description": "紧邻 `start_date` 之前相同长度时间段的每日积分。" }, "previous_request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "conversion_rate": { "type": "number", "nullable": true, "description": "`total_approved / (total_approved + total_declined + total_in_review) x 100`，保留一位小数。没有已完成项时为 `null`。" }, "location_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsLocationStats" }, "demographic_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicStats" }, "device_details": { "$ref": "#/components/schemas/ApplicationAnalyticsDeviceDetails" }, "workflow_funnel_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWorkflowFunnel" }, "verification_time_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimeStats" }, "resubmission_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionStats" }, "warning_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWarningStats" }, "original_status_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusStats" }, "grouping_mode": { "type": "string", "enum": [ "day", "week", "month" ], "description": "`*_time_series` 列表的分组方式：最长 14 天按 `day` 分组，最长 90 天按 `week` 分组，超过则按 `month` 分组。从该范围内包含会话的第一天开始计算。" }, "demographic_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicPoint" } }, "device_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDevicePoint" } }, "verification_time_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimePoint" } }, "resubmission_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionPoint" } }, "original_status_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusPoint" } } } }, "ApplicationAnalyticsWidget": { "type": "object", "description": "一个仪表板小组件。每个小组件都包含 `kind` 和 `title`；其他字段取决于 `kind`。会话小组件复用汇总对象（`data_points`、`request_breakdown`、`workflow_funnel_stats` 等）；列表小组件将其条目放入 `items`；交易指标使用 `value`。", "required": [ "kind", "title" ], "properties": { "kind": { "type": "string", "enum": [ "sessions_volume", "workflow_funnel", "average_verification_time", "country_distribution", "warning_insights", "conversion_rate", "conversion_by_country", "resubmission_insights", "original_status_distribution", "database_validation_coverage", "database_validation_latency", "demographics", "device_details", "horizontal_bar", "kyb_registry_coverage", "kyb_registry_data_completeness", "metric", "time_series", "breakdown", "status_time_series", "leaderboard", "histogram" ], "description": "小组件类型。" }, "title": { "type": "string", "description": "显示标题，例如 `Verification volume`。" }, "grouping_mode": { "type": "string", "enum": [ "day", "week", "month" ], "description": "`*_time_series` 列表的分组方式：最长 14 天按 `day` 分组，最长 90 天按 `week` 分组，超过则按 `month` 分组。从该范围内包含会话的第一天开始计算。" }, "data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" } }, "request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "previous_data_points": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDataPoint" } }, "previous_request_breakdown": { "$ref": "#/components/schemas/ApplicationAnalyticsRequestBreakdown" }, "conversion_rate": { "type": "number", "nullable": true }, "workflow_funnel_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWorkflowFunnel" }, "verification_time_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimeStats" }, "verification_time_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsVerificationTimePoint" } }, "warning_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsWarningStats" }, "resubmission_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionStats" }, "resubmission_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsResubmissionPoint" } }, "original_status_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusStats" }, "original_status_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsOriginalStatusPoint" } }, "demographic_stats": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicStats" }, "demographic_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDemographicPoint" } }, "device_details": { "$ref": "#/components/schemas/ApplicationAnalyticsDeviceDetails" }, "device_time_series": { "type": "array", "items": { "$ref": "#/components/schemas/ApplicationAnalyticsDevicePoint" } }, "items": { "type": "array", "description": "列表组件的条目。`country_distribution`（KYC）：`country`、`country_code`、`session_count`。`conversion_by_country`：`country`、`country_code`、`finished`、`approved`。`time_series`：`date`、`value`。`status_time_series`：`date`、`approved`、`declined`、`flagged`。`breakdown`：带有 `count` 和 `volume` 的 `transaction_type` 或 `action_type`，或 `tag_id`、`tag_name`、`count`。`leaderboard`：`rule_title`、`trigger_count` 或 `assignee`、`handled_count`、`average_processing_seconds`，均附带 `approved_percentage`、`declined_percentage`、`flagged_percentage`。`histogram`：`score`、`count`。", "items": { "type": "object", "additionalProperties": {} } }, "previous_items": { "type": "array", "description": "`start_date` 之前相同长度时间段的交易时间序列。", "items": { "type": "object", "additionalProperties": {} } }, "value": { "type": "number", "description": "`metric` 小组件：该范围的数值。" }, "currency": { "type": "string", "nullable": true, "description": "仅限交易量与交易金额小部件：应用的默认交易货币。" }, "thresholds": { "type": "object", "description": "`histogram` 小组件：应用的审核与拒绝分数阈值。", "properties": { "review": { "type": "integer" }, "decline": { "type": "integer" } } }, "search": { "type": "object", "description": "`kyb_registry_coverage` 小组件：公司登记查询总量。", "properties": { "searches_total": { "type": "integer" }, "searches_with_no_candidates": { "type": "integer" } } } } }, "ApplicationAnalyticsWidgetResponse": { "type": "object", "description": "仪表板微件，在发送 `scope` 或 `widget_keys` 时返回。", "required": [ "scope", "available_widget_keys", "requested_widget_keys", "widgets" ], "properties": { "scope": { "type": "string", "enum": [ "home", "kyc", "kyb", "transactions" ], "description": "仪表板标签页。" }, "available_widget_keys": { "type": "array", "items": { "type": "string" }, "description": "此作用域接受的每个小组件密钥。" }, "requested_widget_keys": { "type": "array", "items": { "type": "string" }, "description": "按顺序返回的小组件键：您的有效 `widget_keys`，或作用域的默认值。" }, "widgets": { "type": "object", "description": "按小部件键划分，顺序与 `requested_widget_keys` 一致。", "additionalProperties": { "$ref": "#/components/schemas/ApplicationAnalyticsWidget" } } } }, "ApplicationAnalyticsToday": { "type": "object", "description": "今天按本地小时划分的验证量与上周同工作日对比。", "required": [ "time_zone", "date", "current_hour", "previous_date", "hours", "previous_hours", "total", "previous_total_so_far", "outcomes" ], "properties": { "time_zone": { "type": "string", "description": "日期及其时间所处的 IANA 时区。", "example": "Europe/Madrid" }, "date": { "type": "string", "format": "date", "description": "该时区下的今天。", "example": "2026-10-30" }, "current_hour": { "type": "integer", "minimum": 0, "maximum": 23, "description": "当前的本地小时数。", "example": 14 }, "previous_date": { "type": "string", "format": "date", "description": "对比基准日：一周前的同一个工作日/周几。", "example": "2026-10-23" }, "hours": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 24, "maxItems": 24, "description": "今日自 00:00 起按本地时间每小时创建的验证数。尚未到来的小时数为 0。" }, "previous_hours": { "type": "array", "items": { "type": "integer", "minimum": 0 }, "minItems": 24, "maxItems": 24, "description": "对比日自 00:00 起按本地时间每小时创建的验证数。" }, "total": { "type": "integer", "minimum": 0, "description": "今日截至目前创建的验证数。", "example": 165 }, "previous_total_so_far": { "type": "integer", "minimum": 0, "description": "对比日截至相同本地时间所创建的验证数。", "example": 151 }, "outcomes": { "type": "object", "description": "在今天的验证中，当前已通过、等待人工审核以及已拒绝的数量。其余尚未完成。", "required": [ "approved", "in_review", "declined" ], "properties": { "approved": { "type": "integer", "minimum": 0 }, "in_review": { "type": "integer", "minimum": 0 }, "declined": { "type": "integer", "minimum": 0 } } } } }, "WebhookConfigDestination": { "type": "object", "description": "Webhook 配置中列出的 Webhook 目标，不包含投递指标。`GET /v3/webhook/destinations/{destination_uuid}/` 会附加其投递摘要。", "required": [ "uuid", "label", "url", "enabled", "webhook_version", "secret_shared_key", "subscribed_events", "created_at", "updated_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "目标 ID。" }, "label": { "type": "string", "maxLength": 255, "description": "易于阅读的名称。" }, "url": { "type": "string", "format": "uri", "maxLength": 2000, "description": "Didit 发送事件通知的 HTTPS endpoint。" }, "enabled": { "type": "boolean", "description": "`false` 会暂停向此目标投递。" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "发送至该目标的 payload 版本。" }, "secret_shared_key": { "type": "string", "description": "此目标的签名密钥（43 字符的 URL 安全 token）。请使用发送该 Webhook 的目标的密钥来验证每个 Webhook。使用 API 密钥调用的调用方始终会接收完整密钥；没有 `read:webhooks` 权限的控制台用户将收到空字符串。" }, "subscribed_events": { "type": "array", "uniqueItems": true, "description": "投递至此目标的事件类型。如果目标创建时未指定事件，则为空，在此情况下它不会接收任何内容。", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "WebhookConfig": { "type": "object", "description": "应用级 Webhook 配置、保留策略和数字身份（Digital ID）钱包返回主机，以及所有 Webhook 目标。", "required": [ "webhook_url", "webhook_version", "secret_shared_key", "capture_method", "data_retention_months", "face_retention_policy", "face_retention_days", "available_events", "allowed_return_hosts", "endpoints" ], "properties": { "webhook_url": { "type": "string", "format": "uri", "nullable": true, "description": "应用级（旧版）Webhook URL。Didit 仅在应用没有已启用的目标时才向其发送事件，且仅发送 `status.updated` 和 `data.updated`。每次创建、更新或删除目标时，都会将其设置为最早启用的目标的 URL；若无已启用的目标，则设置为 `null`。" }, "webhook_version": { "type": "string", "enum": [ "v1", "v2", "v3" ], "description": "传统 `webhook_url` 的 payload 版本。每个目标都有其独立的 `webhook_version`。" }, "secret_shared_key": { "type": "string", "description": "应用级签名密钥（43 字符的 URL 安全 token）。它仅对投递到旧版 `webhook_url` 的事件进行签名；每个目标则使用各自的 `secret_shared_key` 进行签名。通过 API 密钥调用的调用方始终会完整接收该密钥；没有 `read:webhooks` 权限的控制台用户将收到空字符串。" }, "capture_method": { "type": "string", "enum": [ "MOBILE", "MOBILE_AND_DESKTOP" ], "description": "旧版应用设置。验证流程不会读取它：采集选项按工作流进行配置。" }, "data_retention_months": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 120, "description": "自动删除窗口。在此月数以前（一个月按 30 天计算）创建的用户验证会话将被自动删除，且该删除不可逆。`null` 表示会话绝不会被自动删除。参见[数据保留](https://docs.didit.me/zh/console/data-retention)。" }, "face_retention_policy": { "type": "string", "enum": [ "delete_with_session", "retain_until_user_deleted" ], "description": "当会话被删除时，对该会话的人脸特征向量的处理方式。`delete_with_session`（默认）会随会话一同将其删除。`retain_until_user_deleted` 为自选的[生物特征模板保留](https://docs.didit.me/zh/console/data-retention#生物特征模板保留)：与用户关联的不含图像的生物特征模板会被单独管理，直至其数据保留期结束、用户被删除或您主动清除它。" }, "face_retention_days": { "type": "integer", "nullable": true, "minimum": 1, "maximum": 3650, "description": "在 `retain_until_user_deleted` 策略下生物特征模板的保留期（以天为单位）。设置该策略时必填。" }, "biometric_consent_mode": { "type": "string", "enum": [ "auto", "always", "never" ], "description": "托管流程和原生 SDK 何时在人脸采集前向当事人请求明确的生物识别同意。`auto`（默认）仅在适用触发条件时请求：当事人声明的州、当事人的 IP 或身份证件签发地位于伊利诺伊州、德克萨斯州或科罗拉多州，或者当事人看似位于美国境内且所在州未知。`always` 会向工作流中需要采集人脸的每个人请求。`never` 则从不显示该步骤，由您在拍摄自拍照前自行收集同意。每次更改都会记录在审计日志中。请参阅[生物识别同意](https://docs.didit.me/zh/getting-started/biometric-consent)。" }, "available_events": { "type": "array", "description": "目标可以订阅的每种事件类型，附带显示标签。", "items": { "type": "object", "required": [ "value", "label" ], "properties": { "value": { "$ref": "#/components/schemas/WebhookEvent" }, "label": { "type": "string", "description": "显示标签，例如 `Session status updated`。" } } } }, "allowed_return_hosts": { "type": "array", "maxItems": 20, "description": "独立数字身份钱包验证可通过其 `return_url` 将用户送回的主机名（精确匹配，仅限 HTTPS）。您的白标域名也始终被允许。请参阅[注册您的返回目标](https://docs.didit.me/zh/standalone-apis/digital-id-wallets#注册返回目标)。", "items": { "type": "string", "maxLength": 253 } }, "endpoints": { "type": "array", "description": "该应用的每个 Webhook 目标，按时间正序排列，每个目标均附带其签名密钥。此处为只读：使用 `/v3/webhook/destinations/` 系列 endpoint 管理目标。", "items": { "$ref": "#/components/schemas/WebhookConfigDestination" } }, "allowed_domains": { "type": "array", "maxItems": 50, "items": { "type": "string", "maxLength": 300 }, "description": "托管验证流程可以嵌入并可通过会话回调将用户重定向回的源（Origin，例如 `https://app.example.com`；`http` 仅适用于 `localhost`）。服务器到服务器的调用不受影响。空列表表示无限制。Didit 会将每个源以小写形式存储，且不包含默认端口。无效条目将导致 `allowed_domains` 验证失败并返回 `400`。", "example": [ "https://app.example.com" ] } } }, "WebhookDestinationDelivery": { "type": "object", "description": "向 Webhook 目标发送的一次投递尝试。事件的首次发送、每次自动重试以及每次重新发送均作为独立的投递记录。", "required": [ "uuid", "session_id", "request_url", "response_status", "response_time_ms", "status", "webhook_type", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "投递 ID，用于获取详情和重新发送调用。" }, "session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "该事件涉及的用户验证会话。对于企业会话、用户、企业、交易、Travel Rule 和工作流事件为 `null`。" }, "request_url": { "type": "string", "format": "uri", "nullable": true, "description": "投递发送的目标 URL：生成事件时目标的 URL。" }, "response_status": { "type": "integer", "nullable": true, "description": "您的 endpoint 返回的 HTTP 状态码。在投递已排队且尚未尝试时为 `null`。未收到 HTTP 响应时，Didit 会记录自身的状态码：您的 endpoint 未在 5 秒内响应记录为 `504`，连接失败记录为 `503`，因 URL 不安全而被拒绝（例如私有或内部地址）记录为 `400`，其他任何请求错误记录为 `404`。`400` 或更高视为投递失败。" }, "response_time_ms": { "type": "integer", "nullable": true, "minimum": 0, "description": "尝试所花费的时间，以毫秒为单位。投递处于队列中时为 `null`。" }, "status": { "type": "string", "nullable": true, "description": "事件生成时报告的状态：会话事件对应会话状态（例如 `Approved` 或 `In Review`），用户和企业事件对应个人或公司的状态，交易事件对应交易状态。对于不携带状态的事件为 `null`。" }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "created_at": { "type": "string", "format": "date-time", "description": "投递创建的时间。" } } }, "WebhookDestinationDeliveryDetail": { "type": "object", "description": "向 Webhook 目标发送的一次投递尝试，包含 Didit 发送的确切请求头和请求体。", "required": [ "uuid", "session_id", "request_url", "response_status", "response_time_ms", "status", "webhook_type", "created_at", "request_header", "request_body" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "投递 ID，用于获取详情和重新发送调用。" }, "session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "该事件涉及的用户验证会话。对于企业会话、用户、企业、交易、Travel Rule 和工作流事件为 `null`。" }, "request_url": { "type": "string", "format": "uri", "nullable": true, "description": "投递发送的目标 URL：生成事件时目标的 URL。" }, "response_status": { "type": "integer", "nullable": true, "description": "您的 endpoint 返回的 HTTP 状态码。在投递已排队且尚未尝试时为 `null`。未收到 HTTP 响应时，Didit 会记录自身的状态码：您的 endpoint 未在 5 秒内响应记录为 `504`，连接失败记录为 `503`，因 URL 不安全而被拒绝（例如私有或内部地址）记录为 `400`，其他任何请求错误记录为 `404`。`400` 或更高视为投递失败。" }, "response_time_ms": { "type": "integer", "nullable": true, "minimum": 0, "description": "尝试所花费的时间，以毫秒为单位。投递处于队列中时为 `null`。" }, "status": { "type": "string", "nullable": true, "description": "事件生成时报告的状态：会话事件对应会话状态（例如 `Approved` 或 `In Review`），用户和企业事件对应个人或公司的状态，交易事件对应交易状态。对于不携带状态的事件为 `null`。" }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "created_at": { "type": "string", "format": "date-time", "description": "投递创建的时间。" }, "request_header": { "type": "string", "description": "Didit 发送的请求头的 JSON 文本（字符串）：`Content-Type`、`X-Signature`、`X-Signature-V2`、`X-Signature-Simple`、`X-Timestamp` 和 `User-Agent`。请使用 JSON 解析器进行解析。其中包含签名，绝不会包含签名密钥。" }, "request_body": { "type": "string", "description": "Didit 发送的准确 payload 的 JSON 文本（字符串），键已排序，包括 `event_id` 和 `timestamp`。请使用 JSON 解析器进行解析；参见 [Payload 结构](https://docs.didit.me/zh/integration/webhooks#payload-结构)。对于没有 `media: read` 权限的作用域密钥，其中的媒体 URL 为 `null`；没有 `sessions: write` 权限时，会话 token 和托管验证链接为 `null`。以此方式修改的请求体将不再与其签名匹配。Didit 不会记录您的 endpoint 返回的响应体。" } } }, "SessionWebhookDelivery": { "type": "object", "description": "为验证会话记录的一次 Webhook 投递尝试，包含 Didit 发送的原始请求头和请求体。", "required": [ "uuid", "session_id", "request_url", "response_status", "status", "webhook_type", "request_header", "request_body", "created_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "投递 ID。将其用作 `{webhook_uuid}` 以获取或重新发送此投递。" }, "session_id": { "type": "string", "format": "uuid", "description": "投递记录所属的会话（路径中的会话）。" }, "request_url": { "type": "string", "format": "uri", "nullable": true, "description": "投递发送的目标 URL。" }, "response_status": { "type": "integer", "nullable": true, "description": "您的 endpoint 返回的 HTTP 状态码。在投递已排队且尚未尝试时为 `null`。未收到 HTTP 响应时，Didit 会记录自身的状态码：您的 endpoint 未在 5 秒内响应记录为 `504`，连接失败记录为 `503`，因 URL 不安全而被拒绝（例如私有或内部地址）记录为 `400`，其他任何请求错误记录为 `404`。`400` 或更高视为投递失败。" }, "status": { "type": "string", "nullable": true, "description": "生成事件时的会话状态，例如 `In Progress`、`Approved` 或 `Declined`。" }, "webhook_type": { "$ref": "#/components/schemas/WebhookEvent" }, "request_header": { "type": "string", "description": "Didit 发送的请求头的 JSON 文本（字符串）：`Content-Type`、`X-Signature`、`X-Signature-V2`、`X-Signature-Simple`、`X-Timestamp` 和 `User-Agent`。请使用 JSON 解析器进行解析。其中包含签名，绝不会包含签名密钥。" }, "request_body": { "type": "string", "description": "Didit 发送的准确 payload 的 JSON 文本（字符串），键已排序，包括 `event_id` 和 `timestamp`。请使用 JSON 解析器进行解析；参见 [Payload 结构](https://docs.didit.me/zh/integration/webhooks#payload-结构)。对于没有 `media: read` 权限的作用域密钥，其中的媒体 URL 为 `null`；没有 `sessions: write` 权限时，会话 token 和托管验证链接为 `null`。以此方式修改的请求体将不再与其签名匹配。Didit 不会记录您的 endpoint 返回的响应体。" }, "created_at": { "type": "string", "format": "date-time", "description": "投递创建的时间。" } } }, "SessionEvent": { "type": "object", "description": "验证会话事件时间线中的一个条目。", "required": [ "uuid", "event_type", "created_at", "component", "feature_step", "step", "details", "ip_address", "user_agent", "device_info", "file_url", "sent_at" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "事件标识符。" }, "event_type": { "type": "string", "enum": [ "SESSION_CREATED", "SESSION_COMPLETED", "SESSION_STATUS_CHANGED", "LINK_OPENED", "FORM_SUBMITTED", "BUTTON_CLICKED", "FILE_UPLOADED", "ATTEMPT_FAILED", "FEATURE_STEP_CHANGED", "STEP_RENDERED", "NOTE_ADDED", "MANUAL_REVIEW_STARTED", "WORKFLOW_BRANCH_EVALUATED", "WORKFLOW_STATUS_NODE_REACHED", "LOG" ], "description": "发生的情况。由设备在托管流程或 SDK 期间报告：`LINK_OPENED`、`STEP_RENDERED`、`BUTTON_CLICKED`、`FORM_SUBMITTED`、`FILE_UPLOADED`、`ATTEMPT_FAILED` 和 `LOG`（调试）。由服务器记录：`SESSION_CREATED`、`SESSION_STATUS_CHANGED`（`details.old_status`、`details.current_status`）、`FEATURE_STEP_CHANGED`（`details.old_feature_step`、`details.current_feature_step`）、`WORKFLOW_BRANCH_EVALUATED` 和 `WORKFLOW_STATUS_NODE_REACHED`（工作流路由追踪）。`SESSION_COMPLETED`、`NOTE_ADDED` 和 `MANUAL_REVIEW_STARTED` 可能会出现在较早的会话中。" }, "created_at": { "type": "string", "format": "date-time", "description": "Didit 存储该事件的时间。事件为异步存储，通常在 `sent_at` 之后数秒完成。" }, "component": { "type": "string", "nullable": true, "description": "报告该事件的 UI 组件（仅限设备事件）。" }, "feature_step": { "type": "string", "nullable": true, "enum": [ "OCR", "OCR_BACK", "NFC", "AML", "FACE", "LIVENESS", "FACE_MATCH", "IP_ANALYSIS", "AGE_ESTIMATION", "PROOF_OF_ADDRESS", "PHONE_VERIFICATION", "EMAIL_VERIFICATION", "FACE_SEARCH", "DATABASE_VALIDATION", "QUESTIONNAIRE", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "DOCUMENT_AI", "GEOLOCATION", null ], "description": "事件发生时会话所处的验证功能。" }, "step": { "type": "string", "nullable": true, "description": "功能中的页面，例如 `DOCUMENT_CAPTURE_FRONT` 或 `FACE_PASSIVE_LIVENESS`。" }, "details": { "type": "object", "nullable": true, "additionalProperties": true, "description": "特定事件的数据。键取决于 `event_type`。" }, "ip_address": { "type": "string", "nullable": true, "description": "设备报告事件时所在的 IP 地址。对于服务器记录的事件为 `null`。" }, "user_agent": { "type": "string", "nullable": true, "description": "设备的 User-Agent。对于服务器记录的事件为 `null`。" }, "device_info": { "type": "object", "nullable": true, "additionalProperties": true, "description": "SDK 或浏览器报告的设备详情。" }, "file_url": { "type": "string", "format": "uri", "nullable": true, "description": "事件所附加文件（例如捕获的图像）的短期预签名链接。不存在时为 `null`，对于不具备 `media: read` 权限的受限作用域 API 密钥始终为 `null`。" }, "sent_at": { "type": "integer", "format": "int64", "description": "事件发生的时间，为 Unix 毫秒时间戳。结果按此排序。" } } }, "AMLDatasetSourceFreshness": { "type": "object", "description": "某类 AML 数据集的新鲜度。", "required": [ "last_updated_at", "oldest_updated_at", "dataset_count", "dated_dataset_count" ], "properties": { "last_updated_at": { "type": "string", "format": "date-time", "description": "该系列中任何数据集的最新更新。" }, "oldest_updated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "时效性界限：该组中的每个数据集都至少达到此时效性。当该组中至少有一个数据集未报告更新日期时为 `null`，因为此时界限未知。" }, "dataset_count": { "type": "integer", "description": "该系列中的数据集数量。" }, "dated_dataset_count": { "type": "integer", "description": "报告了更新日期的此类数据集数量。" } } }, "AMLDatasetFreshness": { "type": "object", "description": "筛查运行时 AML 数据集的新鲜度。日期绝非估算值。", "required": [ "captured_at", "provider", "catalog_version", "sources" ], "properties": { "captured_at": { "type": "string", "format": "date-time", "description": "Didit 读取此新鲜度所依据的数据集目录的时间。" }, "provider": { "type": "string", "description": "AML 数据源的不透明标识符。请将其视为不透明字符串；请勿基于其进行分支判断。", "example": "aml_data_source" }, "catalog_version": { "type": "string", "nullable": true, "description": "数据集目录的版本标识符（如果源报告了该标识符）。" }, "sources": { "type": "object", "description": "各类数据集的新鲜度。若某个类别的所有数据集均未报告更新日期，则该类别会被省略，而不是填充为 `null`。", "properties": { "sanctions": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" }, "pep": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" }, "warnings": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" }, "adverse_media": { "$ref": "#/components/schemas/AMLDatasetSourceFreshness" } } } } }, "AMLScreeningRun": { "type": "object", "description": "AML 检查中已完成的一次持续监控重新筛查。", "required": [ "uuid", "run_id", "completed_at", "started_at", "outcome", "trigger", "provider", "status", "score", "total_hits", "new_hits", "entities_screened", "dataset_freshness" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "此筛查运行的标识符。" }, "run_id": { "type": "string", "format": "uuid", "description": "该筛查所属的监控运行批次。在同一次运行中筛查的每次验证共享该值。" }, "completed_at": { "type": "string", "format": "date-time", "description": "该主体重新筛查完成的时间。结果按此排序，最新的排在最前。" }, "started_at": { "type": "string", "format": "date-time", "description": "本次重新筛查所属的监控批次开始的时间。" }, "outcome": { "type": "string", "enum": [ "NO_CHANGE", "CHANGED", "FAILED" ], "description": "`NO_CHANGE`：已完成且结果未变动。`CHANGED`：已完成且评分、状态、命中次数或命中项发生了变动。`FAILED`：该主体没有可用结果，因此检查保持原样。" }, "trigger": { "type": "string", "enum": [ "ONGOING_MONITORING" ], "description": "触发筛查的原因。目前始终为 `ONGOING_MONITORING`。" }, "provider": { "type": "string", "description": "做出响应的 AML 数据源的不透明标识符。请将其视为不透明字符串；请勿基于其进行分支判断。", "example": "aml_data_source" }, "status": { "type": "string", "nullable": true, "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested", null ], "description": "本次运行后该检查所处的 AML 检查状态。" }, "score": { "type": "number", "format": "float", "nullable": true, "minimum": 0, "maximum": 100, "description": "本次运行后该检查所处的 AML 评分。" }, "total_hits": { "type": "integer", "nullable": true, "description": "本次运行使核验保持的命中项数量。" }, "new_hits": { "type": "integer", "nullable": true, "description": "本次运行发现的、核验此前没有的新命中项数量。未发现新内容时为 `0`；运行失败或在此计数存在之前记录时为 `null`。" }, "entities_screened": { "type": "integer", "minimum": 0, "maximum": 1, "description": "本次运行为该验证筛查的实体数量：主体已筛查时为 `1`，运行失败时为 `0`。" }, "dataset_freshness": { "allOf": [ { "$ref": "#/components/schemas/AMLDatasetFreshness" } ], "nullable": true, "description": "本次运行所依据的数据集新鲜度，若无可用的日期则为 `null`。" } } }, "KYBKeyPeopleParty": { "type": "object", "description": "企业验证（KYB）会话的关键人员关联方及其子验证。同一关联方会出现在企业会话决策的 `key_people_checks[].submitted.parties[]` 中。", "required": [ "uuid", "entity_type", "source", "name", "is_active", "is_skipped", "requires_verification", "roles", "kyc_session_deleted", "kyb_sub_session_deleted" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "当事方标识符。" }, "entity_type": { "type": "string", "enum": [ "person", "company" ], "description": "该主体是个人还是公司。" }, "source": { "type": "string", "enum": [ "REGISTRY", "USER" ], "description": "`REGISTRY`：从公司登记获取。`USER`：在关键人员页面中输入。" }, "name": { "type": "string", "description": "参与方的显示名称。" }, "first_name": { "type": "string", "nullable": true, "description": "名（个人）。" }, "last_name": { "type": "string", "nullable": true, "description": "姓氏（自然人）。" }, "company_name": { "type": "string", "nullable": true, "description": "企业名称（企业主体）。" }, "registration_number": { "type": "string", "nullable": true, "description": "企业注册号（企业主体）。" }, "email": { "type": "string", "format": "email", "nullable": true, "description": "验证链接发送至的邮箱。" }, "nationality": { "type": "string", "nullable": true, "description": "个人为国籍，企业为注册成立国家/地区。" }, "phone_number": { "type": "string", "nullable": true, "description": "为该主体采集的电话号码。" }, "date_of_birth": { "type": "string", "format": "date", "nullable": true, "description": "出生日期（自然人）。" }, "position": { "type": "string", "nullable": true, "description": "自由文本职位（个人）。" }, "custom_fields": { "type": "object", "additionalProperties": true, "description": "为该方收集的工作流定义自定义字段，按字段键索引。" }, "is_active": { "type": "boolean", "description": "该主体是否处于活跃状态。" }, "is_skipped": { "type": "boolean", "description": "该主体是否免于验证。重新生成将清除此状态。" }, "requires_verification": { "type": "boolean", "description": "角色和股权结构规则是否要求对此主体进行验证。" }, "roles": { "type": "array", "description": "当事方在公司中担任的角色。", "items": { "type": "object", "required": [ "role", "ownership_percent", "voting_percent" ], "properties": { "role": { "type": "string", "enum": [ "director", "non_executive_director", "secretary", "chairman", "ubo", "shareholder", "representative", "founder", "legal_advisor", "authorized_signatory", "trustee", "beneficiary", "settlor", "protector", "company_officer", "investor", "other" ], "description": "角色代码。" }, "ownership_percent": { "type": "number", "nullable": true, "description": "该角色的持股比例（如已知）。" }, "voting_percent": { "type": "number", "nullable": true, "description": "该角色的投票权百分比（若已知）。" } } } }, "kyc_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "子个人 KYC 会话（个人）。" }, "kyc_session_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User", null ], "description": "子 KYC 会话的状态。已删除的会话保留其被删除时的状态。" }, "kyc_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "子 KYC 会话的托管链接。在没有子会话、子会话已被删除，以及对于不具备 `sessions: write` 作用域的受限 API 密钥时为 `null`。" }, "kyc_session_deleted": { "type": "boolean", "description": "子 KYC 会话已被删除，因此永远无法完成结算。" }, "kyb_sub_session_id": { "type": "string", "format": "uuid", "nullable": true, "description": "子 KYB 会话（企业各方）。" }, "kyb_sub_session_status": { "type": "string", "nullable": true, "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User", null ], "description": "子 KYB 会话的状态。" }, "kyb_sub_session_url": { "type": "string", "format": "uri", "nullable": true, "description": "子 KYB 会话的托管链接，其 `null` 规则与 `kyc_session_url` 相同。" }, "kyb_sub_session_deleted": { "type": "boolean", "description": "对应企业主体的 `kyc_session_deleted`。" }, "verification_workflow_type": { "type": "string", "nullable": true, "enum": [ "kyc", "kyb", "adaptive_age_verification", "biometric_authentication", "address_verification", "questionnaire_verification", "email_verification", "phone_verification", null ], "description": "子会话运行的工作流类型。" }, "verification_workflow_id": { "type": "string", "format": "uuid", "nullable": true, "description": "子会话运行的工作流。" }, "verification_workflow_label": { "type": "string", "nullable": true, "description": "该工作流的标签。" }, "verification_workflow_features": { "type": "array", "nullable": true, "description": "子会话工作流的功能及其当前状态。", "items": { "type": "object", "required": [ "feature", "status" ], "properties": { "feature": { "type": "string", "description": "功能代码，例如 `ID_VERIFICATION` 或 `LIVENESS`。" }, "status": { "type": "string", "description": "功能状态，运行前为 `Not Finished`。" } } } }, "didit_internal_id": { "type": "string", "format": "uuid", "nullable": true, "description": "已验证人员的 Didit 标识符（一旦获知）。" } } }, "TravelRuleDelivery": { "type": "object", "description": "该转账应发送给对方的最新消息所处的状态。Didit 会在创建或修改转账的请求返回后联系交易对手，因此该对象显示该消息是否成功送达：已排队（queued）、正在发送（being sent）、出错后等待重试（waiting to be retried after an error）、已投递（delivered）或已失败（failed）。网络仍可能恢复的故障（超时未响应、连接失败、HTTP `408`、`429` 或 `5xx`）会在 30 秒、2 分钟、10 分钟、30 分钟和 1 小时后再次重试。当首条消息（`kind: SEND`）彻底失败（因为网络拒绝或第 6 次尝试也失败）时，转账状态将变为 `COUNTERPARTY_VASP_NOT_REACHABLE`，并在其 `timeline` 中记录 `last_error`；任何其他彻底失败的消息也会在 `timeline` 中标明。转账的 `status` 始终是交易本身的真实事实来源。", "required": [ "kind", "status", "rail", "attempts", "last_error", "next_attempt_at", "delivered_at" ], "properties": { "kind": { "type": "string", "enum": [ "SEND", "ANSWER", "TXID", "CANCEL", "POLL" ], "description": "该消息携带的内容。`SEND`：发送给交易对手的首条转账消息（出站；在发送时选择通道）。`ANSWER`：您对发起请求的网络做出的接受或拒绝（入站）。`TXID`：完成转账后的链上交易哈希。`CANCEL`：取消操作（在您取消转账之后）。`POLL`：向支持状态查询的网络发起的查询请求，在转账等待交易对手期间每 5 分钟重复一次。" }, "status": { "type": "string", "enum": [ "QUEUED", "SENDING", "RETRYING", "DELIVERED", "FAILED" ], "description": "`QUEUED`：等待发送。`SENDING`：正在尝试发送。`RETRYING`：尝试失败，下一次尝试将在 `next_attempt_at` 运行。`DELIVERED`：对方已接收消息。`FAILED`：对方拒绝接收，或最后一次尝试失败。" }, "rail": { "type": "string", "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "" ], "description": "承载该消息的通道。在 Didit 为第一条消息选定通道之前为空。" }, "attempts": { "type": "integer", "minimum": 0, "description": "截至目前针对该消息进行的尝试次数。非状态轮询的消息最多尝试 6 次。" }, "last_error": { "type": "string", "description": "上次尝试遇到的失败类型，无失败时为 `\"\"`：例如 `email undeliverable`、`trp identity endpoint unreachable` 或 `trp transfer inquiry delivery failed`。它从不包含交易对手自身的回复，后者保留在转账的 `timeline` 中。\n当 GTR 回复错误时，会包含其自身的状态码和消息。绝不包含响应体。", "example": "email undeliverable" }, "next_attempt_at": { "type": "string", "format": "date-time", "nullable": true, "description": "当消息处于 `QUEUED` 或 `RETRYING` 状态时，下一次尝试运行的时间。" }, "delivered_at": { "type": "string", "format": "date-time", "nullable": true, "description": "对方接收消息的时间。" } } }, "TravelRuleDiscoveryStep": { "type": "object", "description": "Didit 为出站转账执行的交易对手发现中的一个步骤，按执行顺序排列。第一个指定了具有可用路由的 VASP 的步骤将终止链条。", "properties": { "step": { "type": "string", "enum": [ "internal_address_book", "wallet_attribution", "network_lookup", "customer_hint", "end_user" ], "description": "`internal_address_book`：已证明拥有目标钱包控制权的另一位 Didit 客户。`wallet_attribution`：钱包的区块链分析归属。`network_lookup`：能够辨明持有该地址之 VASP 的网络。`customer_hint`：您在 `beneficiary_data` 中发送的 VASP 名称、LEI 或司法管辖区。`end_user`：终端用户（或您）选择的交易对手，或选择交易对手的请求。" }, "outcome": { "type": "string", "enum": [ "match", "miss", "skipped" ], "description": "`match`：该步骤指明了交易对手。`miss`：已运行但未找到。`skipped`：无法运行，`reason` 说明了原因。" }, "reason": { "type": "string", "description": "机器可读的原因，匹配时为 `\"\"`：`no_proven_internal_wallet`、`attribution_disabled`、`already_attributed`、`no_attributed_entity`、`directory_match_no_route`、`gtr_address_lookup_runs_on_dispatch`、`no_membership`、`network_switched_off`、`no_network_address_lookup`、`no_directory_match`、`awaiting_end_user` 或 `picked_member_without_proven_wallet`。" }, "vasp": { "type": "string", "format": "uuid", "nullable": true, "description": "步骤中指定的目录 VASP（若有指定）。" }, "rail": { "type": "string", "nullable": true, "description": "该步骤找到的、可触达该交易对手的通道。" }, "at": { "type": "string", "format": "date-time" } } }, "TravelRuleNextAction": { "type": "object", "description": "推动处于 `COUNTERPARTY_VASP_NOT_FOUND` 或 `COUNTERPARTY_VASP_NOT_REACHABLE` 状态的转账继续进行的一项操作。请参阅[转账卡住的原因](/zh/transaction-monitoring/travel-rule#为什么转账会卡住)。", "properties": { "action": { "type": "string", "enum": [ "select_counterparty_vasp", "declare_self_hosted", "add_vasp_hint", "update_compliance_email", "resend" ], "description": "`select_counterparty_vasp`：终端用户在钱包所有权组件中选择目标 VASP，或者您通过 PATCH 传入 `action=beneficiary_vasp`。`declare_self_hosted`：终端用户在组件中声明该钱包为自托管钱包。`add_vasp_hint`：通过 VASP 名称、LEI 或 Travel Address（例如目标钱包地址簿条目上的 `travel_address`）告知 Didit 交易对手是谁，然后重新发送。`update_compliance_email` 和 `resend` 是 `PATCH /v3/transactions/{transaction_id}/travel-rule/` 的 `action` 取值：再次提供交易对手的合规邮箱，并重新运行路由。" }, "url": { "type": "string", "format": "uri", "description": "钱包所有权小组件链接，当转账拥有开启的小组件会话时，出现在 `select_counterparty_vasp` 和 `declare_self_hosted` 状态下。" } }, "required": [ "action" ] }, "TransactionTravelRule": { "type": "object", "description": "交易的 Travel Rule 转账，正如 `GET /v3/transactions/{transaction_id}/`、`POST /v3/transactions/` 的 `201` 以及 `GET /v3/transactions/` 的每行所返回的内容。`direction`、`rail`、`counterparty_vasp`、`delivery`、`discovery`、`reason` 和 `next_actions` 的结构与 `PATCH /v3/transactions/{transaction_id}/travel-rule/` 相同，因此读取一次交易即可了解其转账受阻的原因以及如何继续推进。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "protocol": { "type": "string", "nullable": true }, "required": { "type": "boolean" }, "obligations_count": { "type": "integer" }, "originator_data": { "type": "object", "description": "汇款人方。对于入账转账，在所有权确认之前，交易对手的值将被掩码遮盖。" }, "beneficiary_data": { "type": "object", "description": "收款人方。对于入账转账，在确认所有权之前，交易对手的值将被遮蔽。" }, "name_match": { "type": "object", "nullable": true, "description": "决定转账的姓名比对结果（分数和严格程度）。在运行比对前为 null。比对的姓名与当事方一同脱敏。" }, "data_match": { "$ref": "#/components/schemas/TravelRuleDataMatch" }, "mismatched_fields": { "type": "array", "items": { "type": "string" }, "description": "`data_match.mismatched_fields` 的快捷方式。无差异时为空。" }, "data_unmasked": { "$ref": "#/components/schemas/TravelRuleDataUnmasked" }, "data_masked": { "type": "boolean", "description": "在此响应中交易对手的个人数据被遮蔽时为 True。" }, "metadata": { "type": "object" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ], "description": "此笔转账属于交易的哪一方。" }, "rail": { "type": "string", "nullable": true, "description": "转账所走的通道：`INTERNAL`、`TRP`、`GTR`、`TRUST`、`VERIFYVASP`、`SYGNA` 或 `EMAIL`（在沙盒应用上且由 Didit Test VASP 应答时为 `TEST_VASP`），在选定通道前为 `null`。" }, "counterparty_vasp": { "type": "object", "nullable": true, "properties": { "name": { "type": "string" }, "lei": { "type": "string" }, "dd_score": { "type": "integer", "description": "尽职调查评分，范围为 0 到 100，分数越高越好。分值范围与 VASP 名录相同。" }, "dd_score_breakdown": { "type": "object", "description": "对 dd_score 的各组件贡献度，每个组件一个对象（对应 VASP 目录中的 jurisdiction、verification、protocol、lei、history、essentials、responsiveness），每个组件均包含 {points, max, reason, detail}。在交易对手完成评估前为 {}。", "additionalProperties": { "type": "object", "properties": { "points": { "type": "number", "description": "为该组件分配的点数。" }, "max": { "type": "integer", "description": "该组件可赋予的最大分值。" }, "reason": { "type": "string", "description": "组件判定结果的机器可读代码。" }, "detail": { "type": "string", "description": "易于阅读的积分授予原因。" } } } }, "dd_assessed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "尽职调查评估上次运行的时间。在对交易对手进行评估之前为 Null。" } }, "description": "交易对手的名录条目；若转账未关联任何条目，则为 `null`。" }, "delivery": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TravelRuleDelivery" } ], "description": "该转账应发送给另一方的最新消息。若无需发送任何消息（例如金额低于 `threshold_amount` 或针对声明的自托管钱包），则为 `null`。" }, "discovery": { "type": "array", "description": "Didit 查找交易对手的方式，每个运行的步骤对应一个条目。未运行发现流程时为空，例如对于入站转账。", "items": { "$ref": "#/components/schemas/TravelRuleDiscoveryStep" } }, "reason": { "type": "string", "description": "`COUNTERPARTY_VASP_NOT_FOUND` 或 `COUNTERPARTY_VASP_NOT_REACHABLE` 转账受阻的原因；任何其他状态下为 `\"\"`。首先由失败的投递决定（仅适用于 `COUNTERPARTY_VASP_NOT_REACHABLE`）：`email_undeliverable`（邮件服务商拒绝了合规邮件，且没有可尝试的地址：发送时、发送提醒时或后续报告为永久退信）或 `delivery_failed`（负责投递的通道彻底失败：网络通道拒绝了消息或重试次数耗尽、`TRP` 身份主机未应答，或交易对手的 `TRP` 主机不接受查询）。否则由 `discovery` 追踪记录决定：`awaiting_end_user`（没有任何步骤指定 Didit 可触达的交易对手）、`directory_match_no_route`（某步骤指定了名录中的 VASP，但该 VASP 没有可用路由）、`picked_member_without_proven_wallet`（终端用户选择的 Didit 客户尚未证明对该钱包的控制权），或者在追踪记录未提供其他原因时的 `no_directory_match`。重新发送后转账会继续推进，因此该原因将被清除。参见[转账受阻的原因](/zh/transaction-monitoring/travel-rule#为什么转账会卡住)。" }, "next_actions": { "type": "array", "description": "推进转账的操作；除 `COUNTERPARTY_VASP_NOT_FOUND` 或 `COUNTERPARTY_VASP_NOT_REACHABLE` 之外的任何状态均返回 `[]`。`email_undeliverable` 提供 `update_compliance_email`，然后提供 `resend`。`delivery_failed` 提供 `resend`。发现原因提供 `select_counterparty_vasp`、`declare_self_hosted`、`add_vasp_hint` 和 `resend`。", "items": { "$ref": "#/components/schemas/TravelRuleNextAction" } }, "chain_details": { "$ref": "#/components/schemas/TravelRuleChainDetails" } } }, "NetworkListCounts": { "type": "object", "description": "列表各视图和过滤选项的网络计数，每个网络只统计一次。仅在 `summary` 不为 `false` 时返回。`scopes` 统计当前应用可见的所有网络。`views` 统计所选 `scope` 内的可见网络。`facets` 统计所选 `scope` 和 `status` 视图中的网络（除非 `status` 包含，否则已忽略的网络会被排除在外）。其他列表过滤器不会改变这些计数。", "properties": { "scopes": { "type": "object", "description": "按产品划分的可见网络。", "properties": { "all": { "type": "integer" }, "identity": { "type": "integer", "description": "所有其他网络。" }, "transactions": { "type": "integer", "description": "成员全为交易各方的网络。" } } }, "views": { "type": "object", "description": "所选 `scope` 内按状态划分的可见网络，外加两个已保存视图。", "properties": { "all": { "type": "integer" }, "active": { "type": "integer" }, "in_review": { "type": "integer" }, "resolved": { "type": "integer" }, "dismissed": { "type": "integer" }, "mine": { "type": "integer", "description": "分配给调用方控制台成员的网络。对于 API 密钥始终为 0。" }, "high_risk": { "type": "integer", "description": "风险评分达到或超过 80 且未被忽略的网络。" } } }, "facets": { "type": "object", "description": "所选 `scope` 和状态视图内各过滤选项的计数。", "properties": { "total": { "type": "integer", "description": "所选 `scope` 和状态视图中的网络。" }, "last_activity_days": { "type": "object", "description": "在过去 7、30 和 90 天内有活动记录的网络，按天数作为键名。", "properties": { "7": { "type": "integer" }, "30": { "type": "integer" }, "90": { "type": "integer" } } }, "risk_min": { "type": "object", "description": "风险评分至少为 50 和至少为 80 的网络，按阈值作为键名。", "properties": { "50": { "type": "integer" }, "80": { "type": "integer" } } }, "signal_types": { "type": "object", "description": "每种类型至少包含一个信号的网络。", "properties": { "ip_address": { "type": "integer" }, "device": { "type": "integer" }, "face": { "type": "integer" }, "document_number": { "type": "integer" }, "phone": { "type": "integer" }, "email": { "type": "integer" }, "address": { "type": "integer" } } }, "priority": { "type": "object", "description": "按优先级划分的网络。`none` 统计没有优先级的网络。", "properties": { "low": { "type": "integer" }, "medium": { "type": "integer" }, "high": { "type": "integer" }, "none": { "type": "integer" } } }, "assignee": { "type": "object", "description": "按受理人划分的网络。", "properties": { "me": { "type": "integer", "description": "分配给发起调用的控制台成员。对于 API 密钥始终为 0。" }, "unassigned": { "type": "integer", "description": "未分配给任何人。" }, "users": { "type": "array", "description": "每个经办人对应一个条目，网络数量最多的排在最前。", "items": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" }, "full_name": { "type": "string", "description": "被分配人的姓名；若未设置姓名，则为其邮箱。" }, "email": { "type": "string" }, "count": { "type": "integer" } } } } } }, "has_case": { "type": "integer", "description": "此应用为其开启案件的网络。" }, "min_size": { "type": "object", "description": "成员数量至少为 10 的网络，按最小规模作为键名。", "properties": { "10": { "type": "integer" } } } } } } }, "NetworkTag": { "type": "object", "description": "您的应用在网络上的标签之一。", "properties": { "uuid": { "type": "string", "format": "uuid", "description": "标签的 UUID，与您作为 `tag_uuid` 传递的值相同。" }, "name": { "type": "string" }, "color": { "type": "string", "description": "十六进制颜色，例如 `#6366F1`。" }, "source": { "type": "string", "enum": [ "didit", "custom" ], "description": "Didit 预设标签为 `didit`，您团队创建的标签为 `custom`。" }, "added_by": { "type": "string", "nullable": true, "description": "添加该标签的 Console 成员邮箱。由 API 密钥添加时为 Null。" }, "added_at": { "type": "string", "format": "date-time" } } }, "NetworkOutcomes": { "type": "object", "description": "网络的人员和企业所处的状态。您可查看的每位成员仅按其最近一次得出决策的验证状态计入一次。交易当事方不计算在内。", "properties": { "approved": { "type": "integer", "description": "最近一次已决策验证为已通过的成员。" }, "declined": { "type": "integer", "description": "最近一次已决策验证为已拒绝的成员。" }, "in_review": { "type": "integer", "description": "最近一次已决策验证处于审核中的成员。" }, "total": { "type": "integer", "description": "拥有至少一次验证（无论是否已决策）的成员。若某个成员的所有验证均未决策（未开始、进行中、已过期或已放弃），则仅计入此处，不计入其他键。" } } }, "NetworkPatternScore": { "type": "object", "description": "在整个网络中，成员的某种数据有多相似。模式并不等同于信号：成员之间没有共享值进行关联。", "properties": { "type": { "type": "string", "enum": [ "background" ], "description": "`background`：遮挡人物后，每对成员自拍照背景的平均相似度。它读取每人最新的自拍照（最多 50 人的最新自拍照），并排除年龄确认会话。它覆盖整个网络，不仅限于您应用的成员。" }, "score": { "type": "number", "nullable": true, "minimum": 0, "maximum": 1, "description": "介于 0 到 1 之间，四舍五入保留 4 位小数。设置了 `reason` 时为 null。" }, "members": { "type": "integer", "nullable": true, "description": "评分比对了多少位成员的自拍照。无法读取或背景显示过少的自拍照不会参与比对。在 `computing` 时为 null；在 `not_enough_selfies` 时为 0 或 1。" }, "reason": { "type": "string", "enum": [ "computing", "not_enough_selfies" ], "nullable": true, "description": "没有评分的原因。`computing`：当前成员的评分正在计算中；请稍后再次读取网络。`not_enough_selfies`：拥有可用自拍照的成员少于两名。存在评分时为 null。" }, "computed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "分数计算完成的时间。处于 `computing` 状态时为 null。" } } }, "NetworkDetailResponse": { "description": "网络详情，以及组织的共享模式、跨组织信号是否适用于该网络、您的应用在网络上的标签、成员结果和模式评分。", "allOf": [ { "$ref": "#/components/schemas/NetworkDetail" }, { "type": "object", "properties": { "sharing_mode": { "type": "string", "enum": [ "off", "private", "global" ], "description": "该组织的跨组织共享模式。仅 `global` 会跨组织比对网络；`private` 和 `off` 则仅保留在组织自身历史记录内。", "example": "global" }, "cross_org_available": { "type": "boolean", "description": "跨组织信号是否适用于该组织。这需要同时具备 Enterprise 套餐和 `global` 共享模式。", "example": true }, "cross_org_unavailable_reason": { "type": "string", "enum": [ "plan", "sharing_mode" ], "nullable": true, "description": "跨组织信号不适用的原因，按此顺序检查。`plan`：无论共享模式为何，组织的套餐均不包含跨组织欺诈网络（需要 Enterprise 套餐）。`sharing_mode`：套餐包含该功能，但共享模式为 `private` 或 `off`。当 `cross_org_available` 为 `true` 时为 Null。", "example": null }, "tags": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTag" }, "description": "您的应用在网络上的标签，按最早优先排序。每个应用只能看到自己的标签。`fraud_tags` 是独立的且保持不变：指网络成员拥有的标签。" }, "outcomes": { "$ref": "#/components/schemas/NetworkOutcomes" }, "patterns": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkPatternScore" }, "description": "整个网络的模式评分。目前包含一项：`background`。" } } } ] }, "NetworkTagRequest": { "type": "object", "required": [ "tag_uuid" ], "properties": { "tag_uuid": { "type": "string", "format": "uuid", "description": "您应用的某个标签的 UUID。" } }, "example": { "tag_uuid": "7c9e6679-7425-40de-944b-e07fc1f90ae7" } }, "NetworkTimeline": { "title": "Default timeline (no contract)", "type": "object", "description": "不带 `contract`：网络自身事件，按时间从旧到新排序，不分页。", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTimelineEvent" } } } }, "NetworkTimelinePage": { "title": "Typed timeline page (contract=2)", "type": "object", "description": "配合 `contract=2`：一页类型化事件，最新的排在最前。", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTypedTimelineEvent" } }, "next_cursor": { "type": "string", "nullable": true, "description": "作为 `cursor` 传入以读取下一页。在最后一页为 null。" } } }, "NetworkTypedTimelineEvent": { "type": "object", "description": "一个具有类型的时间线事件：四个默认字段，加上其 id、Didit 存储它的时间、它所属的成员账户和记录，以及其事件类型的详情块。其他详情块为 null。", "properties": { "id": { "type": "string", "description": "`:`，在时间线内唯一。", "example": "session:3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "event_type": { "type": "string", "enum": [ "network_detected", "signal_observed", "network_active", "network_in_review", "network_resolved", "network_dismissed", "verification_attempt", "transaction", "login", "rule_hit", "case_linked", "note_added" ] }, "occurred_at": { "type": "string", "format": "date-time", "description": "发生时间。" }, "ingested_at": { "type": "string", "format": "date-time", "description": "Didit 存储的时间。" }, "label": { "type": "string", "description": "简短的英文标签，例如 `Verification attempt 2 of 3`。" }, "metadata": { "type": "object", "description": "对于网络自身的事件，为与默认时间线相同的元数据。其他情况为空。" }, "account": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineAccount" } ], "nullable": true, "description": "成员账户。对于网络本身的事件、`case_linked` 和 `note_added`，该值为 null。" }, "source_ref": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineSourceRef" } ], "nullable": true, "description": "源记录。对于网络自身的事件和 `note_added` 为 Null。" }, "verification_attempt": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineAttempt" } ], "nullable": true, "description": "在 `verification_attempt` 事件发生时设置。" }, "transaction": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineTransaction" } ], "nullable": true, "description": "在 `transaction` 事件发生时设置。" }, "login": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineLogin" } ], "nullable": true, "description": "在 `login` 事件发生时设置。" }, "rule_hit": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineRuleHit" } ], "nullable": true, "description": "在 `rule_hit` 事件发生时设置。" }, "case_linked": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineCaseLinked" } ], "nullable": true, "description": "在 `case_linked` 事件发生时设置。" }, "note_added": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineNoteAdded" } ], "nullable": true, "description": "在 `note_added` 事件发生时设置。绝不返回给 API 密钥。" } } }, "NetworkTimelineAccount": { "type": "object", "description": "该事件所属的成员账户。", "properties": { "node_id": { "type": "string", "description": "`:`，其中 kind 为 `vendor_user`、`vendor_business` 或 `transaction_party`。", "example": "vendor_user:3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "node_type": { "type": "string", "enum": [ "account", "business_account", "transaction_party" ] }, "uuid": { "type": "string", "format": "uuid" }, "vendor_data": { "type": "string", "nullable": true }, "display_name": { "type": "string", "nullable": true }, "ownership": { "type": "string", "enum": [ "owned", "organization" ], "description": "当记录属于您调用的应用时为 `owned`（对于控制台成员，则为其被授予权限的应用）。当属于您组织下的另一个应用时为 `organization`。" }, "route": { "$ref": "#/components/schemas/NetworkTimelineRoute" } } }, "NetworkTimelineSourceRef": { "type": "object", "description": "读取该事件所依据的记录。", "properties": { "kind": { "type": "string", "enum": [ "session", "business_session", "transaction", "monitoring_event", "case" ] }, "id": { "type": "string", "format": "uuid" }, "ownership": { "type": "string", "enum": [ "owned", "organization" ], "description": "当记录属于您调用的应用时为 `owned`（对于控制台成员，则为其被授予权限的应用）。当属于您组织下的另一个应用时为 `organization`。" }, "route": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineRoute" } ], "description": "在 `monitoring_event` 和 `case` 中不存在。" } } }, "NetworkTimelineRoute": { "type": "object", "description": "打开记录的位置：其种类、UUID 以及所属的应用。", "properties": { "kind": { "type": "string", "description": "账户为 `user`、`business` 或 `transaction_party`；源记录为 `session`、`business_session` 或 `transaction`。" }, "id": { "type": "string", "format": "uuid" }, "application_id": { "type": "string", "format": "uuid" } } }, "NetworkTimelineAttempt": { "type": "object", "description": "该账户的一个验证会话。", "properties": { "session_id": { "type": "string", "format": "uuid", "description": "会话 UUID，对于企业则为企业会话 UUID。" }, "session_number": { "type": "integer", "nullable": true }, "attempt": { "type": "integer", "description": "此会话在该账户的所有会话中的位置，按创建顺序排列。" }, "attempt_count": { "type": "integer", "description": "该账户拥有的会话数量。" }, "status": { "type": "string", "description": "会话状态，例如 `Approved` 或 `Declined`。" }, "status_changed_at": { "type": "string", "format": "date-time", "nullable": true }, "decline_reasons": { "type": "array", "items": { "$ref": "#/components/schemas/NetworkTimelineDeclineReason" }, "description": "仅适用于已拒绝的会话：其警告列表，按时间从旧到新排序，每个警告仅出现一次。其他情况为空。" } } }, "NetworkTimelineDeclineReason": { "type": "object", "properties": { "risk": { "type": "string", "description": "警告代码。" }, "feature": { "type": "string", "description": "触发该警告的功能。" }, "short_description": { "type": "string" } } }, "NetworkTimelineTransaction": { "type": "object", "description": "成员账户参与的交易，按其交易日期标注日期。", "properties": { "transaction_id": { "type": "string", "format": "uuid" }, "transaction_number": { "type": "integer", "nullable": true }, "transaction_type": { "type": "string" }, "action_type": { "type": "string" }, "amount": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineAmount" } ], "nullable": true, "description": "当交易没有金额时为 null。" }, "status": { "type": "string" }, "decision_reason_code": { "type": "string", "nullable": true }, "decision_reason_label": { "type": "string", "nullable": true }, "party_role": { "type": "string", "description": "账户在交易中的角色：`APPLICANT`、`REMITTER`、`BENEFICIARY` 或 `COUNTERPARTY`。" } } }, "NetworkTimelineAmount": { "type": "object", "properties": { "value": { "type": "string", "description": "字符串形式的十进制金额。" }, "currency": { "type": "string" }, "direction": { "type": "string", "nullable": true } } }, "NetworkTimelineLogin": { "type": "object", "description": "您通过事件 API 为某人发布的登录事件。", "properties": { "action": { "type": "string", "description": "`.`：登录成功对应 `auth.login` 或 `security.login_succeeded`，登录失败对应 `auth.login_failed` 或 `security.login_failed`。" }, "succeeded": { "type": "boolean" }, "status": { "type": "string", "description": "事件的状态。" }, "ip": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineIP" } ], "nullable": true, "description": "当事件没有地址时为 null。" }, "device": { "allOf": [ { "$ref": "#/components/schemas/NetworkTimelineDevice" } ], "nullable": true, "description": "当事件没有设备指纹或上下文时为 null。" }, "is_first_login": { "type": "boolean", "description": "记录中该账户首次成功的登录。" }, "is_new_device": { "type": "boolean", "description": "来自该账户以往成功登录均未出现过的设备的成功登录。首次登录时绝不为 true。" } } }, "NetworkTimelineIP": { "type": "object", "properties": { "address": { "type": "string" }, "country_code": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "connection_type": { "type": "string", "nullable": true, "description": "地址的连接类型标签，为自由文本格式。" }, "is_vpn_or_tor": { "type": "boolean" }, "is_data_center": { "type": "boolean" } } }, "NetworkTimelineDevice": { "type": "object", "properties": { "fingerprint": { "type": "string", "nullable": true }, "label": { "type": "string", "nullable": true, "description": "根据事件的设备上下文构建的易读设备标签。" } } }, "NetworkTimelineRuleHit": { "type": "object", "description": "命中成员交易或事件的已启用规则。不包括测试模式下的命中。", "properties": { "rule_id": { "type": "string", "format": "uuid" }, "rule_title": { "type": "string" }, "rule_category": { "type": "string" }, "rule_source": { "type": "string" }, "severity": { "type": "string", "nullable": true }, "score_delta": { "type": "integer" }, "status_target": { "type": "string", "nullable": true }, "action_summary": { "type": "string", "nullable": true } } }, "NetworkTimelineCaseLinked": { "type": "object", "description": "为您的组织中的网络打开的案件。`source_ref.ownership` 表明它是否属于您调用的应用。", "properties": { "case_id": { "type": "string", "format": "uuid" }, "case_number": { "type": "string", "nullable": true }, "status": { "type": "string" }, "author_email": { "type": "string", "nullable": true }, "author_name": { "type": "string", "nullable": true } } }, "NetworkTimelineNoteAdded": { "type": "object", "description": "留在网络上的备注。不包含备注文本。", "properties": { "note_id": { "type": "string", "format": "uuid" }, "author_email": { "type": "string" } } }, "FeatureStatusOverride": { "type": "object", "description": "通过 `PATCH /v3/session/{sessionId}/features/{nodeId}/update-status/` 对某项检查（功能）状态进行的一次覆盖：它更改了什么、是否已应用或仍在等待用户完成流程、发起者以及原因。", "required": [ "id", "node_id", "feature_type", "feature_model", "previous_status", "new_status", "state", "forced", "reason", "requested_by", "requested_at", "applied_at", "cancelled_at", "cancel_reason" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "覆盖项的标识符。将其传递给取消 endpoint。", "example": "7c9e6679-7425-40de-944b-e07fc1f90ae7" }, "node_id": { "type": "string", "description": "请求指定的工作流节点（对于没有节点的步骤为 `default`）。", "example": "feature_ocr_1" }, "feature_type": { "type": "string", "description": "请求传递的 `feature_type`；若未传递，则为空字符串。", "example": "" }, "feature_model": { "type": "string", "description": "被覆盖的核验类型，例如 `KYC`、`Face`、`AML` 或 `GeolocationCheck`。", "example": "KYC" }, "previous_status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "请求覆盖时该检查的状态。", "example": "In Review" }, "new_status": { "type": "string", "enum": [ "Approved", "Declined", "In Review" ], "description": "覆盖所设置的状态。", "example": "Approved" }, "state": { "type": "string", "enum": [ "applied", "pending_until_flow_finishes", "cancelled" ], "description": "`applied`：检查已获得新状态。`pending_until_flow_finishes`：覆盖设置处于等待状态，并在该人员完成流程时应用。`cancelled`：已等待且从未应用（参见 `cancel_reason`）。", "example": "applied" }, "forced": { "type": "boolean", "description": "当该人员仍在流程中且覆写立即生效时为 `true`。", "example": false }, "reason": { "type": "string", "nullable": true, "description": "随请求发送的 `comment`，或为 `null`。", "example": "Document manually verified by compliance." }, "requested_by": { "type": "object", "nullable": true, "description": "请求覆盖的人员；若未知则为 `null`。", "properties": { "email": { "type": "string", "format": "email", "nullable": true, "description": "Console 用户的邮箱，对于 API 密钥和系统则为 `null`。", "example": "reviewer@example.com" }, "name": { "type": "string", "nullable": true, "description": "请求者的显示名称，或 `null`。", "example": "Alex Reviewer" }, "type": { "type": "string", "enum": [ "CONSOLE_USER", "API_KEY", "SYSTEM" ], "description": "发起请求的主体：控制台用户、API 密钥或 Didit 本身。", "example": "CONSOLE_USER" } } }, "requested_at": { "type": "string", "format": "date-time", "description": "请求覆盖的时间。", "example": "2026-10-13T09:15:00Z" }, "applied_at": { "type": "string", "format": "date-time", "nullable": true, "description": "检查变为新状态的时间，等待中或一旦取消则为 `null`。", "example": "2026-10-13T09:15:00Z" }, "cancelled_at": { "type": "string", "format": "date-time", "nullable": true, "description": "等待中的覆盖被取消的时间，或为 `null`。", "example": null }, "cancel_reason": { "type": "string", "nullable": true, "enum": [ "cancelled_by_reviewer", "replaced", "check_changed", "session_closed", null ], "description": "处于等待状态的覆盖为何从未生效，或为 `null`。`cancelled_by_reviewer`：已通过取消 endpoint 取消。`replaced`：同一项检查上更新的覆盖替换了它。`check_changed`：用户在完成流程之前重新进行了检查。`session_closed`：会话在用户完成之前离开了流程（已放弃、已过期或在流程中做出决策）。", "example": null } } }, "SandboxSimulateRequest": { "type": "object", "description": "强制修改沙盒会话的状态。所有字段均为可选，但 `new_status`、`scenario` 或 `risk` 中必须至少提供一个。", "properties": { "new_status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Abandoned" ], "description": "要设置的状态。如果省略，则默认使用风险案件的默认状态（`risk`，或场景魔法值所携带的第一个风险），否则使用场景的默认状态。", "example": "Declined" }, "comment": { "type": "string", "maxLength": 500, "description": "添加到状态变更所记录活动条目的备注。", "example": "Testing the decline path" }, "scenario": { "type": "string", "maxLength": 100, "description": "来自目录的场景标识（`GET /v1/sandbox/scenarios/`）。它提供默认状态，且在没有 `risk` 的情况下，提供其魔法值携带的警告。未知标识将返回 `400`。", "example": "decline_aml_hit" }, "risk": { "type": "string", "maxLength": 128, "description": "来自目录的风险案例。其警告将被添加到会话中，日志类型遵循 `new_status`。未知值将返回 `400`。", "example": "POSSIBLE_MATCH_FOUND" }, "node_id": { "type": "string", "maxLength": 128, "description": "风险警告所关联的工作流节点。默认为会话的当前节点。", "example": "feature_aml_1" }, "send_webhooks": { "type": "boolean", "default": true, "description": "`true` 会向沙盒应用的目标发送真实状态变更所发送的完全相同的 Webhook：`status.updated`，以及变更所引起的 `user.status.updated` / `user.data.updated`（或 `business.status.updated` / `business.data.updated`）事件（针对订阅了这些事件的目标）。`false` 会更改状态但不会记录或发送任何 Webhook：遗漏 Webhook 恢复机制永远不会重新发送该决策，控制台仍会实时更新，且会话的下一次状态变更将照常发送 Webhook。", "example": true } } }, "SandboxSimulateResponse": { "type": "object", "required": [ "session_id", "previous_status", "status", "scenario", "risk", "send_webhooks" ], "properties": { "session_id": { "type": "string", "format": "uuid", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "previous_status": { "type": "string", "enum": [ "Not Started", "In Progress", "Approved", "Declined", "In Review", "Expired", "Abandoned", "Kyc Expired", "Resubmitted", "Awaiting User" ], "description": "模拟前的会话状态。", "example": "In Progress" }, "status": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Abandoned" ], "description": "模拟设置的状态。", "example": "Declined" }, "scenario": { "type": "string", "nullable": true, "description": "您传入的场景 slug，或为 `null`。", "example": "decline_aml_hit" }, "risk": { "type": "string", "nullable": true, "description": "应用的风险案件（`risk`，或从场景中获取的案件），无案件时为 `null`。", "example": "POSSIBLE_MATCH_FOUND" }, "send_webhooks": { "type": "boolean", "description": "模拟应用的 `send_webhooks` 值。", "example": false } } }, "CaseTeamSummary": { "type": "object", "nullable": true, "description": "负责该案件的审核团队；没有团队负责时为 null。当路由规则将案件分配给其团队之一时，路由系统会对其进行设置。使用 `PATCH .../cases/{case_uuid}/`（`team`）进行修改或清除。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } }, "CaseChecker": { "type": "object", "nullable": true, "description": "被指定批准或拒绝待决决定的成员。仅当双人复核（four-eyes）决议等待指定复核员时设置。在无待决事项、待决决议在复核员队列中等待，以及决议已获批准、被拒绝或因证据变更而退回重新审核后，该值为 null。", "properties": { "member_uuid": { "type": "string", "format": "uuid", "description": "成员的用户 UUID：在您解决案件时作为 `checker` 传入的值。" }, "name": { "type": "string", "nullable": true, "description": "成员的姓名，未知时为 null。" }, "email": { "type": "string", "format": "email" } } }, "ServiceStatusFeed": { "type": "object", "description": "公开服务状态：各项 Didit 服务的状态、整体状态以及正在发生或在过去 7 天内已解决的事件。", "required": [ "status", "updated_at", "services", "incidents" ], "properties": { "status": { "type": "string", "enum": [ "operational", "degraded", "down" ], "description": "所有服务当前状态中的最差状态，仅由正在发生的事件决定。", "example": "degraded" }, "updated_at": { "type": "string", "format": "date-time", "description": "Didit 生成此响应的时间（ISO 8601，UTC）。响应会缓存 30 秒，因此可能最多有 30 秒的延迟。", "example": "2026-10-13T09:41:07.512345Z" }, "services": { "type": "array", "description": "每个服务对应一个条目，始终列出所有服务。", "items": { "$ref": "#/components/schemas/ServiceStatusService" } }, "incidents": { "type": "array", "description": "按 `started_at` 最新的优先排序。包括所有进行中的事件，加上过去 7 天内解决的事件（最多 50 个已解决事件）。若在此期间无事件发生则为空。", "items": { "$ref": "#/components/schemas/ServiceStatusIncident" } } } }, "ServiceStatusService": { "type": "object", "required": [ "key", "name", "status" ], "properties": { "key": { "type": "string", "enum": [ "service_id_verification", "service_liveness_face_match", "service_aml_screening", "service_kyb_registries", "service_database_validation", "service_phone_delivery", "service_email_delivery", "service_transaction_monitoring" ], "description": "稳定的服务密钥。请基于此键进行匹配，切勿基于显示名称。`service_id_verification`：身份证件验证，`service_liveness_face_match`：活体检测与人脸比对，`service_aml_screening`：AML 筛查，`service_kyb_registries`：KYB 注册机构，`service_database_validation`：数据库核验，`service_phone_delivery`：电话验证投递，`service_email_delivery`：邮箱验证投递，`service_transaction_monitoring`：交易监控。", "example": "service_database_validation" }, "name": { "type": "string", "description": "服务的英文显示名称。", "example": "Database validation" }, "status": { "type": "string", "enum": [ "operational", "degraded", "down" ], "description": "当该服务没有正在发生的事件时为 `operational`，否则为其正在发生事件中最严重的状态。", "example": "degraded" } } }, "ServiceStatusIncident": { "type": "object", "required": [ "id", "service", "service_name", "state", "status", "title", "body", "affected", "country_name", "started_at", "resolved_at", "duration_minutes" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "事件 ID。", "example": "3fa85f64-5717-4562-b3fc-2c963f66afa6" }, "service": { "type": "string", "enum": [ "service_id_verification", "service_liveness_face_match", "service_aml_screening", "service_kyb_registries", "service_database_validation", "service_phone_delivery", "service_email_delivery", "service_transaction_monitoring" ], "description": "受影响服务的键（参见 `services[].key`）。", "example": "service_database_validation" }, "service_name": { "type": "string", "description": "受影响服务的英文显示名称。", "example": "Database validation" }, "state": { "type": "string", "enum": [ "degraded", "down" ], "description": "服务受影响的方式。已解决的事件会保留其最后所处的状态。", "example": "degraded" }, "status": { "type": "string", "enum": [ "ongoing", "resolved" ], "description": "在服务恢复前为 `ongoing`，恢复后为 `resolved`。", "example": "ongoing" }, "title": { "type": "string", "description": "英文标题。如需翻译，请根据 `service`、`state` 和 `country_name` 构建您自己的文本。", "example": "Database validation is degraded in Brazil." }, "body": { "type": "string", "description": "英文详情说明行：自何时起核验可能会变慢或失败，或者何时已恢复。", "example": "Checks against Brazil (CPF) may be slow or fail since 08:55 UTC." }, "affected": { "type": "string", "description": "受影响的国家/地区或登记机构，例如 `Brazil (CPF)`。当事件未与特定国家/地区或登记机构关联时为空。", "example": "Brazil (CPF)" }, "country_name": { "type": "string", "description": "受影响的国家/地区，以英文表示。当事件未与特定国家/地区关联时为空。", "example": "Brazil" }, "started_at": { "type": "string", "format": "date-time", "description": "事件开始时间（ISO 8601，UTC）。", "example": "2026-10-13T08:55:00Z" }, "resolved_at": { "type": "string", "format": "date-time", "nullable": true, "description": "服务恢复时间（ISO 8601，UTC）。事件持续期间为 `null`。" }, "duration_minutes": { "type": "integer", "nullable": true, "description": "从 `started_at` 到 `resolved_at` 的整分钟数。事件仍在持续时为 `null`。" } } }, "TravelRuleJoinInvitation": { "type": "object", "description": "在输入任何内容之前，加入页面显示的内容。", "properties": { "email": { "type": "string", "format": "email", "description": "邀请发送的目标地址。" }, "vasp_name": { "type": "string" }, "source": { "type": "string", "description": "邀请的来源，例如 `pickup`。" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "prefill": { "type": "object", "properties": { "vasp_id": { "type": "string", "format": "uuid", "nullable": true }, "legal_name": { "type": "string" }, "lei": { "type": "string" }, "jurisdiction": { "type": "string" }, "domains": { "type": "array", "items": { "type": "string" } } } } } }, "TravelRuleJoinRegisterRequest": { "type": "object", "required": [ "email", "password" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254, "description": "必须是邀请发送至的地址。" }, "password": { "type": "string", "minLength": 8, "maxLength": 128 } } }, "TravelRuleJoinVerifyRequest": { "type": "object", "required": [ "email", "code" ], "properties": { "email": { "type": "string", "format": "email", "maxLength": 254 }, "code": { "type": "string", "minLength": 6, "maxLength": 6, "description": "注册后通过电子邮件发送的 6 位验证码。" } } }, "TravelRuleJoinCredentials": { "type": "object", "description": "新的免费组织及其应用调用 API 所使用的凭据。", "properties": { "organization": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } }, "application": { "type": "object", "properties": { "uuid": { "type": "string", "format": "uuid" } } }, "client_id": { "type": "string" }, "api_key": { "type": "string", "description": "在工作区 endpoint 上作为 `x-api-key` 请求头发送。" } } }, "TravelRuleWorkspaceClaimRequest": { "type": "object", "required": [ "vasp_id" ], "properties": { "vasp_id": { "type": "string", "format": "uuid", "description": "此工作区对应的目录条目。从 `GET /v3/travel-rule/vasps/` 读取 ID。" } } }, "TravelRuleWorkspaceDomainConfirmRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "minLength": 6, "maxLength": 6 } } }, "TravelRuleWorkspaceBillingRequest": { "type": "object", "properties": { "enabled": { "type": "boolean", "default": true, "description": "仅接受 `true`：无法通过 API 重新关闭出站计费。" } } }, "TravelRuleWorkspaceDomainCodeResponse": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "unverified", "code_sent", "verified" ] }, "txt": { "$ref": "#/components/schemas/TravelRuleWorkspaceTxtRecord" } } }, "TravelRuleWorkspaceTxtRecord": { "type": "object", "description": "为 DNS 证明而发布的 TXT 记录。在证明启动前为空。", "properties": { "host": { "type": "string", "example": "didit-tr-verify.example.com" }, "value": { "type": "string" } } }, "TravelRuleWorkspace": { "type": "object", "description": "免费加入的应用所享有的免费 Travel Rule 工作区。", "properties": { "joined_free": { "type": "boolean" }, "work_email": { "type": "string", "format": "email" }, "joined_at": { "type": "string", "format": "date-time", "nullable": true }, "claim": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "unclaimed", "pending_review", "claimed", "rejected" ] }, "proved_by_domain": { "type": "boolean" }, "claimed_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "review_note": { "type": "string" }, "vasp_id": { "type": "string", "format": "uuid", "nullable": true }, "vasp_name": { "type": "string" } } }, "prefill": { "type": "object", "description": "取自目录条目的个人资料值：`vasp_id`、`legal_name`、`lei`、`jurisdiction`、`compliance_email`、`domains`。在发起认领之前不会写入任何内容。" }, "domain": { "type": "object", "properties": { "domain": { "type": "string" }, "status": { "type": "string", "enum": [ "unverified", "code_sent", "verified" ] }, "verified_at": { "type": "string", "format": "date-time", "nullable": true }, "txt": { "$ref": "#/components/schemas/TravelRuleWorkspaceTxtRecord" } } }, "billing_enabled": { "type": "boolean", "description": "接收 Travel Rule 数据是免费的。仅在启用计费后，发送数据才会收取费用。" }, "billing_enabled_at": { "type": "string", "format": "date-time", "nullable": true }, "didit_network": { "type": "object", "description": "Didit 网络中是否列出了此 VASP；如果未列出，则包含其仍未满足的各项条件。" }, "settings": { "$ref": "#/components/schemas/TravelRuleSettingsDetail" } } }, "InvestigatorDecision": { "type": "object", "description": "该项离开调查员队列的方式。`decided_by`、`original_outcome` 和 `overrides` 由接受和覆盖 endpoint 以及报告返回；会话决策的 `investigator` 块包含其他字段。", "properties": { "outcome": { "type": "string", "enum": [ "accepted", "edited", "overridden", "decided_elsewhere", "automated" ], "description": "`accepted` 或 `edited` 采纳了建议（`edited` 包含重写的陈述），`overridden` 采取了其他操作，`decided_elsewhere` 是在报告打开期间在 Investigator 之外做出的决策，`automated` 是 Investigator 自行做出的决策。" }, "action": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "override_category": { "type": "string", "enum": [ "missing_context", "needs_information", "policy_differs", "evidence_misread", "other", "" ], "nullable": true }, "override_reason": { "type": "string", "nullable": true }, "final_status": { "type": "string", "description": "作出决策后该项目的状态。" }, "agreed": { "type": "boolean", "description": "决策是否与建议一致。", "nullable": true }, "decided_at": { "type": "string", "format": "date-time" }, "billed": { "type": "boolean", "description": "该审核已扣费。" }, "decided_by": { "type": "string", "enum": [ "investigator", "member" ] }, "original_outcome": { "type": "object", "description": "Investigator 自行做出的决策，未受后续覆盖修改。对于团队做出的决策，该值为 null。", "properties": { "action": { "type": "string" }, "final_status": { "type": "string" }, "decided_at": { "type": "string", "format": "date-time" } }, "nullable": true }, "overrides": { "type": "array", "description": "调查员自行做出的决策的每次覆盖，按时间正序排列。", "items": { "type": "object", "properties": { "action": { "type": "string" }, "actor_email": { "type": "string", "nullable": true }, "actor_name": { "type": "string", "nullable": true }, "override_category": { "type": "string" }, "override_reason": { "type": "string" }, "previous_status": { "type": "string" }, "final_status": { "type": "string" }, "agreed": { "type": "boolean", "nullable": true }, "overridden_at": { "type": "string", "format": "date-time" } } } } } }, "InvestigatorBlock": { "type": "object", "nullable": true, "description": "该项最新的调查员审核结果，若从未审核过则为 null。由 V3 会话和企业会话决策携带（并通过 `status.updated` Webhook 发送）。", "properties": { "run_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "running", "completed", "failed" ] }, "stage": { "type": "string", "enum": [ "shadow", "live" ] }, "queue": { "type": "string", "enum": [ "kyc", "kyb", "aml", "transactions", "cases" ] }, "is_open": { "type": "boolean" }, "recommendation": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ], "nullable": true }, "recommendation_detail": { "type": "string", "nullable": true }, "confidence": { "type": "string", "enum": [ "high", "moderate", "low" ], "nullable": true }, "summary": { "type": "string", "nullable": true }, "ready_to_accept": { "type": "boolean" }, "prepared_at": { "type": "string", "format": "date-time", "nullable": true }, "automated": { "type": "boolean", "description": "调查员自行做出的决策，即使该决策随后被覆盖。" }, "decided_by": { "type": "string", "enum": [ "investigator", "member" ], "nullable": true }, "decision": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InvestigatorDecision" } ], "type": "object" } } }, "InvestigatorQueueRow": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "session", "business_session", "transaction", "case" ] }, "queue": { "type": "string", "enum": [ "kyc", "kyb", "aml", "transactions", "cases" ] }, "stage": { "type": "string", "enum": [ "shadow", "live" ] }, "subject": { "type": "object", "description": "待审核项目：`id`、`number`、`status`、`name`，以及根据类型包含的 `country`、`workflow`、`vendor_data`、`txn_id`、`amount`、`currency`、`direction`、`title` 或 `priority`。", "additionalProperties": true }, "recommendation": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] }, "recommendation_detail": { "type": "string" }, "confidence": { "type": "string", "enum": [ "high", "moderate", "low" ] }, "summary": { "type": "string" }, "sources_count": { "type": "integer" }, "ready_to_accept": { "type": "boolean" }, "guardrails": { "description": "锁定此项目的防护规则（若有）。" }, "waiting_since": { "type": "string", "format": "date-time", "nullable": true }, "due_at": { "type": "string", "format": "date-time", "nullable": true }, "prepared_at": { "type": "string", "format": "date-time", "nullable": true } } }, "InvestigatorRunDetail": { "allOf": [ { "$ref": "#/components/schemas/InvestigatorQueueRow" }, { "type": "object", "properties": { "status": { "type": "string" }, "is_open": { "type": "boolean" }, "lookups": { "type": "integer", "description": "读取的部分和关联记录数量。" }, "duration_ms": { "type": "integer", "nullable": true }, "agent_version": { "type": "string" }, "prepared_before_opened": { "type": "boolean", "nullable": true }, "report": { "type": "object", "additionalProperties": true, "description": "报告：推理过程、包含判定结果（`ok`、`risk`、`look`、`explained`、`context`）和引用来源的证据点、筛查命中判定（`same`、`not_same`、`unclear`）以及建议的后续步骤。" }, "trail": { "description": "核查内容：按顺序读取的概览、各部分和记录。" }, "decision": { "nullable": true, "allOf": [ { "$ref": "#/components/schemas/InvestigatorDecision" } ], "type": "object" }, "autonomy": { "type": "object", "additionalProperties": true, "description": "自主处理对报告的处理结果（`result`、`reason`、`tier`、`policy_version`、`rule`、`agreement`、`decisions`、`threshold`、`at`）。当队列未自动化时为 Null。", "nullable": true } } } ] }, "InvestigatorAcceptRequest": { "type": "object", "properties": { "narrative": { "type": "string", "maxLength": 4000, "description": "重写的陈述。发送该陈述会将决策记录为已编辑并已接受。" }, "send_email": { "type": "boolean", "default": false, "description": "就决策结果向当事人发送邮件。" }, "email_address": { "type": "string", "format": "email", "description": "当 `send_email` 为 true 时必填。" }, "email_language": { "type": "string", "default": "en", "maxLength": 16 } } }, "InvestigatorOverrideRequest": { "type": "object", "required": [ "action", "category", "reason" ], "properties": { "action": { "type": "string", "enum": [ "approve", "decline", "escalate", "request" ] }, "category": { "type": "string", "enum": [ "missing_context", "needs_information", "policy_differs", "evidence_misread", "other" ] }, "reason": { "type": "string", "minLength": 10, "maxLength": 500 }, "send_email": { "type": "boolean", "default": false, "description": "就决策结果向当事人发送邮件。" }, "email_address": { "type": "string", "format": "email", "description": "当 `send_email` 为 true 时必填。" }, "email_language": { "type": "string", "default": "en", "maxLength": 16 } } }, "InvestigatorBatchAcceptRequest": { "type": "object", "required": [ "run_ids" ], "properties": { "run_ids": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "format": "uuid" } } } }, "InvestigatorBatchAcceptResponse": { "type": "object", "properties": { "accepted": { "type": "integer" }, "skipped": { "type": "integer" }, "results": { "type": "array", "items": { "type": "object", "properties": { "run_id": { "type": "string", "format": "uuid" }, "result": { "type": "string", "enum": [ "accepted", "skipped" ] }, "reason": { "type": "string", "enum": [ "not_found", "forbidden", "already_decided", "not_ready", "guardrail", "invalid" ] }, "detail": {}, "action": { "type": "string" }, "final_status": { "type": "string" } } } } } }, "InvestigatorSettings": { "type": "object", "properties": { "stage": { "type": "string", "enum": [ "none", "shadow", "live" ] }, "stage_changed_at": { "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "stage_changed_by": { "type": "string", "readOnly": true }, "monthly_spend_limit": { "type": "string", "format": "decimal", "description": "以您的结算币种计的月度限额，0.01 至 1,000,000。Null 表示关闭该限额。", "nullable": true }, "spend_limit": { "type": "object", "readOnly": true, "properties": { "enabled": { "type": "boolean" }, "limit": { "type": "string", "format": "decimal", "nullable": true }, "spent": { "type": "string", "format": "decimal" }, "reviews": { "type": "integer" }, "reserved": { "type": "string", "format": "decimal", "description": "所有未结生产环境报告的价格，由于接受会产生费用而暂扣。" }, "currency": { "type": "string" }, "paused": { "type": "boolean", "description": "达到上限：不会开始新的审核。" } } } } }, "TravelRuleUtxoEntry": { "type": "object", "description": "UTXO 交易的一个输入或输出，与区块链上记录的一致。", "required": [ "address" ], "properties": { "address": { "type": "string", "maxLength": 128 }, "amount": { "type": "string", "nullable": true, "description": "以代币自身为单位的十进制字符串（BTC，而非聪）。可选。", "example": "0.0125" }, "txid": { "type": "string", "maxLength": 128, "description": "可选。输入所花费的交易。" }, "vout": { "type": "integer", "nullable": true, "minimum": 0, "description": "可选。输入所花费的输出索引。" } } }, "TravelRuleUtxo": { "type": "object", "description": "UTXO 转账（BTC、LTC、BCH、DOGE）的输入与输出。仅在这些链上支持：在任何其他链上将返回 `400`。Didit 会据此推断汇款人钱包（申报的钱包，否则为贡献金额最多的输入地址）和收款人输出（申报的输出，否则为唯一未将找零退回输入地址的输出，否则为支付转账金额的那笔输出）。结果保存在转账的 `chain_details` 中。", "required": [ "outputs" ], "properties": { "inputs": { "type": "array", "maxItems": 1000, "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" }, "description": "可选。若没有输入，则不会推断汇款人，也不会识别找零输出。" }, "outputs": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" } } } }, "TravelRuleChainSide": { "type": "object", "description": "Didit 根据链上数据解析出的其中一方钱包。", "properties": { "address": { "type": "string", "description": "钱包。在 memo 网络上为经典地址（XRP X-address 会被拆分为其经典地址和标签）；在闪电网络上为收款人节点 ID 或闪电网络地址。" }, "memo": { "type": "string", "description": "作为钱包一部分的目标标签或 memo；无则为 `\"\"`。" }, "source": { "type": "string", "enum": [ "declared", "x_address", "largest_input", "only_non_change_output", "amount_match", "invoice_payee", "updated" ], "description": "钱包来源：`declared`（您的请求）、`x_address`（从 XRP X-address 拆分）、`largest_input`（贡献最大的 UTXO 输入地址）、`only_non_change_output`（唯一的非找零 UTXO 输出）、`amount_match`（支付转账金额的那个 UTXO 输出）、`invoice_payee`（闪电网络付款请求中指定的收款人）、`updated`（稍后通过 `action: update_originator_wallet` 设置）。" } } }, "TravelRuleChainDetails": { "type": "object", "description": "当转账涉及的不止是一个地址向另一个地址付款时，该交易所在区块链对其两个钱包的命名方式。对于账户模型区块链上的转账（EVM、Solana、Tron），由于两个地址本身就是钱包，因此该字段为空（`{}`）。匹配、路由和地址簿会优先从此字段读取钱包信息。", "properties": { "chain": { "type": "string", "description": "规范链，例如 `BTC`、`XRP`，或用于闪电网络转账的 `LIGHTNING`。" }, "shape": { "type": "string", "enum": [ "utxo", "memo", "lightning" ] }, "originator": { "$ref": "#/components/schemas/TravelRuleChainSide" }, "beneficiary": { "$ref": "#/components/schemas/TravelRuleChainSide" }, "utxo": { "type": "object", "description": "在 UTXO 转账中：存储的输入和输出（金额为十进制字符串）以及 Didit 将哪些输出读取为何种内容。", "properties": { "inputs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" } }, "outputs": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleUtxoEntry" } }, "change_output_indexes": { "type": "array", "items": { "type": "integer" }, "description": "向输入地址回款的输出。" }, "beneficiary_output_index": { "type": "integer", "nullable": true, "description": "向收款人付款的输出；若无法明确区分则为 null。" } } }, "lightning": { "type": "object", "description": "在 Lightning 转账中：付款请求的内容。始终包含 `kind`（`bolt11`、`bolt12_offer`、`bolt12_invoice`、`bolt12_invoice_request`、`lnurl`、`lightning_address`、`node_id` 或 `unknown`）；BOLT11 发票会附加 `network`、`payee_node_id`、`payment_hash`、`amount_msat`、`created_at` 和 `expires_at`；BOLT12 字符串附加 `blinded_paths` 和 `payee_node_id`；LNURL 或 Lightning Address 附加其 `domain`。不会通过网络解析任何内容：仅对请求进行解码。", "additionalProperties": true }, "warnings": { "type": "array", "items": { "type": "string", "enum": [ "declared_originator_not_an_input", "declared_beneficiary_not_an_output", "beneficiary_output_ambiguous", "beneficiary_output_amount_differs" ] }, "description": "值得关注的 UTXO 不一致性：声明的汇款人不是输入、声明的收款人不是输出、无法区分出单一的收款人输出，或收款人输出支付的金额与交易声明的不一致。" }, "not_applicable_reason": { "type": "string", "enum": [ "LIGHTNING_NO_PAYEE_IDENTIFIER", "LIGHTNING_BOLT12_BLINDED_PAYEE", "LIGHTNING_LNURL_NAMES_NO_PAYEE" ], "description": "在未指明收款人的出站 Lightning 转账中：转账为何为 `NOT_APPLICABLE`。`LIGHTNING_NO_PAYEE_IDENTIFIER`（请求未指明收款人节点，或无法解码）、`LIGHTNING_BOLT12_BLINDED_PAYEE`（报价通过盲化路径隐藏了收款人）、`LIGHTNING_LNURL_NAMES_NO_PAYEE`（LNURL 指明的是服务而非收款人）。相同的代码会打开转账的最后一条 `timeline` 条目。" } } }, "WalletAddressImportRow": { "type": "object", "description": "要导入的一个钱包：通过其 `address`、`address_hash` 或两者。这些字段的 camelCase 形式也被接受，例如 `walletAddress`、`walletAddressHash`、`destinationTag` 和 `externalUserId`。", "properties": { "address": { "type": "string", "maxLength": 128, "description": "钱包地址。别名：`walletAddress`。" }, "address_hash": { "type": "string", "description": "将地址转换为小写后计算的 SHA-256，表示为 64 个十六进制字符或 44 个 Base64 字符。单独发送可在不透露其地址的情况下注册钱包；与 `address` 一起发送时，必须为该地址的哈希值。别名：`walletAddressHash`。" }, "chain": { "type": "string", "maxLength": 32 }, "memo": { "type": "string", "maxLength": 256, "description": "目标标签或备注。XRP：目标标签，0 到 4294967295 之间的整数（支持 JSON 数字格式）。XLM：最多 28 字节的文本备注、64 位 ID 或 32 字节的十六进制哈希。EOS：最多 256 字节。ATOM：最多 256 个字符。HBAR：最多 100 字节。Bitcoin、EVM、Solana、Tron、Litecoin、Bitcoin Cash、Dogecoin 和 Lightning 钱包不支持备注：若传入将返回 `400`。" }, "holder_name": { "type": "string", "maxLength": 255 }, "holder_vendor_data": { "type": "string", "maxLength": 255, "description": "您为持有者指定的内部标识符。别名：`externalUserId`。" }, "entity_type": { "type": "string", "enum": [ "individual", "company" ], "default": "individual" }, "label": { "type": "string", "maxLength": 255 }, "owner_type": { "type": "string", "enum": [ "customer", "internal", "vasp" ], "default": "customer" }, "travel_address": { "type": "string", "maxLength": 512 }, "self_declared": { "type": "boolean", "default": false, "description": "当您的设置允许时，创建已通过自主申报核验的条目。" } } }, "WalletAddressImportReport": { "type": "object", "description": "导入中每一行的处理情况，按发送顺序排列。", "properties": { "total": { "type": "integer" }, "created": { "type": "integer" }, "existing": { "type": "integer" }, "duplicate": { "type": "integer" }, "failed": { "type": "integer" }, "rows": { "type": "array", "items": { "type": "object", "properties": { "row": { "type": "integer", "description": "行号，从 1 开始。" }, "status": { "type": "string", "enum": [ "created", "existing", "duplicate", "failed" ], "description": "`created`：已添加到名录。`existing`：钱包已在名录中且未作任何改动。`duplicate`：重复了此导入中之前的某一行。`failed`：参见 `errors`。" }, "entry_id": { "type": "string", "format": "uuid", "nullable": true, "description": "该行创建或找到的地址簿条目。" }, "errors": { "type": "object", "description": "`failed` 行的字段错误；否则为空。" }, "duplicate_of_row": { "type": "integer", "nullable": true, "description": "在 `duplicate` 行上，表示其重复的行。" } } } } } }, "TravelRuleCounterpartyContact": { "type": "object", "description": "EMAIL 渠道写入单个名录条目的合规地址。", "properties": { "uuid": { "type": "string", "format": "uuid" }, "counterparty": { "type": "string", "format": "uuid", "description": "目录条目的 `id`，如 GET /v3/travel-rule/vasps/ 所显示。" }, "counterparty_name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "description": "可选标签，例如团队名称。" }, "source": { "type": "string", "enum": [ "staff", "application", "learned" ], "description": "staff：由 Didit 维护。learned：该 VASP 自身域名下的地址，通过其响应链接回复了请求。application：由您的应用添加。" }, "scope": { "type": "string", "enum": [ "platform", "application" ], "description": "platform：由 Didit 整理或从已验证的响应中获取，供所有 Didit 客户使用，对您而言为只读。application：对您的应用私有。" }, "created_by": { "type": "string", "description": "对于平台联系人和通过 API 密钥添加的联系人，该项为空。" }, "verified_at": { "type": "string", "format": "date-time", "nullable": true, "description": "此地址上次通过其响应链接回复请求的时间。" }, "is_invalid": { "type": "boolean", "description": "一旦地址发生退信或投诉，则为 true；EMAIL 通道会跳过该地址。" }, "invalid_reason": { "type": "string", "enum": [ "", "hard_bounce", "soft_bounce", "spam_complaint", "suppressed" ] }, "invalid_detail": { "type": "string", "description": "接收邮件服务器返回的原因（如有）。" }, "invalid_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleCounterpartyContactCreate": { "type": "object", "required": [ "counterparty", "email" ], "properties": { "counterparty": { "type": "string", "format": "uuid", "description": "目录条目的 `id`。" }, "email": { "type": "string", "format": "email", "maxLength": 254 }, "name": { "type": "string", "description": "可选标签。", "maxLength": 255 } } }, "TravelRuleNameMatch": { "type": "object", "nullable": true, "description": "决定转账的姓名比对结果，在运行比对前为 null。在当事方被脱敏期间，以及在 INTERNAL 交易另一方客户的副本上，`transfer_name`、`compared_name`、`matched_names` 和 `mismatched_names` 将被隐藏。`score` 和 `matched` 可能会不一致：`matched` 遵循严格程度规则，`score` 则是两个全名之间的相似度。", "properties": { "score": { "type": "integer", "minimum": 0, "maximum": 100, "description": "两个姓名的相似度，0 到 100。当任一姓名为空时为 0。" }, "matched": { "type": "boolean", "description": "姓名是否满足 `strictness`。转账的结果取决于比对每个字段的 `data_match`，因此即使此处为 true，转账状态仍可能为 COUNTERPARTY_MISMATCHED_DATA。" }, "method": { "type": "string", "enum": [ "none", "exact_token", "token_subset", "token_containment", "sequence_ratio" ], "description": "`matched` 的判定方式：无匹配（`NONE`）、精确 token（`STRICT`）、token 子集（`DEFAULT`）、token 包含（`CONTAINS`）或序列比率（`FUZZY`）。" }, "strictness": { "type": "string", "enum": [ "NONE", "STRICT", "CONTAINS", "DEFAULT", "FUZZY" ] }, "compared_with": { "type": "string", "enum": [ "wallet_holder", "counterparty_vasp" ], "description": "wallet_holder：为钱包记录的持有者。counterparty_vasp：交易对手在邮件响应页面上回复的名称，或在沙盒中 Didit Test VASP 回复的名称。" }, "transfer_name": { "type": "string", "description": "转账上的姓名。" }, "compared_name": { "type": "string", "description": "用于比对的姓名。" }, "matched_names": { "type": "array", "items": { "type": "string" }, "description": "在 `compared_name` 中找到的 `transfer_name` 词语。" }, "mismatched_names": { "type": "array", "items": { "type": "string" }, "description": "`compared_name` 中缺失的 `transfer_name` 词语，紧接着是 `transfer_name` 中缺失的 `compared_name` 词语。" } } }, "TravelRuleTransferRow": { "type": "object", "description": "转账列表中显示的一笔 Travel Rule 转账：仅包含 VASP 名称、钱包和备注，绝不包含汇款人或收款人的个人数据。", "properties": { "id": { "type": "string", "format": "uuid", "description": "转账的 id。" }, "transaction_id": { "type": "string", "format": "uuid", "description": "此转账所属的 Didit 交易。" }, "txn_id": { "type": "string", "nullable": true, "description": "您为该交易指定的自身 ID。Didit 为您登记的转账（例如 Didit Test VASP 入账转账）将带有生成的 ID。" }, "txn_date": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "withdrawal", "deposit", "message" ], "description": "withdrawal：出账。message：通道根据交易对手的消息创建的入账转账（TRP 查询、INTERNAL 入账分支，或 GTR、VerifyVASP 或 Sygna Bridge 消息）。deposit：任何其他入账转账。" }, "direction": { "type": "string", "enum": [ "INBOUND", "OUTBOUND" ] }, "status": { "type": "string", "enum": [ "AWAITING_COUNTERPARTY", "ON_HOLD", "COMPLETED", "FINISHED", "CANCELLED", "EXPIRED", "COUNTERPARTY_MISMATCHED_DATA", "COUNTERPARTY_VASP_NOT_FOUND", "COUNTERPARTY_VASP_NOT_REACHABLE", "UNCONFIRMED_OWNERSHIP", "COUNTERPARTY_VASP_GENERAL_DECLINE", "NOT_ENOUGH_COUNTERPARTY_DATA", "NOT_APPLICABLE" ] }, "reason": { "type": "string", "description": "`COUNTERPARTY_VASP_NOT_FOUND` 或 `COUNTERPARTY_VASP_NOT_REACHABLE` 转账受阻的原因，取值与转账自身的 `reason` 相同，因此列表无需逐一打开每笔转账即可区分合规邮件退信与无路由的交易对手。任何其他状态下为 `\"\"`。参见[转账受阻的原因](/zh/transaction-monitoring/travel-rule#为什么转账会卡住)。" }, "rail": { "type": "string", "nullable": true, "enum": [ "INTERNAL", "TRP", "GTR", "TRUST", "VERIFYVASP", "SYGNA", "EMAIL", "TEST_VASP", null ] }, "asset": { "type": "string", "description": "交易的币种。" }, "amount": { "type": "string", "description": "普通小数形式的金额，例如 \"1.25\"。" }, "originator_vasp": { "type": "string", "description": "出向：您 VASP 的法定名称。入向：交易对手的名称，来自其目录条目、Didit 网络成员、TRP 发送方、Didit Test VASP 或转账声明的名称。未知时为空。" }, "beneficiary_vasp": { "type": "string", "description": "出向：以相同方式计算得出的交易对手名称。入向：您 VASP 的法定名称。" }, "originator_wallet": { "type": "string" }, "beneficiary_wallet": { "type": "string" }, "originator_memo": { "type": "string", "description": "Memo 或目标标签，在没有该项的链上为空。" }, "beneficiary_memo": { "type": "string" }, "originator_wallet_type": { "type": "string", "enum": [ "vasp", "self_hosted", "own" ], "description": "vasp、self_hosted（声明为非托管）或 own（您的地址簿中记录为属于您的钱包）。您自己的一方始终为 vasp。" }, "beneficiary_wallet_type": { "type": "string", "enum": [ "vasp", "self_hosted", "own" ] }, "matched_transaction_id": { "type": "string", "format": "uuid", "nullable": true, "description": "您手动与已声明转账相匹配的充值交易另一方。" }, "deadline_at": { "type": "string", "format": "date-time", "nullable": true, "description": "如果转账仍在等待其交易对手，该转账过期的时间。针对您使用 `POST /v3/transactions/` 创建且需要进行交换的出账或入账的每一笔转账进行设置。低于阈值、不适用 Travel Rule 的闪电网络支付，以及交易对手联系到您时 Didit 创建的入账转账（入账 TRP 问询、网络消息或 INTERNAL 入账环节）时为 null。" }, "created_at": { "type": "string", "format": "date-time" } } }, "BankAccountCheckHolder": { "description": "核对账户所依据的名称。`full_name` 和 `business_name` 中仅能传入一个。", "oneOf": [ { "$ref": "#/components/schemas/BankAccountCheckPersonHolder" }, { "$ref": "#/components/schemas/BankAccountCheckBusinessHolder" } ] }, "BankAccountCheckRequest": { "type": "object", "required": [ "country", "account", "holder" ], "properties": { "country": { "type": "string", "minLength": 3, "maxLength": 3, "description": "账户所在的国家/地区，采用 ISO 3166-1 alpha-3 代码，例如 `NGA`。支持小写。", "example": "NGA" }, "account": { "type": "object", "description": "按所在国家/地区记录方式填写的账户：`iban`，或带有该国家/地区所需银行代码或分支机构代码（`sort_code`、`routing_number`、`transit_institution`、`bsb`、`ifsc`、`bank_code` 或 `bic`）的 `account_number`。墨西哥使用 `clabe`，阿根廷使用 `cbu_cvu`，这两者已标识银行。如果所在国家/地区有要求，企业账户需添加 `registration_id`。空格、短横线和点号将被忽略。该国家/地区的核验中未使用的键将被忽略；如果缺少其所需的键，则会返回指明该键的 `400`。", "properties": { "iban": { "type": "string", "maxLength": 64, "description": "使用 IBAN 的国家/地区的 IBAN。它必须属于 `country`。" }, "account_number": { "type": "string", "maxLength": 64, "description": "账号，适用于其账户记录方式包含独立银行代码或分支机构代码的国家/地区。" }, "sort_code": { "type": "string", "maxLength": 64, "description": "英国：6 位清算号。" }, "routing_number": { "type": "string", "maxLength": 64, "description": "美国：9 位 ABA 路由号。" }, "transit_institution": { "type": "string", "maxLength": 64, "description": "加拿大：8 位 transit 和机构编号。" }, "bsb": { "type": "string", "maxLength": 64, "description": "澳大利亚：6 位 BSB。" }, "ifsc": { "type": "string", "maxLength": 64, "description": "印度：11 个字符的 IFSC 编码。" }, "bank_code": { "type": "string", "maxLength": 64, "description": "银行代码，适用于所在国家/地区需要该项的情况，例如在尼日利亚。" }, "bic": { "type": "string", "maxLength": 64, "description": "银行的 BIC，适用于所在国家/地区的核验需要该项的情况。" }, "clabe": { "type": "string", "maxLength": 64, "description": "墨西哥：18 位 CLABE。它已包含银行名称。" }, "cbu_cvu": { "type": "string", "maxLength": 64, "description": "阿根廷：22 位 CBU 或 CVU。其中已指明银行名称。" }, "registration_id": { "type": "string", "maxLength": 64, "description": "企业账户的注册号（当所在国家/地区要求提供时）。" } }, "additionalProperties": { "type": "string", "maxLength": 64 }, "example": { "bank_code": "000014", "account_number": "0123450001" } }, "holder": { "$ref": "#/components/schemas/BankAccountCheckHolder" }, "vendor_data": { "type": "string", "nullable": true, "description": "您为此项检查指定的自身参考编号，将原样返回。", "example": "payout_20481" }, "consent": { "type": "boolean", "default": false, "description": "当账户持有人明确同意此项核查时设为 `true`。在账户核查需要此类同意的国家/地区为必填项：若未提供，核查将被拒绝并返回 `400`（其 `field` 为 `consent`，`reason` 为 `required`），且不计费。在其他国家/地区此项为选填，当您发送时，Didit 会将其与核查费用一同记录。", "example": true } } }, "BankAccountCheckResponse": { "type": "object", "required": [ "request_id", "result", "holder_name", "account", "vendor_data", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "此检查的 ID。" }, "result": { "type": "string", "enum": [ "match", "close_match", "no_match", "cannot_verify" ], "description": "`match`：银行持有以您发送的姓名开设的账户。`close_match`：以相近姓名开设，例如缺少中间名或有拼写错误。`no_match`：以其他姓名开设，或不存在此类账户。`cannot_verify`：银行未比对姓名即返回响应，例如账户已被冻结或注销。" }, "holder_name": { "type": "string", "nullable": true, "description": "仅在 `close_match` 时，且仅在银行返回时提供：银行记录中的账户名称。其他情况下为 `null`。" }, "account": { "type": "string", "description": "账户，已脱敏并仅保留后 4 位字符。" }, "vendor_data": { "type": "string", "nullable": true, "description": "您的自身参考编号，与您发送的内容一致。" }, "created_at": { "type": "string", "format": "date-time", "description": "检查运行的时间，以 UTC 表示。" } } }, "BankAccountCheckError": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string", "description": "错误详情（英文）。" }, "code": { "type": "string", "description": "用于分支判断的稳定代码。对于 `401` 和 `403` 不存在。" }, "field": { "type": "string", "description": "仅限 `400`：需更正的请求体字段，格式为以点分隔的路径，例如 `account.sort_code`。" }, "reason": { "type": "string", "enum": [ "required", "length", "format", "checksum", "country_mismatch", "rejected" ], "description": "仅限 `400`：字段被拒绝的原因。`required`、`length`、`format`、`checksum` 以及 `country_mismatch`（其他国家的 IBAN）为 Didit 自身的检查；`rejected` 表示银行拒绝了所提交的账户。" } } }, "BankVerificationResult": { "type": "object", "description": "单个银行验证步骤的结果，适用于用户验证和企业验证（KYB）。`method` 说明了账户是如何验证的，`none` 表示该人员在评估任何尝试之前未绑定银行即继续操作。`continued_without_bank` 表示该人员在评估尝试后仍未绑定银行继续操作。请参阅[银行验证方式](/zh/core-technology/bank-verification/verification-methods)和[当用户无法验证其银行时](/zh/core-technology/bank-verification/fallbacks)。", "properties": { "schema_version": { "type": "integer", "description": "此结果结构的当前版本。目前为 `1`。" }, "bank_verification_id": { "type": "string", "format": "uuid", "description": "此结果的 ID。" }, "node_id": { "type": "string", "description": "此结果所属的工作流节点。" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Expired" ], "description": "在执行其操作和状态规则后，该步骤的裁定结果。" }, "original_status": { "type": "string", "nullable": true, "description": "该步骤达成的首个裁决结果，早于任何后续变更（例如人工审核）。" }, "method": { "type": "string", "nullable": true, "enum": [ "open_banking", "account_lookup", "microdeposits", "statement", "none" ], "description": "账户的验证方式：`open_banking`（银行登录：用户在其银行登录）、`account_lookup`（账户核查：用户输入账户详情，银行确认姓名）、`microdeposits` 或 `statement`（上传银行对账单）。当用户在评估任何尝试前选择在没有银行的情况下继续时为 `none`，此时未验证任何账户。在完成一次已评估的尝试后，它将保持该尝试的方式。在评估账户之前以及工作流限制其返回的数据时为 `null`。工作流规则读取与 `bank.method` 相同的值。" }, "provider": { "type": "string", "nullable": true, "description": "运行连接的路由密钥。读取 `method` 而非此密钥，以确定账户的验证方式。" }, "credential_source": { "type": "string", "nullable": true, "enum": [ "native", "byok" ], "description": "`native`：Didit 自身的路由，从您的 Didit 余额中扣费。`byok`：您使用自己的凭据连接的应用市场服务商。" }, "route": { "type": "object", "nullable": true, "description": "同意前选择的路由。此后绝不更改。", "properties": { "provider_key": { "type": "string", "nullable": true, "description": "路由的键。" }, "credential_source": { "type": "string", "enum": [ "native", "byok" ] }, "is_fallback": { "type": "boolean", "description": "Didit 的自有路由是否替代了无法连接的市场提供商。" }, "provider_connection_id": { "type": "string", "nullable": true, "description": "用于 `byok` 的应用市场连接。" }, "requested_scopes": { "type": "array", "items": { "type": "string" }, "description": "连接请求的数据，例如 `ownership` 或 `balances`。" } } }, "connection": { "type": "object", "nullable": true, "description": "最新尝试的连接。在首次尝试前为 `null`。", "properties": { "status": { "type": "string", "enum": [ "pending", "connected", "cancelled", "timeout", "failed", "unsupported", "revoked", "expired" ] }, "institution_id": { "type": "string", "nullable": true, "description": "银行的 ID。对于未选择银行的账户核验，该值为 `null`。" }, "institution_name": { "type": "string", "nullable": true, "description": "银行名称。对于账户核验，该值为 `null`。" }, "institution_country": { "type": "string", "nullable": true, "description": "账户所在的国家/地区，采用 ISO 3166-1 alpha-3 格式。" }, "oauth": { "type": "boolean", "nullable": true, "description": "银行登录是通过 OAuth 还是应用间（app-to-app）运行。账户核对时为 `null`。" }, "connected_at": { "type": "string", "format": "date-time", "nullable": true, "description": "连接成功的时间。" }, "consent_expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "银行同意有效期结束的时间，用于银行登录。" }, "last_refreshed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "上次重新读取财务数据的时间。" }, "attempts": { "type": "integer", "description": "该用户在此步骤中尝试的次数，所有方式累计计算。" }, "reason_code": { "type": "string", "nullable": true, "description": "连接状态并非仅为 `connected` 的原因，例如 `USER_CANCELLED`、`INSTITUTION_DOWN`、`ACCOUNT_NOT_FOUND`、`REFERENCE_IDENTITY_MISSING` 或 `VERIFICATION_COMPLETED`。" } } }, "account": { "type": "object", "nullable": true, "description": "已评估的账户。在账户被评估之前为 `null`。", "properties": { "account_id_masked": { "type": "string", "nullable": true, "description": "脱敏后的账号。" }, "iban_masked": { "type": "string", "nullable": true, "description": "已脱敏的 IBAN。" }, "sort_code": { "type": "string", "nullable": true, "description": "英国的银行代码（sort code）。" }, "routing_number_masked": { "type": "string", "nullable": true, "description": "已脱敏的路由号码。" }, "type": { "type": "string", "nullable": true, "enum": [ "checking", "current", "savings", "business", "other" ] }, "subtype": { "type": "string", "nullable": true, "description": "银行自有的账户子类型。" }, "currency": { "type": "string", "nullable": true, "description": "账户的 ISO 4217 货币。" }, "holder_type": { "type": "string", "nullable": true, "enum": [ "person", "business", "unknown" ] }, "holders_count": { "type": "integer", "nullable": true }, "is_joint": { "type": "boolean", "nullable": true }, "is_business": { "type": "boolean", "nullable": true } } }, "ownership": { "type": "object", "nullable": true, "description": "账户持有人与已验证身份的比对情况。在评估账户之前为 `null`。", "properties": { "result": { "type": "string", "enum": [ "match", "partial_match", "no_match", "unknown", "not_verifiable" ], "description": "`partial_match` 表示相近匹配。`not_verifiable`：银行返回响应但没有可供比对的账户持有人。`unknown`：无法读取凭证，或者没有可供比对的身份信息。" }, "reference_identity_source": { "type": "string", "nullable": true, "description": "将持有者与之进行身份比对的步骤：`kyc`、`database_validation`、`expected_details`、`questionnaire`、`document_ai` 或 `kyb`。" }, "name_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "Didit 的持有人姓名分数。" }, "provider_name_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "银行自有的账户持有人姓名分数（若已返回）。" }, "address_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "持有人地址评分（当执行了地址匹配时）。" }, "email_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "持有人邮箱评分（当执行了邮箱匹配时）。" }, "phone_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "持有人电话评分（当执行了电话匹配时）。" }, "dob_score": { "type": "integer", "minimum": 0, "maximum": 100, "nullable": true, "description": "持有人出生日期评分（当银行提供了该信息时）。" }, "close_match": { "type": "boolean", "nullable": true, "description": "姓名是否落在近似匹配区间内。" }, "holder_confirmation": { "type": "string", "nullable": true, "enum": [ "pending", "confirmed", "rejected" ], "description": "要求确认近似匹配姓名时该人员的回答。如果从未询问则为 `null`。" }, "method": { "type": "string", "nullable": true, "enum": [ "exact", "token_set", "nickname", "transliteration", "fuzzy", "provider_only", "microdeposits" ], "description": "生成该分数的姓名比对方式。这不是验证方法：验证方法请查看顶层的 `method`。" }, "matched_holder_index": { "type": "integer", "nullable": true }, "holders": { "type": "array", "items": { "type": "object" }, "description": "银行列出的每个持有人及其评分。" }, "owner_identity_available": { "type": "boolean", "nullable": true }, "evidence_freshness": { "type": "string", "nullable": true, "enum": [ "live", "cached", "refreshed" ] }, "evaluated_at": { "type": "string", "format": "date-time", "nullable": true, "description": "计算得出裁定的时间。" } } }, "financial_data": { "type": "object", "description": "该步骤读取的财务数据。仅银行登录会读取此数据。", "properties": { "balances": { "type": "object", "nullable": true, "description": "带有 `balances` 权限范围。" }, "transactions": { "type": "object", "nullable": true, "description": "带有 `transactions` 权限范围。" }, "income": { "type": "object", "nullable": true, "description": "带有 `income` 权限范围。" }, "categorization": { "type": "object", "nullable": true, "description": "Didit 对读取交易的分类。如果没有则为 `null`。" }, "not_collected": { "type": "array", "items": { "type": "string", "enum": [ "balances", "income", "transactions" ] }, "description": "该步骤请求但验证账户的方法未收集的数据。余额、交易和收入仅来自银行登录，因此通过账户核查验证的账户会在此处列出它们。绝非失败。否则为空。" } } }, "billing": { "type": "object", "nullable": true, "properties": { "route": { "type": "string", "enum": [ "native", "byok" ] }, "billed": { "type": "boolean" }, "marketplace_fee": { "type": "string", "nullable": true, "description": "针对 `byok` 收取的应用市场平台费用。" }, "usage_type": { "type": "string", "nullable": true, "description": "计费所记入的使用量项目：`bank_verification` 对应银行登录或账户核验，`bank_statement_upload` 对应此前没有扣费银行尝试的对账单上传，`bank_byok_fee` 对应您自带提供商的市场服务费。未产生费用时为 `null`。" } } }, "reference_identity": { "type": "object", "nullable": true, "description": "持有人比对所依据的身份及其来源。" }, "signals": { "type": "object", "nullable": true, "description": "从交易历史记录中读取的账户信号（当该步骤读取了交易历史记录时）。" }, "connection_abandoned": { "type": "boolean", "nullable": true, "description": "在用户离开银行页面后，该步骤是否在未匹配的情况下结束。" }, "not_covered": { "type": "boolean", "nullable": true, "description": "在此步骤中是否无法连接到该用户的银行或国家/地区。当用户因没有可核验其国家/地区或银行的方式而选择不关联银行直接继续时，也为 `true`。" }, "continued_without_bank": { "type": "boolean", "description": "用户是否通过 **Continue without your bank** 离开了该步骤。此时 `continuation` 会说明原因。若在用户继续之前未评估任何尝试，则 `method` 为 `none`。在评估尝试（例如持有人不匹配）之后，`method` 将保持该尝试的验证方式，其判定和原因代码仍然有效。即使工作流缩小了返回数据的范围，也会返回此字段。" }, "continuation": { "type": "object", "nullable": true, "description": "用户在没有银行的情况下继续的方式。若未如此操作则为 `null`。当工作流限制其返回的数据时，仍会返回 `reason`，其他所有键均为 `null`。", "properties": { "reason": { "type": "string", "enum": [ "no_route", "institution_unsupported", "attempts_exhausted", "person_choice" ], "description": "原因，由 Didit 在该人员继续操作时判断：`no_route`（没有适用于其国家/地区的银行登录或账户核验服务）、`institution_unsupported`（他们选择的银行无法在此步骤中使用）、`attempts_exhausted`（所有尝试均已用尽且无正在进行的尝试），或 `person_choice`（存在核验方式但他们选择继续，也包括当前无法连接其银行的情况）。除非已评估的尝试已对该步骤做出决策，否则 `no_route` 和 `institution_unsupported` 遵循 `bank_unsupported_action`，`attempts_exhausted` 遵循 `bank_attempts_exhausted_action`，`person_choice` 遵循 `bank_skipped_action`。" }, "country": { "type": "string", "nullable": true, "description": "该人进行验证所在的国家/地区，ISO 3166-1 alpha-3 格式。若在选择前继续操作，则为 `null`。" }, "offered": { "type": "array", "items": { "type": "string", "enum": [ "statement", "microdeposits" ] }, "nullable": true, "description": "该人在继续操作时该国家/地区向其提供的其他验证方式，按提供顺序排列：`statement`（对账单上传），然后是 `microdeposits`（微额存款）。若未提供任何方式则为空。" }, "institution_id": { "type": "string", "nullable": true, "description": "对于 `institution_unsupported`，为该用户无法使用的银行 ID：其选择的银行，或其最后一次尝试最终落在的银行。Didit 从其自有的银行列表中获取该信息，绝不会从用户的设备中获取，因此该列表中不存在的银行将显示为 `null`。对于所有其他原因均为 `null`。" }, "institution_name": { "type": "string", "nullable": true, "description": "对于 `institution_unsupported`，为该银行的名称，来自与 `institution_id` 相同的列表。当该列表不包含该银行时以及对于所有其他原因，均为 `null`。" }, "continued_at": { "type": "string", "format": "date-time", "nullable": true, "description": "当事人继续操作的时间。" } } }, "evidence_purged_at": { "type": "string", "format": "date-time", "nullable": true, "description": "根据 `bank_evidence_retention_days` 删除银行凭证的时间。否则为 `null`。" }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "信息性代码，例如 `holder_declared`。警告本身绝不会改变状态。" }, "reason_codes": { "type": "array", "items": { "type": "string" }, "description": "得出该判定的原因，例如 `OWNER_NAME_PARTIAL`。可能适用多项。`NOT_COVERED`：由于没有任何方法可核验其国家/地区或银行，该人员在未绑定银行的情况下继续。`SKIPPED`：存在核验方式，但该人员选择在未绑定银行的情况下继续。如果已评估的尝试已对该步骤做出决策，则两者均不添加。" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "BankAccountCheckPersonHolder": { "type": "object", "description": "应持有该账户的人员。", "required": [ "full_name" ], "properties": { "full_name": { "type": "string", "maxLength": 255, "description": "应持有该账户的人员的姓名。", "example": "Maria Oliveira" } } }, "BankAccountCheckBusinessHolder": { "type": "object", "description": "应持有该账户的企业。用于检查企业账户。", "required": [ "business_name" ], "properties": { "business_name": { "type": "string", "maxLength": 255, "description": "应当持有该账户的公司名称。用于核验企业账户。" } } }, "BankVerificationPricing": { "type": "object", "description": "公开银行验证价格表：银行对账单上传、自有提供商密钥费用以及各国家/地区支持的方法。", "required": [ "currency", "statement_upload", "own_provider_fee_usd", "countries" ], "properties": { "currency": { "type": "string", "enum": [ "USD" ], "description": "响应中每个价格的货币。", "example": "USD" }, "statement_upload": { "$ref": "#/components/schemas/BankStatementUploadPricing" }, "own_provider_fee_usd": { "type": "string", "description": "对于使用您自己的提供商合同而非 Didit 合同的路由，每次计费的股权结构核验所收取的费用，无论结果如何均会收取。已取消、超时或已放弃的连接不予计费。保留 4 位小数的十进制数字符串，以 USD 计价。", "example": "0.0200" }, "countries": { "type": "object", "description": "每个国家/地区，以 ISO 3166-1 alpha-3 代码为键。", "additionalProperties": { "$ref": "#/components/schemas/BankVerificationPricingCountry" } } } }, "BankStatementUploadPricing": { "type": "object", "description": "银行对账单上传的计费方式。", "required": [ "price_usd", "included_after_charged_bank_attempt", "standalone_available" ], "properties": { "price_usd": { "type": "string", "description": "一次已收费的银行尝试后上传对账单的价格。4 位小数的十进制字符串，单位为美元（USD）。", "example": "0.0000" }, "included_after_charged_bank_attempt": { "type": "boolean", "description": "在同一会话中进行收费的银行尝试后，若该上传无需额外付费即可包含，则为 `true`。", "example": true }, "standalone_available": { "type": "boolean", "description": "当对账单上传可以独立运行而无需先尝试银行登录时为 `true`。在生产环境中为 `false`；沙盒会话可以在不产生计费的情况下进行测试。", "example": false } } }, "BankVerificationPricingCountry": { "type": "object", "description": "某个国家/地区的银行验证方式及其标价。", "required": [ "name", "methods" ], "properties": { "name": { "type": "string", "description": "英文国家/地区名称。", "example": "United Kingdom" }, "methods": { "$ref": "#/components/schemas/BankVerificationPricingMethods" } } }, "BankVerificationPricingMethods": { "type": "object", "description": "某个国家/地区的两种银行验证方法。", "required": [ "open_banking", "account_lookup" ], "properties": { "open_banking": { "$ref": "#/components/schemas/BankSignInPricing" }, "account_lookup": { "$ref": "#/components/schemas/BankAccountCheckPricing" } } }, "BankSignInPricing": { "type": "object", "description": "银行登录：用户登录其银行。按市场定价，同一市场内的所有银行价格相同。", "required": [ "available", "market", "price_usd", "add_ons" ], "properties": { "available": { "type": "boolean", "description": "仅在 Didit 于生产环境中在该国家/地区提供银行登录服务时为 `true`。", "example": true }, "market": { "type": "string", "nullable": true, "description": "适用其价格的市场。不可用时为 `null`。", "example": "UK and EEA" }, "price_usd": { "type": "string", "nullable": true, "description": "单次银行登录的标价。不可用时为 `null`。保留 4 位小数的数字字符串，以 USD 计价。", "example": "0.7900" }, "add_ons": { "type": "object", "description": "在该国家/地区定价的附加功能，每个均为以美元计价、保留 4 位小数的十进制字符串，计入银行登录价格。仅列出该国家/地区提供的附加功能；当银行登录不可用时为空。", "properties": { "balance": { "type": "string", "description": "账户余额附加功能。", "example": "0.3500" }, "transactions": { "type": "string", "description": "交易附加组件。", "example": "1.3000" } } } } }, "BankAccountCheckPricing": { "type": "object", "description": "账户核验：用户输入其账号，Didit 会向银行进行核验。按国家/地区定价。", "required": [ "available", "price_usd" ], "properties": { "available": { "type": "boolean", "description": "仅在 Didit 于生产环境中在该国家/地区提供账户核验服务时为 `true`。", "example": true }, "price_usd": { "type": "string", "nullable": true, "description": "银行响应的单次账户核验标价。不可用时为 `null`。保留 4 位小数的数字字符串，以 USD 计价。", "example": "0.4000" } } }, "ImportProvider": { "type": "object", "properties": { "key": { "type": "string", "enum": [ "sumsub", "jumio", "veriff", "onfido", "persona", "metamap", "socure", "idnow", "shufti", "idenfy", "ondato", "trulioo", "au10tix", "complycube", "other" ] }, "name": { "type": "string" }, "mode": { "type": "string", "enum": [ "api_list", "api_ids", "export_file" ], "description": "`api_list`：Didit 使用密钥列出记录。`api_ids`：上传导出中的记录 ID。`export_file`：上传 Didit 格式的导出文件。" }, "record_noun": { "type": "string" }, "credential_fields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "label": { "type": "string" }, "secret": { "type": "boolean" } } } }, "regions": { "type": "array", "items": { "type": "string" } }, "required_permissions": { "type": "array", "items": { "type": "string" } }, "docs_url": { "type": "string", "nullable": true }, "status_mapping": { "type": "object", "additionalProperties": { "type": "string", "enum": [ "Approved", "Declined", "In Review", "Expired", "Not Finished", "Abandoned" ] } } } }, "ImportJobSummary": { "type": "object", "description": "任意类型的单个导入任务，格式与控制台的“导入任务”抽屉所读取的结构一致。", "properties": { "id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "sessions", "businesses", "users", "status_rules", "transactions" ] }, "source": { "type": "string", "enum": [ "file", "api", "provider" ] }, "provider": { "type": "string", "nullable": true }, "provider_name": { "type": "string", "nullable": true }, "filename": { "type": "string", "nullable": true }, "state": { "type": "string", "enum": [ "ready", "queued", "running", "paused", "completed", "errors", "failed", "cancelled" ], "description": "控制台显示的任务状态；`errors` 表示任务已完成但存在被拒绝的行。" }, "status": { "type": "string" }, "is_dry_run": { "type": "boolean" }, "credential_hint": { "type": "string", "nullable": true }, "resumes_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "nullable": true }, "started_by": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true } } }, "progress": { "type": "object", "properties": { "total": { "type": "integer", "format": "int64" }, "processed": { "type": "integer", "format": "int64" }, "imported": { "type": "integer", "format": "int64" }, "updated": { "type": "integer", "format": "int64" }, "already_in_didit": { "type": "integer", "format": "int64" }, "failed": { "type": "integer", "format": "int64" }, "not_finished": { "type": "integer", "format": "int64" }, "same_person": { "type": "integer", "format": "int64" } } }, "face_templates": { "type": "object", "nullable": true, "properties": { "enabled": { "type": "boolean" }, "built": { "type": "integer", "format": "int64" }, "duplicates": { "type": "integer", "format": "int64" }, "blocklisted": { "type": "integer", "format": "int64" } } }, "eta_seconds": { "type": "integer", "nullable": true }, "created_at": { "type": "string", "format": "date-time" }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } } }, "FiledRegulatoryReport": { "type": "object", "description": "已定稿的监管报告，阻止了请求的删除操作。", "required": [ "uuid", "report_number", "report_type", "case_uuid" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "报告 UUID。" }, "report_number": { "type": "string", "description": "在控制台中显示的报告编号（例如 SAR-0001）。" }, "report_type": { "type": "string", "enum": [ "SAR", "STR", "CTR", "TTR", "UTR", "IFT", "CBR", "TFR" ], "description": "监管报告类型。" }, "case_uuid": { "type": "string", "format": "uuid", "description": "该报告所属的案件。" } } }, "FiledReportTransaction": { "type": "object", "description": "因已定稿的监管报告列出而无法删除的交易。", "required": [ "uuid", "transaction_id", "reports" ], "properties": { "uuid": { "type": "string", "format": "uuid", "description": "Didit 交易 UUID。" }, "transaction_id": { "type": "string", "description": "创建交易时提供的交易标识符。" }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/FiledRegulatoryReport" }, "description": "列出此交易的已定稿报告。" } } }, "InFiledReportError": { "type": "object", "description": "由于所选数据包含在已定稿的监管报告中，删除被拒绝。没有任何内容被删除。请删除该报告，然后重试请求。", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "in_filed_report" ], "description": "因最终监管报告阻止删除的稳定错误代码。" }, "reports": { "type": "array", "items": { "$ref": "#/components/schemas/FiledRegulatoryReport" }, "description": "阻止删除个人、企业、案件或会话的报告。" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/FiledReportTransaction" }, "description": "阻止删除该交易的交易列表，每笔均附带列出它的报告。" } } }, "SubjectDeletionInProgressError": { "type": "object", "description": "另一个请求仍在删除此人或企业。本次请求未删除任何内容，可在该删除操作完成后重试；重试将删除届时仍处于选中状态的内容。", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "subject_deletion_in_progress" ], "description": "因另一请求正在删除该个人或企业而返回的稳定错误代码。" } } }, "TravelRuleNetworkParticipantSummary": { "type": "object", "nullable": true, "description": "该应用自身在该网络上的参与者，若无则为 null。", "properties": { "mode": { "type": "string", "enum": [ "platform", "own" ], "description": "platform：由 Didit 的成员资格承载；own：在应用自身的成员资格下入驻。" }, "status": { "type": "string", "enum": [ "not_requested", "questionnaire_pending", "submitted_to_network", "active", "suspended", "rejected" ], "description": "not_requested：从未请求过，或网络拒绝了首次请求（参见 last_error）；questionnaire_pending：等待尽职调查问卷审核通过；submitted_to_network：已提交至网络入驻流程；active：网络已为该应用分配专属参与者代码；suspended / rejected：Didit 已暂停或拒绝该请求。" }, "participant_code": { "type": "string", "description": "网络分配给此应用的代号（对于 GTR，为其 VASP 代号）。出站消息携带此代号，绝不携带 Didit 自身的代号。" }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "activated_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "description": "网络拒绝注册时的答复；其他情况下为空。" } } }, "TravelRuleNetworkState": { "type": "object", "description": "该应用在特定网络上将如何发送 Travel Rule 消息，以及无法发送的原因。此项为配置状态，并非实时健康状态或投递检查。", "properties": { "rail": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "mode": { "type": "string", "enum": [ "own", "didit", "off", "unavailable" ], "description": "own：使用应用已关联的成员资格；didit：Didit 的成员资格将该应用作为自身有效参与者接入；off：在 disabled_networks 中禁用了平台路由，且无自身成员资格；unavailable：目前无法在此网络上发送任何内容（参见 state 和 reason）。" }, "state": { "type": "string", "enum": [ "own_membership", "live_through_didit", "off", "didit_onboarding", "questionnaire_needed", "questionnaire_in_review", "request_access", "request_sent", "unavailable", "error" ], "description": "own_membership：通过您关联的成员资格发送；live_through_didit：通过 Didit 成员资格下的专属参与者发送；off：您关闭了平台路由；didit_onboarding：Didit 自身在该网络上的成员资格尚未生效，因此无法接入任何人；questionnaire_needed / questionnaire_in_review：尽职调查问卷必须提交或正在由 Didit 审核；request_access：问卷已通过，可申请接入网络；request_sent：您的参与者正在入驻中；unavailable：参见 reason；error：参见 reason。" }, "reason": { "type": "string", "enum": [ "own_membership_connected", "platform_network_switched_off", "own_membership_only", "sandbox_application", "didit_membership_not_live", "participant_suspended", "participant_rejected", "questionnaire_not_submitted", "questionnaire_submitted", "questionnaire_changes_requested", "questionnaire_rejected", "participant_not_requested", "participant_active", "participant_key_missing", "participant_key_unresolved", "provisioning_failed", "questionnaire_pending", "submitted_to_network" ], "description": "状态的机器可读详情。own_membership_only：Didit 在此网络（TRUST）上不承载应用，请连接您自己的成员资格；sandbox_application：沙盒转账绝不会送达网络；provisioning_failed：网络拒绝了注册，参与者的 last_error 指明了原因，再次请求该网络将重试。" }, "platform_available": { "type": "boolean", "description": "Didit 自身在该网络中的成员身份是否已配置；并非实时健康状态检查。" }, "connected": { "type": "boolean", "description": "是否存在已连接的客户成员身份。凭证在本地进行验证；网络验证则在实时交互中进行。" }, "participant": { "$ref": "#/components/schemas/TravelRuleNetworkParticipantSummary" }, "vasps_reachable": { "type": "integer", "description": "在此网络上可达的目录中的 VASP。" }, "routed_30d": { "type": "integer", "description": "过去 30 天内该应用在此网络上进行的转账。" } } }, "TravelRuleNetworkQuestionnaireAnswers": { "type": "object", "description": "Didit 网络尽职调查问卷。保存操作是部分保存：保存会保留所有未提及的答案。提交时除 lei 和 data_protection_contact_email 之外的所有字段均为必填项，且三项证明必须为 true。", "properties": { "legal_name": { "type": "string", "maxLength": 255 }, "registration_number": { "type": "string", "maxLength": 255 }, "incorporation_country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 国家/地区代码。" }, "registered_address": { "type": "string", "maxLength": 1000 }, "website": { "type": "string", "format": "uri", "maxLength": 500 }, "lei": { "type": "string", "maxLength": 20, "description": "可选。若提供，须为有效的 ISO 17442 LEI。" }, "licences": { "type": "array", "minItems": 1, "items": { "type": "object", "required": [ "regulator", "jurisdiction", "licence_type", "licence_number" ], "properties": { "regulator": { "type": "string", "maxLength": 255 }, "jurisdiction": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 国家/地区代码。" }, "licence_type": { "type": "string", "maxLength": 255 }, "licence_number": { "type": "string", "maxLength": 255 } } }, "description": "该 VASP 持有的每项许可证或注册。" }, "operating_jurisdictions": { "type": "array", "minItems": 1, "maxItems": 250, "items": { "type": "string", "minLength": 2, "maxLength": 2, "description": "ISO 3166-1 alpha-2 国家/地区代码。" } }, "compliance_officer_name": { "type": "string", "maxLength": 255 }, "compliance_officer_email": { "type": "string", "format": "email" }, "aml_ctf_policy_attested": { "type": "boolean", "description": "提交时必须为 true。" }, "sanctions_screening_attested": { "type": "boolean", "description": "提交时必须为 true。" }, "data_protection_attested": { "type": "boolean", "description": "提交时必须为 true。" }, "data_protection_contact_email": { "type": "string", "format": "email", "description": "可选。" }, "expected_monthly_transfers": { "type": "integer", "minimum": 0 }, "expected_monthly_volume_usd": { "type": "string", "format": "decimal", "description": "预期的每月交易量（美元），最多保留 2 位小数。以字符串形式返回。" }, "assets": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "string", "maxLength": 32 }, "description": "资产代号，存储为大写、已排序并去重。" } } }, "TravelRuleNetworkQuestionnaire": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "draft", "submitted", "changes_requested", "approved", "rejected" ], "description": "答案可在 draft 或 changes_requested 状态下保存；submitted、approved 和 rejected 则由 Didit 负责推进。" }, "answers": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaireAnswers" }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "reviewed_at": { "type": "string", "format": "date-time", "nullable": true }, "review_note": { "type": "string", "description": "Didit 对其最新决策的备注，例如需要修改的内容。" }, "history": { "type": "array", "readOnly": true, "description": "每次状态变更，按时间正序排列。", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "string" }, "note": { "type": "string", "description": "审核备注或网络回复（如果有）。" } } } }, "updated_at": { "type": "string", "format": "date-time", "nullable": true } } }, "TravelRuleNetworkParticipant": { "type": "object", "description": "该应用自身在某个网络上的参与者。", "properties": { "network": { "type": "string", "enum": [ "gtr", "trust", "verifyvasp", "sygna" ] }, "rail": { "type": "string", "enum": [ "GTR", "TRUST", "VERIFYVASP", "SYGNA" ] }, "mode": { "type": "string", "enum": [ "platform", "own" ] }, "status": { "type": "string", "enum": [ "not_requested", "questionnaire_pending", "submitted_to_network", "active", "suspended", "rejected" ], "description": "not_requested：从未请求过，或网络拒绝了首次请求（参见 last_error）；questionnaire_pending：等待尽职调查问卷审核通过；submitted_to_network：已提交至网络入驻流程；active：网络已为该应用分配专属参与者代码；suspended / rejected：Didit 已暂停或拒绝该请求。" }, "participant_code": { "type": "string" }, "requested_at": { "type": "string", "format": "date-time", "nullable": true }, "submitted_at": { "type": "string", "format": "date-time", "nullable": true }, "activated_at": { "type": "string", "format": "date-time", "nullable": true }, "suspended_at": { "type": "string", "format": "date-time", "nullable": true }, "last_error": { "type": "string", "description": "网络拒绝注册时的答复；其他情况下为空。" }, "history": { "type": "array", "readOnly": true, "description": "每次状态变更，按时间正序排列。", "items": { "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "from": { "type": "string" }, "to": { "type": "string" }, "note": { "type": "string", "description": "审核备注或网络回复（如果有）。" } } } } } }, "TravelRuleNetworksOverview": { "type": "object", "properties": { "platform_networks_enabled": { "type": "boolean", "description": "通过 Didit 成员身份的网络访问是否已开放。若为 false，问卷保存、提交和网络请求均将返回 403。" }, "questionnaire": { "$ref": "#/components/schemas/TravelRuleNetworkQuestionnaire" }, "participants": { "type": "array", "items": { "$ref": "#/components/schemas/TravelRuleNetworkParticipant" } }, "networks": { "type": "object", "readOnly": true, "description": "按网络列出：此应用将如何发送以及为何无法发送。默认不包含任何网络（包括 GTR）：网络可通过您自己已连接的成员资格访问，或者在 Didit 在该网络上的成员资格生效且您自己在该网络上的参与方处于活跃状态后，通过 Didit 的成员资格访问。非实时健康状态或投递检查。", "properties": { "gtr": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "trust": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "verifyvasp": { "$ref": "#/components/schemas/TravelRuleNetworkState" }, "sygna": { "$ref": "#/components/schemas/TravelRuleNetworkState" } } } } }, "AddressValidationResult": { "type": "object", "description": "单次地址验证的结果：地址是否存在，以及其规范化形式。它仅确认地址；绝不会将地址与个人关联。", "required": [ "status", "verification_level", "address", "formatted_address", "latitude", "longitude" ], "properties": { "status": { "type": "string", "enum": [ "verified", "partially_verified", "not_verified", "unavailable" ], "description": "`verified`：地址已确认具体到建筑物（或单元/公寓、邮政信箱）。`partially_verified`：仅确认到街道，或确认到该地点邮政参考数据所能支持的最精确级别。`not_verified`：仅匹配到地区或城市，或完全未匹配。`unavailable`：无法执行核验（例如参考服务未响应）；该状态不计费，且绝不会影响验证。" }, "verification_level": { "type": "string", "nullable": true, "enum": [ "administrative_area", "locality", "thoroughfare", "premise", "delivery_point", null ], "description": "地址匹配到的最高精确度级别。未匹配到任何内容或 `status` 为 `unavailable` 时为 `null`。" }, "address": { "type": "object", "nullable": true, "description": "标准化地址。当 `status` 为 `unavailable` 时为 `null`。", "properties": { "address_line_1": { "type": "string", "nullable": true, "description": "投递地址第一行，按该国家/地区的书写习惯书写。", "example": "1600 Amphitheatre Pkwy" }, "address_line_2": { "type": "string", "nullable": true, "description": "第二行投递地址（公寓、楼栋或社区，若地址包含）。" }, "city": { "type": "string", "nullable": true, "example": "Mountain View" }, "region": { "type": "string", "nullable": true, "description": "州、省或地区。", "example": "CA" }, "postal_code": { "type": "string", "nullable": true, "example": "94043-1351" }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2 国家/地区代码。", "example": "US" } } }, "formatted_address": { "type": "string", "nullable": true, "description": "单行格式的标准化地址。", "example": "1600 Amphitheatre Pkwy, Mountain View CA 94043-1351" }, "latitude": { "type": "number", "nullable": true, "example": 37.422022 }, "longitude": { "type": "number", "nullable": true, "example": -122.08429 } } }, "AddressValidationRequest": { "type": "object", "required": [ "country" ], "description": "一个地址：使用单行文本（`address`），或者至少包含 `address_line_1` 的结构化字段，两者不可兼有。", "properties": { "address": { "type": "string", "maxLength": 500, "description": "单行完整地址。", "example": "Paseo de la Castellana 259, 28046 Madrid" }, "address_line_1": { "type": "string", "maxLength": 255, "description": "街道与门牌号。", "example": "1600 Amphitheatre Pkwy" }, "address_line_2": { "type": "string", "maxLength": 255, "description": "公寓、套房、楼层或楼栋。" }, "city": { "type": "string", "maxLength": 128, "description": "城市或地区。", "example": "Mountain View" }, "region": { "type": "string", "maxLength": 128, "description": "州、省或地区。", "example": "CA" }, "postal_code": { "type": "string", "maxLength": 32, "example": "94043" }, "country": { "type": "string", "maxLength": 3, "description": "地址所在国家/地区的 ISO 3166-1 alpha-2 或 alpha-3 代码。", "example": "US" } } }, "AddressValidationResponse": { "type": "object", "required": [ "request_id", "address_validation", "created_at" ], "properties": { "request_id": { "type": "string", "format": "uuid", "description": "此请求的标识符；联系支持团队时请引用此标识符。不会创建会话。" }, "address_validation": { "$ref": "#/components/schemas/AddressValidationResult" }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleWalletProofFailureReason": { "type": "string", "enum": [ "", "SIGNATURE_INVALID", "SIGNATURE_UNSUPPORTED_SCHEME", "DEPOSIT_NOT_FOUND", "DEPOSIT_UNCONFIRMED", "DEPOSIT_LOOKUP_FAILED", "DEPOSIT_MISMATCH", "DEPOSIT_STALE", "TXID_REUSED", "CHAIN_UNSUPPORTED", "WINDOW_EXPIRED", "OWNERSHIP_CHANGED", "METHOD_SWITCHED", "REVIEW_REJECTED", "ABANDONED" ], "description": "钱包所有权证明（或其最近一次尝试）未能达到 VERIFIED 的原因。未出现失败时为空。处于 PENDING 状态的证明可能会包含此项：最近一次尝试失败，终端用户可以重试。DEPOSIT_MISMATCH、DEPOSIT_STALE、TXID_REUSED 和 REVIEW_REJECTED 会将证明关闭为 REJECTED。SIGNATURE_INVALID：签名与钱包和挑战值不匹配。SIGNATURE_UNSUPPORTED_SCHEME：钱包签名的格式 Didit 无法验证。DEPOSIT_NOT_FOUND、DEPOSIT_UNCONFIRMED、DEPOSIT_LOOKUP_FAILED：测试存款不可读取或尚未确认；Didit 会持续检查，直至测试窗口关闭。DEPOSIT_MISMATCH：交易未从该钱包向存款地址发送预期金额。DEPOSIT_STALE：交易早于挑战值发生。TXID_REUSED：该交易已用于证明另一个钱包。CHAIN_UNSUPPORTED：该方法在此链上不可用。WINDOW_EXPIRED：测试窗口已关闭。OWNERSHIP_CHANGED：在小组件会话生成后，钱包持有者发生变更，或钱包已从您的地址簿中删除。METHOD_SWITCHED：终端用户在完成该方法之前选择了另一种方法。REVIEW_REJECTED：您的审核员拒绝了该截图。ABANDONED：小组件会话在终端用户完成之前已失效。" }, "TravelRuleWidgetProofError": { "type": "object", "properties": { "detail": { "type": "string", "description": "便于人类阅读的英文消息。" }, "code": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "机器可读的原因，以便客户端展示其自有的翻译消息。" }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ], "description": "在证明已关闭时存在：因刚提交的充值而变为 REJECTED（400），或在向已关闭的证明发送证据时为 REJECTED 或 EXPIRED（409）。" }, "proof_id": { "type": "string", "format": "uuid", "description": "与状态一起提供：已关闭的证明。" }, "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ], "description": "与状态一起提供：已关闭证明的方式。" }, "max_attempts": { "type": "integer", "description": "随状态存在：该会话允许的被拒绝钱包证明。" }, "attempts_used": { "type": "integer", "description": "与状态一起提供：截至目前被拒绝的证明。" }, "attempts_remaining": { "type": "integer", "description": "与状态一起提供：当其值为 0 时，启动另一个证明将返回 409，您需要生成新的小部件会话。" } } }, "TravelRuleWidgetProofCreate": { "type": "object", "required": [ "method" ], "properties": { "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ], "description": "终端用户选择的证明方式。必须是上下文 allowed_methods 中的一种。" }, "wallet_address": { "type": "string", "maxLength": 128, "description": "默认为会话的 wallet_address。当会话关联到转账时，必须与转账的钱包匹配。" }, "chain": { "type": "string", "maxLength": 32, "description": "默认为会话所属的链。" } } }, "TravelRuleWidgetProofVerifyResult": { "type": "object", "properties": { "proof_id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT", "SELF_DECLARATION" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ] }, "is_ownership_verified": { "type": "boolean", "description": "在证明为 VERIFIED 时存在：地址簿条目现已通过所有权核验。" }, "transfer_status": { "type": "string", "nullable": true, "description": "在证明为 VERIFIED 时存在：关联转账的状态，若无关联转账则为 null。" }, "detail": { "type": "string", "description": "在证明保持为 PENDING 期间存在：等待审核的已提交截图，或尚未确认的测试充值。" }, "code": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "在待处理的测试充值中存在：说明尚未确认的原因。" } } }, "TravelRuleWalletProofReview": { "type": "object", "properties": { "proof_id": { "type": "string", "format": "uuid" }, "method": { "type": "string", "enum": [ "SCREENSHOT" ] }, "status": { "type": "string", "enum": [ "PENDING", "VERIFIED", "REJECTED", "EXPIRED" ] }, "wallet_address": { "type": "string" }, "chain": { "type": "string", "description": "规范链标识符，例如 ETH、BTC、SOL、TRX。" }, "holder_name": { "type": "string" }, "is_ownership_verified": { "type": "boolean", "description": "该地址簿条目是否已完成所有权核验（通过此证明或其他证明）。" }, "transaction_id": { "type": "string", "format": "uuid", "nullable": true, "description": "为其生成小部件会话的 Travel Rule 转账所属的交易。对于生成时未提供 transaction_id 的会话，该值为 null。" }, "file_name": { "type": "string", "nullable": true }, "content_type": { "type": "string", "nullable": true }, "screenshot_url": { "type": "string", "nullable": true, "description": "已上传屏幕截图的有时限链接。重新列出队列以获取新链接。" }, "attempts": { "type": "integer", "description": "终端用户为此证明上传的文件数量。" }, "failure_reason": { "allOf": [ { "$ref": "#/components/schemas/TravelRuleWalletProofFailureReason" } ], "description": "拒绝后为 REVIEW_REJECTED，在做出决策前钱包持有人发生变更或被删除时为 OWNERSHIP_CHANGED。其他情况下为空。" }, "method_chosen_at": { "type": "string", "format": "date-time", "nullable": true, "description": "终端用户选择屏幕截图方式的时间。" }, "decided_at": { "type": "string", "format": "date-time", "nullable": true }, "decided_by": { "type": "string", "description": "关闭证明的主体：控制台审核员为 review:，API 密钥决策为 review，Didit 自动关闭时为 widget 或 sweeper。处于 PENDING 状态时为空。" }, "review_note": { "type": "string", "description": "随决策一同发送的备注。若无则为空。" }, "created_at": { "type": "string", "format": "date-time" } } }, "TravelRuleWalletProofDecision": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string", "enum": [ "approve", "reject" ] }, "note": { "type": "string", "maxLength": 512, "description": "可选。与证明一同保存，并作为 review_note 返回。" } } }, "DigitalIdWalletApiWalletDigitalCredentialsRequest": { "type": "object", "properties": { "protocol": { "type": "string", "description": "openid4vp-v1-signed。" }, "request": { "type": "object", "additionalProperties": {}, "description": "原样传递：在浏览器中为 navigator.credentials.get({digital: request})，或在 Android 上作为 GetDigitalCredentialOption 的 requestJson 传入 JSON.stringify(request)。由 Didit 为您的应用签名。" } }, "required": [ "protocol", "request" ] }, "DigitalIdWalletApiGoogleWalletWalletVerificationStartRequest": { "type": "object", "description": "启动 Google Wallet 验证（USA、GBR、BRA、SGP、TWN）。", "properties": { "vendor_data": { "type": "string", "nullable": true, "description": "您为此验证指定的自身参考编号（例如您的用户 ID）。在结果和 Webhook 中返回。" }, "metadata": { "type": "object", "additionalProperties": {}, "nullable": true, "description": "与验证一同存储并在结果和 Webhook 中返回的可选 JSON 对象。" }, "sandbox_scenario": { "type": "string", "minLength": 1, "description": "仅限沙盒应用：模拟结果，可为 'wallet_cancelled'、'wallet_timeout' 或 'wallet_provider_error'；任何其他场景（或无场景）均通过验证。在生产环境应用上会被拒绝。完整目录可在 GET /v1/sandbox/scenarios/ 获取。" }, "country": { "allOf": [ { "$ref": "#/components/schemas/DigitalIdWalletApiGoogleWalletWalletVerificationStartCountryEnum" } ], "description": "Google Wallet 身份的 ISO 3166-1 alpha-3 国家/地区。\n\n* `USA` - USA\n* `GBR` - GBR\n* `BRA` - BRA\n* `SGP` - SGP\n* `TWN` - TWN" }, "origin": { "type": "string", "minLength": 1, "description": "您的页面或应用向钱包发起请求的来源位置：页面的 https 源（其 host 必须在应用的 allowed_return_hosts 中，或是其白标域名），例如 https://app.example.com，或者 android:apk-key-hash:<您应用签名证书的 base64 SHA-256，无填充>。钱包会拒绝来自其他任何位置的请求。", "maxLength": 256 } }, "required": [ "country", "origin" ] }, "DigitalIdWalletApiGoogleWalletWalletVerificationStartCountryEnum": { "enum": [ "USA", "GBR", "BRA", "SGP", "TWN" ], "type": "string", "description": "* `USA` - USA\n* `GBR` - GBR\n* `BRA` - BRA\n* `SGP` - SGP\n* `TWN` - TWN" }, "DigitalIdWalletApiWalletDigitalCredentialResponseRequest": { "type": "object", "description": "对于 `request_digital_credential` 验证，钱包向您的页面或应用返回的内容。", "properties": { "response": { "type": "object", "additionalProperties": {}, "description": "钱包返回的确切内容：来自 navigator.credentials.get 的 DigitalCredential 的 {protocol, data}，或 Android DigitalCredential 解析后的 credentialJson。已为 Didit 加密；切勿修改。" } }, "required": [ "response" ] }, "SessionFilesExport": { "type": "object", "description": "包含会话中所有原始画质文件的一个 ZIP 包。", "required": [ "export_id", "session_id", "status", "file_count", "size_bytes", "download_url", "expires_at", "error", "created_at", "completed_at" ], "properties": { "export_id": { "type": "string", "format": "uuid", "description": "导出的 ID。将其传递给 `GET /v3/session/{sessionId}/files-export/{exportId}/`。" }, "session_id": { "type": "string", "format": "uuid", "description": "文件所属的会话。" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "READY", "FAILED", "EXPIRED" ], "description": "ZIP 准备期间为 `PENDING` 和 `PROCESSING`，可供下载后为 `READY`，无法准备时为 `FAILED`（请发起新的导出请求），ZIP 被删除后为 `EXPIRED`。" }, "file_count": { "type": "integer", "nullable": true, "description": "ZIP 包中的文件。仅当 `status` 为 `READY` 时设置。" }, "size_bytes": { "type": "integer", "format": "int64", "nullable": true, "description": "ZIP 文件的大小（字节）。仅在 `status` 为 `READY` 时设置。" }, "download_url": { "type": "string", "format": "uri", "nullable": true, "description": "ZIP 文件的签名 URL，短期内有效。仅在 `status` 为 `READY` 时设置；如需新的 URL，请重新读取该导出。" }, "expires_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ZIP 文件的删除时间，为生成就绪后 24 小时。仅当 `status` 为 `READY` 时设置。" }, "error": { "type": "string", "nullable": true, "description": "当 `status` 为 `FAILED` 时，导出失败的原因。" }, "created_at": { "type": "string", "format": "date-time", "description": "请求导出的时间。" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true, "description": "ZIP 文件就绪或导出失败的时间。" } } }, "TransactionRuleSuggestionsCreatedEvent": { "description": "交易规则建议运行为您的应用提出了新的规则更改建议。在规则建议设置开启 Webhook 通知时发送。没有顶层 `status`。", "allOf": [ { "$ref": "#/components/schemas/WebhookEventEnvelope" }, { "type": "object", "properties": { "webhook_type": { "type": "string", "enum": [ "transaction_rule_suggestions.created" ], "description": "始终为 `transaction_rule_suggestions.created`。" }, "run_id": { "type": "string", "format": "uuid", "description": "生成新建议的建议运行。" }, "open_count": { "type": "integer", "description": "本次运行后仍处于开启状态的建议数量，包括新增的建议。" }, "suggestions": { "type": "array", "description": "本次运行创建的建议。", "items": { "type": "object", "required": [ "suggestion_id", "kind", "title", "rule_id", "expected_impact" ], "properties": { "suggestion_id": { "type": "string", "format": "uuid" }, "kind": { "type": "string", "enum": [ "ADD", "TWEAK", "DISABLE" ], "description": "`ADD` 提议新增规则，`TWEAK` 更改现有规则，`DISABLE` 停用规则。" }, "title": { "type": "string" }, "rule_id": { "type": "string", "format": "uuid", "nullable": true, "description": "`TWEAK` 或 `DISABLE` 建议所适用的规则；对于 `ADD` 为 `null`。" }, "expected_impact": { "type": "object", "additionalProperties": true, "description": "该变更将执行的操作，如 Console 中的建议所示。" } } } } }, "required": [ "webhook_type", "run_id", "open_count", "suggestions" ] } ] }, "GeolocationCheck": { "type": "object", "description": "单个位置验证结果，即一个工作流节点已接受的尝试。测量值、不确定性和真实性是独立的键，因此精确的未证明定位与不精确的已证明定位读取结果不同。", "properties": { "node_id": { "type": "string", "nullable": true, "description": "生成此结果的工作流节点，从而使包含两个位置验证步骤的工作流保持清晰易读。" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "此位置验证步骤的功能级状态，根据其警告解析得出。独立于会话的 `status`。" }, "outcome": { "type": "string", "nullable": true, "description": "本次尝试中发生的情况。", "enum": [ "verified", "low_accuracy", "accuracy_undetermined", "stale", "approximate", "denied", "restricted", "unavailable", "timeout", "mock_detected", "outside_geofence", "in_blocked_area", "anonymizer_detected", "skipped", "replay_rejected", "unsupported_client", null ] }, "permission": { "type": "string", "nullable": true, "description": "操作系统或浏览器授予的权限。`not_requested` 表示该步骤仅使用连接的 IP 位置，因此绝不会向用户请求权限。", "enum": [ "granted_precise", "granted_approximate", "denied", "restricted", "unavailable", "timeout", "dismissed", "not_requested", null ] }, "latitude": { "type": "number", "nullable": true, "description": "定位点的 WGS84 纬度。无定位点时为 `null`。", "format": "double" }, "longitude": { "type": "number", "nullable": true, "description": "定位点的 WGS84 经度。无定位点时为 `null`。", "format": "double" }, "accuracy_m": { "type": "number", "nullable": true, "description": "不确定性半径（米），基于 `accuracy_confidence` 中的置信度水平。", "format": "double" }, "accuracy_confidence": { "type": "string", "nullable": true, "description": "平台附加到 `accuracy_m` 的置信度水平：`p95`（浏览器）、`p68`（Android）或 `unspecified`（iOS）。", "enum": [ "p95", "p68", "unspecified", null ] }, "measured_at": { "type": "string", "nullable": true, "description": "设备按自身时钟获取定位的时间。", "format": "date-time" }, "age_seconds": { "type": "integer", "nullable": true, "description": "设备完成定位与 Didit 接收到定位之间的秒数间隔。" }, "source": { "type": "string", "nullable": true, "description": "定位的来源（当平台指明时）。`ip` 表示位置为连接的 IP 位置。", "enum": [ "gps", "fused", "network", "wifi", "cell", "browser", "unknown", "ip", null ] }, "platform": { "type": "string", "nullable": true, "description": "生成该修复的客户端。", "enum": [ "web", "ios", "android", "react_native", "flutter", null ] }, "sdk_version": { "type": "string", "nullable": true, "description": "生成该修复的 SDK 版本。" }, "is_mock": { "type": "boolean", "nullable": true, "description": "当设备指示定位结果来自模拟位置提供程序或模拟软件时为 `true`。当平台未报告该信息时为 `null`（浏览器无法识别）；`null` 不等同于 `false`。" }, "produced_by_accessory": { "type": "boolean", "nullable": true, "description": "仅限 iOS：当定位数据来自外部配件时为 `true`。其他情况为 `null`。" }, "integrity": { "type": "string", "enum": [ "attested", "not_attested", "failed", "unsupported", "not_determined" ], "description": "设备证明是否为该修复提供支持。`unsupported` 为浏览器所报告的值，因为 Web 没有证明机制；这并非故障。" }, "country_code": { "type": "string", "nullable": true, "description": "定位所在的国家/地区的 ISO 3166-1 alpha-2 代码。" }, "region_code": { "type": "string", "nullable": true, "description": "定位点所在的 ISO 3166-2 行政区划。" }, "city": { "type": "string", "nullable": true, "description": "最近的有人口聚居地，供审核员参考的标签。" }, "geofence": { "type": "object", "description": "该步骤的国家/地区及区域规则的结果。", "properties": { "enabled": { "type": "boolean", "description": "该步骤是否应用了任何国家/地区或区域规则。" }, "result": { "type": "string", "nullable": true, "description": "该位置相对于规则所处的状态。`undetermined` 表示精度圆跨越了边界或位置未解析到任何国家/地区；这并不能证明其处于范围之外。", "enum": [ "inside", "outside", "undetermined", null ] } } }, "inside_geofence": { "type": "boolean", "nullable": true, "description": "当 `geofence.result` 为 `inside` 时为 `true`，为 `outside` 时为 `false`，否则为 `null`。" }, "geofence_basis": { "type": "string", "nullable": true, "description": "区域结果所判定的位置来源：`device` 定位或连接的 `ip` 位置。", "enum": [ "device", "ip", null ] }, "inside_areas": { "type": "array", "items": { "type": "string" }, "description": "该位置所在的已配置允许区域的 ID 列表。" }, "blocked_areas": { "type": "array", "items": { "type": "string" }, "description": "该位置所在的已配置拦截区域的 ID 列表。" }, "position_source": { "type": "string", "nullable": true, "description": "该步骤获取位置的来源，按配置而定：设备与 IP 位置对照检查、仅设备，或仅 IP 位置。", "enum": [ "device_and_ip", "device_only", "ip_only", null ] }, "anonymizers": { "type": "object", "nullable": true, "description": "连接和设备的情况，各项为 `true`、`false`，若来源无法判断则为 `null`。", "properties": { "vpn": { "type": "boolean", "nullable": true }, "proxy": { "type": "boolean", "nullable": true }, "tor": { "type": "boolean", "nullable": true }, "spoofing": { "type": "boolean", "nullable": true }, "emulator": { "type": "boolean", "nullable": true } } }, "ip_distance_km": { "type": "number", "nullable": true, "description": "减去两个不确定性半径后到会话 IP 位置的距离；重叠时为 `0`。", "format": "double" }, "ip_distance_uncertainty_km": { "type": "number", "nullable": true, "description": "扣除的合并半径：IP 定位半径加上此次定位修正的准确度。", "format": "double" }, "ip_consistent": { "type": "boolean", "nullable": true, "description": "`ip_distance_km` 是否在步骤中配置的距离范围内。当任一方未知时为 `null`。" }, "document_distance_km": { "type": "number", "nullable": true, "description": "到身份证件或地址证明上经地理编码地址的距离。若无留存地址则为 `null`。", "format": "double" }, "travel_excused": { "type": "boolean", "nullable": true, "description": "该步骤的行程容差是否豁免了与地址的距离。容差关闭时为 `null`。" }, "consecutive_mismatches": { "type": "integer", "nullable": true, "description": "在最后一次尝试中：此检查加上同一人先前连续的不匹配项。" }, "attempts": { "type": "integer", "description": "该节点内的尝试次数序号，从 1 开始。" }, "consent": { "type": "object", "nullable": true, "description": "该人在系统提示前给出的同意，记录了他们所看到的用词版本和语言。", "properties": { "accepted_at": { "type": "string", "format": "date-time" }, "version": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true } } }, "warnings": { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string", "enum": [ "ID_VERIFICATION", "NFC", "LIVENESS", "FACEMATCH", "PROOF_OF_ADDRESS", "PHONE", "EMAIL", "AML", "LOCATION", "DATABASE_VALIDATION", "QUESTIONNAIRE", "DOCUMENT_AI", "KYB_REGISTRY", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE", "GEOLOCATION", "SIGNATURE" ], "description": "生成此警告的功能。该值标识警告所属的功能块。每个模块的警告数组通常使用与其模块匹配的值（例如 `phone_verifications[].warnings` 内的 `PHONE`），但上述枚举在决策 payload 的所有功能警告中具有权威性。" }, "risk": { "type": "string" }, "additional_data": { "type": "object", "nullable": true }, "log_type": { "type": "string" }, "short_description": { "type": "string" }, "long_description": { "type": "string" }, "node_id": { "type": "string", "description": "生成此警告的工作流图节点 ID" } } }, "description": "该位置验证步骤生成的警告，`feature` 设置为 `GEOLOCATION`。警告代码以 `LOCATION_` 开头。" } } }, "GeolocationAttempt": { "type": "object", "description": "位置验证步骤的一次尝试：字段与 `geolocation_checks[]` 相同（`warnings` 除外），另加 Didit 接收该尝试的时间。", "properties": { "node_id": { "type": "string", "nullable": true, "description": "生成此结果的工作流节点，从而使包含两个位置验证步骤的工作流保持清晰易读。" }, "status": { "type": "string", "enum": [ "Not Finished", "Approved", "Declined", "In Review", "Resub Requested" ], "description": "此位置验证步骤的功能级状态，根据其警告解析得出。独立于会话的 `status`。" }, "outcome": { "type": "string", "nullable": true, "description": "本次尝试中发生的情况。", "enum": [ "verified", "low_accuracy", "accuracy_undetermined", "stale", "approximate", "denied", "restricted", "unavailable", "timeout", "mock_detected", "outside_geofence", "in_blocked_area", "anonymizer_detected", "skipped", "replay_rejected", "unsupported_client", null ] }, "permission": { "type": "string", "nullable": true, "description": "操作系统或浏览器授予的权限。`not_requested` 表示该步骤仅使用连接的 IP 位置，因此绝不会向用户请求权限。", "enum": [ "granted_precise", "granted_approximate", "denied", "restricted", "unavailable", "timeout", "dismissed", "not_requested", null ] }, "latitude": { "type": "number", "nullable": true, "description": "定位点的 WGS84 纬度。无定位点时为 `null`。", "format": "double" }, "longitude": { "type": "number", "nullable": true, "description": "定位点的 WGS84 经度。无定位点时为 `null`。", "format": "double" }, "accuracy_m": { "type": "number", "nullable": true, "description": "不确定性半径（米），基于 `accuracy_confidence` 中的置信度水平。", "format": "double" }, "accuracy_confidence": { "type": "string", "nullable": true, "description": "平台附加到 `accuracy_m` 的置信度水平：`p95`（浏览器）、`p68`（Android）或 `unspecified`（iOS）。", "enum": [ "p95", "p68", "unspecified", null ] }, "measured_at": { "type": "string", "nullable": true, "description": "设备按自身时钟获取定位的时间。", "format": "date-time" }, "age_seconds": { "type": "integer", "nullable": true, "description": "设备完成定位与 Didit 接收到定位之间的秒数间隔。" }, "source": { "type": "string", "nullable": true, "description": "定位的来源（当平台指明时）。`ip` 表示位置为连接的 IP 位置。", "enum": [ "gps", "fused", "network", "wifi", "cell", "browser", "unknown", "ip", null ] }, "platform": { "type": "string", "nullable": true, "description": "生成该修复的客户端。", "enum": [ "web", "ios", "android", "react_native", "flutter", null ] }, "sdk_version": { "type": "string", "nullable": true, "description": "生成该修复的 SDK 版本。" }, "is_mock": { "type": "boolean", "nullable": true, "description": "当设备指示定位结果来自模拟位置提供程序或模拟软件时为 `true`。当平台未报告该信息时为 `null`（浏览器无法识别）；`null` 不等同于 `false`。" }, "produced_by_accessory": { "type": "boolean", "nullable": true, "description": "仅限 iOS：当定位数据来自外部配件时为 `true`。其他情况为 `null`。" }, "integrity": { "type": "string", "enum": [ "attested", "not_attested", "failed", "unsupported", "not_determined" ], "description": "设备证明是否为该修复提供支持。`unsupported` 为浏览器所报告的值，因为 Web 没有证明机制；这并非故障。" }, "country_code": { "type": "string", "nullable": true, "description": "定位所在的国家/地区的 ISO 3166-1 alpha-2 代码。" }, "region_code": { "type": "string", "nullable": true, "description": "定位点所在的 ISO 3166-2 行政区划。" }, "city": { "type": "string", "nullable": true, "description": "最近的有人口聚居地，供审核员参考的标签。" }, "geofence": { "type": "object", "description": "该步骤的国家/地区及区域规则的结果。", "properties": { "enabled": { "type": "boolean", "description": "该步骤是否应用了任何国家/地区或区域规则。" }, "result": { "type": "string", "nullable": true, "description": "该位置相对于规则所处的状态。`undetermined` 表示精度圆跨越了边界或位置未解析到任何国家/地区；这并不能证明其处于范围之外。", "enum": [ "inside", "outside", "undetermined", null ] } } }, "inside_geofence": { "type": "boolean", "nullable": true, "description": "当 `geofence.result` 为 `inside` 时为 `true`，为 `outside` 时为 `false`，否则为 `null`。" }, "geofence_basis": { "type": "string", "nullable": true, "description": "区域结果所判定的位置来源：`device` 定位或连接的 `ip` 位置。", "enum": [ "device", "ip", null ] }, "inside_areas": { "type": "array", "items": { "type": "string" }, "description": "该位置所在的已配置允许区域的 ID 列表。" }, "blocked_areas": { "type": "array", "items": { "type": "string" }, "description": "该位置所在的已配置拦截区域的 ID 列表。" }, "position_source": { "type": "string", "nullable": true, "description": "该步骤获取位置的来源，按配置而定：设备与 IP 位置对照检查、仅设备，或仅 IP 位置。", "enum": [ "device_and_ip", "device_only", "ip_only", null ] }, "anonymizers": { "type": "object", "nullable": true, "description": "连接和设备的情况，各项为 `true`、`false`，若来源无法判断则为 `null`。", "properties": { "vpn": { "type": "boolean", "nullable": true }, "proxy": { "type": "boolean", "nullable": true }, "tor": { "type": "boolean", "nullable": true }, "spoofing": { "type": "boolean", "nullable": true }, "emulator": { "type": "boolean", "nullable": true } } }, "ip_distance_km": { "type": "number", "nullable": true, "description": "减去两个不确定性半径后到会话 IP 位置的距离；重叠时为 `0`。", "format": "double" }, "ip_distance_uncertainty_km": { "type": "number", "nullable": true, "description": "扣除的合并半径：IP 定位半径加上此次定位修正的准确度。", "format": "double" }, "ip_consistent": { "type": "boolean", "nullable": true, "description": "`ip_distance_km` 是否在步骤中配置的距离范围内。当任一方未知时为 `null`。" }, "document_distance_km": { "type": "number", "nullable": true, "description": "到身份证件或地址证明上经地理编码地址的距离。若无留存地址则为 `null`。", "format": "double" }, "travel_excused": { "type": "boolean", "nullable": true, "description": "该步骤的行程容差是否豁免了与地址的距离。容差关闭时为 `null`。" }, "consecutive_mismatches": { "type": "integer", "nullable": true, "description": "在最后一次尝试中：此检查加上同一人先前连续的不匹配项。" }, "attempts": { "type": "integer", "description": "该节点内的尝试次数序号，从 1 开始。" }, "consent": { "type": "object", "nullable": true, "description": "该人在系统提示前给出的同意，记录了他们所看到的用词版本和语言。", "properties": { "accepted_at": { "type": "string", "format": "date-time" }, "version": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true } } }, "received_at": { "type": "string", "nullable": true, "description": "Didit 收到此次尝试的时间。", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" } } }, "BiometricRetention": { "type": "object", "description": "此会话的实时生物特征数据被删除的时间。", "required": [ "jurisdictions", "deletes_at" ], "properties": { "jurisdictions": { "type": "array", "items": { "type": "string" }, "description": "其生物识别规则对该人员设定了删除时限的美国州代码（若州未知则为 `US`）。若不适用则为空。" }, "deletes_at": { "type": "string", "format": "date-time", "nullable": true, "description": "根据您应用的数据保留设置以及该人员所在管辖区的法定限制（如果适用），此会话的活体生物特征数据（人脸图像和模板）被删除的日期。尚无适用日期时为 `null`。" } } }, "TravelRuleManualMatchRequest": { "type": "object", "required": [ "transaction_id" ], "properties": { "transaction_id": { "type": "string", "format": "uuid", "description": "收到的 Travel Rule 消息的 `transaction_id`（`kind: message` 的行）。" } } }, "TravelRuleManualMatchResponse": { "type": "object", "required": [ "deposit", "message" ], "properties": { "deposit": { "$ref": "#/components/schemas/TravelRuleTransferRow" }, "message": { "$ref": "#/components/schemas/TravelRuleTransferRow" } } } }, "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "您的应用 API 密钥，可在 Business Console 的“开发者 -> API 密钥”中获取。主密钥拥有完整访问权限。指定名称的密钥可设置作用域：针对每个资源设为无权限、只读或读写，限定于特定工作流或已通过的会话、限定于 IP 地址列表，以及设置到期日期。401 表示密钥错误、已撤销或已过期；403 表示未发送密钥、密钥无权访问该资源或操作，或请求来自其 IP 列表之外的地址；在会话路由上返回 404 表示该会话不在该密钥允许的工作流或状态范围内。没有媒体访问权限的密钥获取到的图片、视频和 PDF URL 将为 null；没有会话写入权限的密钥获取到的会话链接和 token 将为 null。请参阅 https://docs.didit.me/console/api-keys。" }, "TransactionTokenAuth": { "type": "apiKey", "in": "header", "name": "X-Transaction-Token", "description": "由您的后端通过 POST /v3/transactions/sdk-token/ 生成的短期限定范围 token。供 Didit SDK 在面向设备的 /v1/transactions/ endpoint 上使用。" }, "SessionTokenAuth": { "type": "apiKey", "in": "header", "name": "Session-Token", "description": "在 POST /v3/session/ 的 `session_token` 字段中返回的短期 token。由托管验证流程（以及自定义沙盒 UI）用于代表正在验证的用户调用限定会话范围的 endpoint，无需使用您的服务器端 API 密钥。" }, "BearerAuth": { "type": "http", "scheme": "bearer", "description": "该应用的客户端凭证访问 token。" }, "CaseRequestToken": { "type": "apiKey", "in": "header", "name": "X-Case-Request-Token", "description": "来自安全链接的请求专用凭证。仅授予对该请求的访问权限。" } }, "responses": { "Unauthorized": { "description": "未授权", "content": { "application/json": { "examples": { "Invalid API Key": { "summary": "无效的 API 密钥", "value": { "detail": "Invalid API Key." } } } } } }, "Forbidden": { "description": "禁止访问", "content": { "application/json": { "examples": { "No Permission": { "summary": "无权限", "value": { "detail": "You do not have permission to perform this action." } }, "Not Enough Credits": { "summary": "额度不足", "value": { "error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me" } } } } } }, "NotFound": { "description": "未找到", "content": { "application/json": { "examples": { "Not Found": { "summary": "未找到", "value": { "detail": "Resource not found." } } } } } }, "PhoneRiskValidationError": { "description": "请求验证失败。", "content": { "application/json": { "examples": { "Missing phone number": { "summary": "缺少电话号码", "value": { "phone_number": [ "This field is required." ] } }, "Invalid phone number": { "summary": "无效的电话号码", "value": { "phone_number": [ "Invalid phone number provided." ] } }, "Invalid signal IP": { "summary": "无效的信号 IP", "value": { "signals": { "ip": [ "Enter a valid IPv4 or IPv6 address." ] } } } } } } }, "EmailRiskValidationError": { "description": "请求验证失败。", "content": { "application/json": { "examples": { "Missing email": { "summary": "缺少邮箱", "value": { "email": [ "This field is required." ] } }, "Invalid email": { "summary": "无效的邮箱", "value": { "email": [ "Enter a valid email address." ] } }, "Invalid country hint": { "summary": "无效的国家/地区提示", "value": { "country_code": [ "Ensure this field has no more than 3 characters." ] } } } } } }, "IPRiskValidationError": { "description": "请求验证失败。", "content": { "application/json": { "examples": { "Missing IP address": { "summary": "缺少地址", "value": { "ip_address": [ "This field is required." ] } }, "Invalid IP address": { "summary": "无效的 IP 地址", "value": { "ip_address": [ "Enter a valid IPv4 or IPv6 address." ] } }, "Country hint too long": { "summary": "国家/地区提示过长", "value": { "claimed_country": [ "Ensure this field has no more than 3 characters." ] } } } } } }, "RiskPermissionDenied": { "description": "API 密钥缺失或无效，或者组织无法支付实时查询费用。此 API 从不返回 `401`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "summary": "缺少 `x-api-key` 请求头，或者密钥无效或已被吊销", "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "summary": "组织余额不足以支付查询价格", "value": { "error": "You don't have enough credits to perform this request." } } } } } }, "RateLimitedWrite": { "description": "已超出每个 API 密钥每分钟 300 次请求的共享写入限制。在重试之前请遵循 `Retry-After`。", "content": { "application/json": { "schema": { "type": "object", "required": [ "detail" ], "properties": { "detail": { "type": "string" } } }, "example": { "detail": "Write request rate limit exceeded. You can make up to 300 requests per minute." } } } }, "AddressValidationValidationError": { "description": "请求体无效：缺失或未知的 `country`、未提供地址，或同时提供了 `address` 与结构化字段。", "content": { "application/json": { "examples": { "Unknown country": { "value": { "country": [ "Use an ISO 3166-1 alpha-2 or alpha-3 country code, e.g. 'US' or 'USA'." ] } }, "No address": { "value": { "address": [ "Send the address: 'address' on one line, or the structured fields with 'address_line_1'." ] } }, "Both shapes": { "value": { "address": [ "Send either 'address' or the structured fields (address_line_1, ...), not both." ] } } } } } }, "AddressValidationPermissionDenied": { "description": "API 密钥缺失或无效、限定作用域的密钥缺少 `sessions` 写入权限，或者组织无法支付核验费用。此 API 从不返回 `401`。", "content": { "application/json": { "examples": { "Missing or invalid API key": { "value": { "detail": "You do not have permission to perform this action." } }, "Not enough credits": { "value": { "detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me", "code": "insufficient_credits" } } } } } }, "DocumentProcessingBusy": { "description": "当前正在处理的证件过多，因此本次上传未被处理：未存储任何内容，且未消耗尝试次数。请在 `Retry-After` 指定的秒数后再次发送相同文件。请根据 `code` 进行分支判断，而非根据消息文本。", "headers": { "Retry-After": { "description": "再次发送相同请求前需等待的秒数。", "schema": { "type": "integer", "example": 10 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "detail", "code" ], "properties": { "detail": { "type": "string" }, "code": { "type": "string", "enum": [ "document_processing_busy" ] } } }, "example": { "detail": "We are busy processing documents. Please try again in a moment.", "code": "document_processing_busy" } } } } }, "parameters": { "WebhookSignature": { "name": "X-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "以目标密钥进行键控的精确原始请求正文的小写十六进制 HMAC-SHA256。" }, "WebhookSignatureV2": { "name": "X-Signature-V2", "in": "header", "required": true, "schema": { "type": "string" }, "description": "以目标密钥进行键控的正文规范 JSON（键排序、无空白符、非 ASCII 字符不转义）的小写十六进制 HMAC-SHA256。推荐使用，因为它不受会对正文重新编码的中介软件影响。" }, "WebhookSignatureSimple": { "name": "X-Signature-Simple", "in": "header", "required": true, "deprecated": true, "schema": { "type": "string" }, "description": "以目标密钥进行键控的 `{timestamp}:{session_id}:{status}:{webhook_type}`（缺失字段为空字符串）的小写十六进制 HMAC-SHA256。仅涵盖信封结构，绝不涵盖 payload。" }, "WebhookTimestamp": { "name": "X-Timestamp", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Unix 时间（以秒为单位），等于请求体中的 `timestamp`。拒绝超过几分钟的投递。" } } }, "x-webhooks": { "status.updated": { "post": { "summary": "会话状态已变更", "description": "验证会话状态发生变更。`decision` 仅在状态为 `Approved`、`Declined`、`In Review` 和 `Abandoned` 时发送；对于使用 Webhook 版本 3（默认）的目标，其结构与 `GET /v3/session/{sessionId}/decision/` 相同；对于版本 1 或版本 2 的目标，则采用较早的精简结构。企业会话始终接收版本 3 的企业决策。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "data.updated": { "post": { "summary": "会话数据已更改", "description": "验证会话的数据在状态未发生变化的情况下发生变更，例如在人工审核编辑、步骤覆盖或持续监控重新筛查之后。`decision` 仅针对 `Approved`、`Declined`、`In Review` 和 `Abandoned` 发送；对于 Webhook 版本 3（默认）的目标，其格式与 `GET /v3/session/{sessionId}/decision/` 相同，对于版本 1 或版本 2 的目标，则采用较早的精简格式。企业会话始终接收版本 3 的企业决策。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionDataUpdatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "user.status.updated": { "post": { "summary": "用户状态已变更", "description": "用户状态发生变更。创建用户时不会发送。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "user.data.updated": { "post": { "summary": "用户数据已变更", "description": "用户的字段已更改。创建用户时不会发送。一次保存可能同时产生状态事件和数据事件。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserDataUpdatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "business.status.updated": { "post": { "summary": "企业状态已变更", "description": "企业状态发生变更。创建企业时不会发送。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "business.data.updated": { "post": { "summary": "企业数据已变更", "description": "企业的字段已更改。创建企业时不会发送。一次保存可能同时产生状态事件和数据事件。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessDataUpdatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "transaction.created": { "post": { "summary": "交易已创建", "description": "交易已创建并完成筛查。仅针对生产环境应用发送。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionCreatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "transaction.status.updated": { "post": { "summary": "交易状态已变更", "description": "交易状态已更改，原因来自规则、审核或终端用户操作。仅针对生产环境应用发送。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "travel_rule.status.updated": { "post": { "summary": "Travel Rule 状态已变更", "description": "Travel Rule 交换状态已变更。在直到并包括 `FINISHED`、`CANCELLED` 或 `EXPIRED` 的每次状态转换时发送，此后绝不发送。针对生产环境应用发送；对于 Travel Rule 交换，也会针对沙盒应用发送（`environment: sandbox`）。没有顶级 `status`。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TravelRuleStatusUpdatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "workflow.compliance_changed": { "post": { "summary": "工作流合规状态已更改", "description": "已发布工作流的合规状态在重新评估后发生了变更。每个工作流触发一个事件。不存在顶级 `status`。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowComplianceChangedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "kyb.registry_search.resolved": { "post": { "summary": "企业搜索已解析（未签名回调）", "description": "一旦登记查询解析完成，发送至 `POST /v3/kyb/search/` 的 `webhook_url` 的回调正文。此回调未签名：请求带有 `X-Didit-Unsigned-Callback: true` 且不包含任何签名请求头，因此请通过将 `request_id` 与您发起的查询进行比对来确认。使用 `event_type`，而非 `webhook_type`。", "tags": [ "Webhook" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KYBRegistrySearchResolvedCallback" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } }, "transaction_rule_suggestions.created": { "post": { "summary": "交易规则建议已创建", "description": "交易规则建议运行为您的应用提出了新的规则更改建议。在规则建议设置开启 Webhook 通知时发送。没有顶层 `status`。", "tags": [ "Webhook" ], "parameters": [ { "$ref": "#/components/parameters/WebhookSignature" }, { "$ref": "#/components/parameters/WebhookSignatureV2" }, { "$ref": "#/components/parameters/WebhookSignatureSimple" }, { "$ref": "#/components/parameters/WebhookTimestamp" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionRuleSuggestionsCreatedEvent" } } } }, "responses": { "2XX": { "description": "任何 2xx 响应均确认已投递。其他响应和超时将会重试；参见 https://docs.didit.me/integration/webhooks。" } } } } } }