跳转到主要内容
服务端 SDK 是 Didit 官方为您的后端提供的库。每个 SDK 都使用类型化的请求和响应调用 API 参考 中的服务端 endpoint，验证 Didit 发送给您的 Webhook，并验证 Didit Authentication 的 token。1.0.1 版本尚未包含两个 Google Wallet endpoint：发起 Google Wallet 验证和提交钱包响应。Python、Node.js、Java、PHP、Ruby 和 .NET SDK 包含其他所有服务端 endpoint。Go 1.0.1 还缺少另外九个 endpoint，其中大多数是 Travel Rule endpoint：请参阅Go SDK 尚未提供的 endpoint。 只要您的代码持有 Didit API 密钥，就可以使用这些服务端 SDK：创建验证会话、读取决策、调用独立 API、管理用户、企业、工作流和案件、筛查交易和钱包，以及使用 Travel Rule。在浏览器或移动应用中，请改用 Web 和原生 SDK：它们向用户展示验证流程，且从不持有您的 API 密钥。 API 参考中的服务端 endpoint 页面（包括数据库核验服务页面）会在 cURL 请求旁边显示每个服务端 SDK 的代码示例。只有当 SDK 的最新版本包含该 endpoint 以及示例发送的每个字段时，才会显示该示例：API 新增的 endpoint 或字段，会在各 SDK 的下一个版本中获得示例。1.0.1 版本的任何 SDK 都没有在生成之后新增的 16 个数据库核验请求字段（例如 vin 或 bank_account_number），因此发送这些字段的服务页面只显示 cURL。

​
安装

​
配置

每个 SDK 都读取相同的环境变量，因此不带任何选项创建的客户端即可直接使用。边缘运行时没有进程环境变量：此时请将 API 密钥作为选项传给 Node.js 客户端。 凡是可以通过环境变量设置的内容，也都可以传给客户端，包括基础 URL、超时、重试、默认请求头和您自己的 HTTP 客户端。请在每个进程中创建一个客户端并共享使用：它会维护连接池，可以安全地被多个线程或任务同时使用。 account 方法（程序化注册：注册、登录、组织和应用）会调用 https://apx.didit.me/auth/v2，且从不发送您的 API 密钥。请使用 account.login 登录，然后将返回的 访问 token 作为 账户 token 传给客户端。

​
每个 SDK 的功能

  • 资源和方法。 调用遵循 API 的资源结构：client.<resource>.<method>(...)，例如 sessions.create、sessions.retrieve_decision 或 transactions.create，大小写遵循各语言自身的习惯。路径 ID 作为位置参数传入；请求正文和查询参数则合并为一组具名字段。Python、Node.js、PHP 和 Ruby 使用 API 自身的字段名（workflow_id）；Go、Java 和 .NET 使用各自语言的命名方式（WorkflowID、workflowId、WorkflowId）。
  • 列表。 列表方法会自动翻页，为您遍历全部结果（底层使用 limit 和 offset），同时也会以 count、next、previous 和 results 的形式公开每一页。在 Ruby 中，auto_paging_each 会遍历所有页面，而每一页的 total_count、next_url 和 previous_url 分别对应 API 的 count、next 和 previous。
  • 文件。 上传（证件图像、自拍照、地址证明、导入文件）接受文件路径、字节或数据流。下载（会话 PDF、报告）返回字节或数据流，从不返回解析后的 JSON。
  • 向前兼容。 SDK 版本尚未识别的响应字段或枚举值会被保留并可读取，不会报错，因此 API 新增内容不会影响已部署的集成。
  • Webhook。 webhooks.verify 会使用您的 Webhook 密钥检查每次投递的 X-Signature-V2 和 X-Signature 请求头及时间戳，并返回类型化的事件。在轮换密钥期间，它可接受多个密钥组成的列表。签名方案请参阅 Webhook。
  • 认证。 Authentication 辅助工具用于验证您的 Authentication 颁发者签发的 访问 token 和 ID token，并调用其 token、会话和增强验证 endpoint。它从不使用您的 API 密钥。

​
错误、重试和超时

所有错误都派生自 DiditError。在 Go 中，每个错误都实现 didit.Error 接口，并且是指针类型，例如 *didit.NotFoundError。Java、PHP 和 .NET 使用各自常见的 Exception 后缀命名错误，并将 API 写为 Api：DiditException、ApiStatusException、NotFoundException。 SDK 会对失败的请求最多重试 2 次，采用指数退避，起始间隔为 0.5 秒（完全抖动，最长 8 秒），并遵循 Retry-After。GET、HEAD、PUT 和 DELETE 在连接错误、超时、408、429 和 5xx 时重试。POST 和 PATCH 仅在收到 429，或请求发送前连接已失败时重试，因此重试不会创建第二个会话或交易。默认超时时间为 60 秒。每个响应还会暴露原始 HTTP 状态码、响应头和请求 ID。429 背后的限制请参阅 速率限制。

​
版本控制与支持

  • SDK 遵循语义化版本控制，并对 API 变更采用一项规则。镜像 Didit API 的变更作为次版本发布，即使它可能破坏有类型约束的代码（字段类型变化、字段可以为 null，或移除了端点、字段或枚举值）。API 对所有调用方都已如此表现，因此旧版 SDK 版本并不更安全。发布说明会在 “API changes that can break typed code” 下列出此类变更。
  • 主版本仅用于 SDK 自身设计的变更：在 API 保留某方法或资源时将其重命名或移除，修改客户端配置、错误、重试、分页或 Webhook 验证行为，或放弃某个运行时版本。当端点从 API 中移除或其方法被重命名时，旧方法至少保留一个次版本，并标记为已弃用，以便您的代码在迁移到新方法期间仍可构建。每种语言保留各自的版本号：Node.js、PHP 和 Ruby 为 2.x，其余为 1.x，因为这三者在本规则适用之前曾把 API 变更作为主版本发布。
  • SDK 根据已发布的 API 合约（openapi-25.json 和 openapi-auth.json）生成，其 Didit Authentication 方法会与 openapi-authentication.json 对照检查。三份合约每天都会检查，因此新的端点或字段会随七种 SDK 的常规发布一同到达。
  • 每个 SDK 支持表中列出的最低运行时版本及其之后的所有版本。其测试会在最低版本及之后的每个版本上运行；Node.js 和 Java 则在每个长期支持版本上运行。
  • 每个仓库的 CHANGELOG.md 都列出了每个版本的变更。
  • 请通过 SDK 仓库的安全公告私下报告安全问题，或发送邮件至 support@didit.me。
最后修改于 2026年11月7日