> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Didit 服务端 SDK：Python、Node.js、Go、Java、PHP、Ruby、.NET

> 从后端调用 Didit 服务端 API，使用官方类型化 SDK。涵盖安装矩阵、配置、错误处理、重试、版本与支持政策。

服务端 SDK 是 Didit 官方为您的后端提供的库。每个 SDK 都使用类型化的请求和响应调用 [API 参考](https://docs.didit.me/zh/api-reference/overview.md) 中的服务端 endpoint，验证 Didit 发送给您的 Webhook，并验证 [Didit Authentication](https://docs.didit.me/zh/authentication/overview.md) 的 token。1.0.1 版本尚未包含两个 Google Wallet endpoint：[发起 Google Wallet 验证](https://docs.didit.me/zh/api-reference/digital-id-wallets/google-wallet.md)和[提交钱包响应](https://docs.didit.me/zh/standalone-apis/digital-id-wallet-response.md)。Python、Node.js、Java、PHP、Ruby 和 .NET SDK 包含其他所有服务端 endpoint。Go 1.0.1 还缺少另外九个 endpoint，其中大多数是 Travel Rule endpoint：请参阅[Go SDK 尚未提供的 endpoint](https://docs.didit.me/zh/integration/server-sdks/go.md#go-sdk-尚未支持的端点)。

只要您的代码持有 Didit API 密钥，就可以使用这些服务端 SDK：创建验证会话、读取决策、调用独立 API、管理用户、企业、工作流和案件、筛查交易和钱包，以及使用 Travel Rule。在浏览器或移动应用中，请改用 [Web](https://docs.didit.me/zh/integration/web-sdks/overview.md) 和[原生](https://docs.didit.me/zh/integration/native-sdks/overview.md) SDK：它们向用户展示验证流程，且从不持有您的 API 密钥。

[API 参考](https://docs.didit.me/zh/api-reference/overview.md)中的服务端 endpoint 页面（包括[数据库核验](https://docs.didit.me/zh/standalone-apis/database-validation.md)服务页面）会在 cURL 请求旁边显示每个服务端 SDK 的代码示例。只有当 SDK 的最新版本包含该 endpoint 以及示例发送的每个字段时，才会显示该示例：API 新增的 endpoint 或字段，会在各 SDK 的下一个版本中获得示例。1.0.1 版本的任何 SDK 都没有在生成之后新增的 16 个数据库核验请求字段（例如 `vin` 或 `bank_account_number`），因此发送这些字段的服务页面只显示 cURL。

## 安装

```bash Python theme={null}
pip install didit-sdk
```

```bash Node.js theme={null}
npm install @didit-protocol/sdk-node
```

```bash Go theme={null}
go get github.com/didit-protocol/sdk-go
```

```kotlin Java theme={null}
implementation("me.didit:didit-java:1.0.1")
```

```bash PHP theme={null}
composer require didit-protocol/sdk-php guzzlehttp/guzzle
```

```bash Ruby theme={null}
gem install didit-sdk
```

```bash .NET theme={null}
dotnet add package Didit
```

| 语言 | 软件包 | 源代码 | 最低运行环境 |
| - | - | - | - |
| [Python](https://docs.didit.me/zh/integration/server-sdks/python.md) | [PyPI `didit-sdk`](https://pypi.org/project/didit-sdk/) | [sdk-python](https://github.com/didit-protocol/sdk-python) | Python 3.10 |
| [Node.js 和 TypeScript](https://docs.didit.me/zh/integration/server-sdks/node.md) | [npm `@didit-protocol/sdk-node`](https://www.npmjs.com/package/@didit-protocol/sdk-node) | [sdk-node](https://github.com/didit-protocol/sdk-node) | Node.js 18、Bun、Deno，以及支持 `fetch` 的边缘运行时 |
| [Go](https://docs.didit.me/zh/integration/server-sdks/go.md) | [Go 模块 `github.com/didit-protocol/sdk-go`](https://pkg.go.dev/github.com/didit-protocol/sdk-go) | [sdk-go](https://github.com/didit-protocol/sdk-go) | Go 1.22 |
| [Java 和 Kotlin](https://docs.didit.me/zh/integration/server-sdks/java.md) | [Maven Central `me.didit:didit-java`](https://central.sonatype.com/artifact/me.didit/didit-java) | [sdk-java](https://github.com/didit-protocol/sdk-java) | Java 11 |
| [PHP](https://docs.didit.me/zh/integration/server-sdks/php.md) | [Packagist `didit-protocol/sdk-php`](https://packagist.org/packages/didit-protocol/sdk-php) | [sdk-php](https://github.com/didit-protocol/sdk-php) | PHP 8.1 |
| [Ruby](https://docs.didit.me/zh/integration/server-sdks/ruby.md) | [RubyGems `didit-sdk`](https://rubygems.org/gems/didit-sdk) | [sdk-ruby](https://github.com/didit-protocol/sdk-ruby) | Ruby 3.1 |
| [C# 和 .NET](https://docs.didit.me/zh/integration/server-sdks/dotnet.md) | [NuGet `Didit`](https://www.nuget.org/packages/Didit) | [sdk-dotnet](https://github.com/didit-protocol/sdk-dotnet) | .NET 8 或 .NET Standard 2.0 |

## 配置

每个 SDK 都读取相同的环境变量，因此不带任何选项创建的客户端即可直接使用。边缘运行时没有进程环境变量：此时请将 API 密钥作为选项传给 Node.js 客户端。

| 变量 | 用途 |
| - | - |
| `DIDIT_API_KEY` | 所有需要 API 密钥的调用。请在控制台的 [API 密钥](https://docs.didit.me/zh/console/api-keys.md)中创建该密钥。 |
| `DIDIT_ORGANIZATION_ID`、`DIDIT_APPLICATION_ID` | `/v3/organization/{organization_id}/application/{application_id}/` 下的操作（案件、网络、监管报告、报告模板，以及部分用户和企业工具）。SDK 会从客户端填充这两个路径 ID，因此您无需在每次调用时传入。缺少它们时，这些调用会在发送任何请求之前失败。 |
| `DIDIT_LOG=debug` | 记录每个请求的方法、路径、状态、耗时和请求 ID。请求正文和请求头永远不会被记录。 |

凡是可以通过环境变量设置的内容，也都可以传给客户端，包括基础 URL、超时、重试、默认请求头和您自己的 HTTP 客户端。请在每个进程中创建一个客户端并共享使用：它会维护连接池，可以安全地被多个线程或任务同时使用。

`account` 方法（[程序化注册](https://docs.didit.me/zh/integration/programmatic-registration.md)：注册、登录、组织和应用）会调用 `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](https://docs.didit.me/zh/integration/webhooks.md)。
* **认证。** `Authentication` 辅助工具用于验证您的 Authentication 颁发者签发的 访问 token 和 ID token，并调用其 token、会话和增强验证 endpoint。它从不使用您的 API 密钥。

## 错误、重试和超时

| 错误 | 触发条件 |
| - | - |
| `APIConnectionError`、`APITimeoutError` | 未收到任何响应 |
| `APIStatusError` | 任何其他非 2xx 响应，包含状态码、解析后的响应体、响应头和请求 ID |
| `BadRequestError` 400、`AuthenticationError` 401、`PermissionDeniedError` 403、`NotFoundError` 404、`ConflictError` 409、`UnprocessableEntityError` 422、`RateLimitError` 429、`InternalServerError` 5xx | `APIStatusError` 的子类 |
| `WebhookVerificationError` | 一次 Webhook 投递未通过验证；其 `reason` 说明原因 |
| `ConfigurationError` | 缺少 API 密钥、账户 token、组织 ID 或应用 ID |

所有错误都派生自 `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 背后的限制请参阅 [速率限制](https://docs.didit.me/zh/integration/rate-limiting.md)。

## 版本控制与支持

* 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`](https://docs.didit.me/openapi-25.json) 和 [`openapi-auth.json`](https://docs.didit.me/openapi-auth.json)）生成，其 [Didit Authentication](https://docs.didit.me/zh/authentication/overview.md) 方法会与 [`openapi-authentication.json`](https://docs.didit.me/openapi-authentication.json) 对照检查。三份合约每天都会检查，因此新的端点或字段会随七种 SDK 的常规发布一同到达。
* 每个 SDK 支持表中列出的最低运行时版本及其之后的所有版本。其测试会在最低版本及之后的每个版本上运行；Node.js 和 Java 则在每个长期支持版本上运行。
* 每个仓库的 `CHANGELOG.md` 都列出了每个版本的变更。
* 请通过 SDK 仓库的安全公告私下报告安全问题，或发送邮件至 [support@didit.me](mailto:support@didit.me)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.