> ## 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 Python SDK：KYC、AML 与交易监控

> Didit 官方 Python SDK 快速入门，提供同步与异步类型化客户端，用于服务端 API、Webhook 验证和认证 token 检查。

Didit 官方的 Python 库。它需要 Python 3.10 或更高版本，提供同步客户端 `Didit` 和异步客户端 `AsyncDidit`，两者方法相同。有关所有 SDK 共享的内容，请参阅[服务端 SDK 概览](https://docs.didit.me/zh/integration/server-sdks/overview.md)。

## 安装

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

该软件包在 PyPI 上名为 [`didit-sdk`](https://pypi.org/project/didit-sdk/)。其源代码和变更日志位于 GitHub 上的 [didit-protocol/sdk-python](https://github.com/didit-protocol/sdk-python)。

要验证 [Authentication](#验证-authentication-令牌) 令牌，请安装用于添加签名检查的额外依赖项：

```bash theme={null}
pip install "didit-sdk[auth]"
```

## 配置客户端

`Didit()` 会从环境变量中读取 `DIDIT_API_KEY`。如需覆盖该设置，或设置应用范围调用（案件、网络、监管报告）所需的组织和应用 ID，请传入选项。

```python theme={null}
import os

from didit import Didit

client = Didit(
    api_key=os.environ["DIDIT_API_KEY"],
    organization_id=os.environ.get("DIDIT_ORGANIZATION_ID"),
    application_id=os.environ.get("DIDIT_APPLICATION_ID"),
    timeout=30,
    max_retries=2,
)

# Options for a single call.
fast = client.with_options(timeout=5, max_retries=0)
```

## 创建会话

为工作流创建[验证会话](https://docs.didit.me/zh/sessions-api/create-session.md)，并引导用户访问其 URL。

```python theme={null}
from didit import Didit

client = Didit()

session = client.sessions.create(
    workflow_id="11111111-2222-3333-4444-555555555555",
    vendor_data="user-123",
    callback="https://example.com/verification/done",
)
print(session.url)
```

## 读取决策

用户完成操作后（或 Webhook 到达时），[读取决策](https://docs.didit.me/zh/sessions-api/retrieve-session.md)。每个功能结果都是一个列表，每个工作流节点对应一个条目。

```python theme={null}
from didit import Didit

client = Didit()

decision = client.sessions.retrieve_decision("11111111-2222-3333-4444-555555555555")
print(decision.status)
for verification in decision.id_verifications or []:
    print(verification.first_name, verification.last_name)
```

## 验证 Webhook

传入确切的原始请求体字节和请求头。对于任何无效或过期的投递，`verify` 都会抛出 `WebhookVerificationError`，因此只需捕获该类即可。

```python theme={null}
import os

import didit

WEBHOOK_SECRET = os.environ["DIDIT_WEBHOOK_SECRET"]


def handle_webhook(raw_body: bytes, headers: didit.webhooks.HeadersLike) -> int:
    try:
        event = didit.webhooks.verify(raw_body, headers, WEBHOOK_SECRET)
    except didit.WebhookVerificationError as error:
        print("rejected:", error.reason)
        return 400
    if isinstance(event, didit.webhooks.SessionStatusUpdatedEvent):
        print(event.session_id, event.status)
    return 200
```

在 Flask 中为 `handle_webhook(request.get_data(), dict(request.headers))`；在 FastAPI 中为 `handle_webhook(await request.body(), request.headers)`。轮换密钥期间，请同时传入两者：`[new_secret, old_secret]`。有关事件和签名方案，请参阅 [Webhook](https://docs.didit.me/zh/integration/webhooks.md)。

## 筛查交易

将付款、提现或加密货币转账提交至[交易监控](https://docs.didit.me/zh/transaction-monitoring/overview.md)；响应中包含其状态和风险评分。

```python theme={null}
from didit import Didit

client = Didit()

transaction = client.transactions.create(
    transaction_id="txn-1001",
    transaction_category="finance",
    transaction_details={"direction": "outbound", "amount": 1500, "currency": "EUR"},
    subject={"entity_type": "individual", "vendor_data": "user-123", "full_name": "Maria Garcia"},
)
print(transaction.status, transaction.score)
```

## 验证 Authentication 令牌

`didit.authentication` 会在您的后端检查您的 [Authentication](https://docs.didit.me/zh/authentication/overview.md) 颁发方签名的访问令牌，无需为每个请求调用 Didit。它还可以交换代码、刷新令牌、检查和撤销会话，并运行升级验证。

> [!NOTE]
>
> 令牌验证会针对您应用的颁发方和签名密钥，执行[在服务器上验证令牌](https://docs.didit.me/zh/authentication/tokens-and-jwks.md#在服务器上验证令牌)中列出的检查。

```python theme={null}
from didit.authentication import Authentication, TokenVerificationError

# The publishable key (pk_live_... or pk_test_...) carries your issuer URL.
auth = Authentication.from_publishable_key("pk_live_...", client_id="your-application-id")


def current_user(access_token: str) -> str | None:
    try:
        claims = auth.verify_access_token(access_token)
    except TokenVerificationError as error:
        print("rejected:", error.reason)
        return None
    return claims.sub
```

## 错误

```python theme={null}
import didit
from didit import Didit

client = Didit()

try:
    client.sessions.retrieve_decision("11111111-2222-3333-4444-555555555555")
except didit.NotFoundError:
    print("no such session")
except didit.RateLimitError as error:
    print("slow down, request", error.request_id)
except didit.APIStatusError as error:
    print(error.status_code, error.body)
```

## 列表、文件和异步

```python theme={null}
import asyncio
from pathlib import Path

from didit import AsyncDidit, Didit

client = Didit()

# Lists page through every result.
for session in client.sessions.list(status="Approved"):
    print(session.session_id)

# Uploads take a path, bytes or an open file.
result = client.id_verification.verify(front_image=Path("id-front.jpg"), back_image=Path("id-back.jpg"))
print(result.id_verification)


async def main() -> None:
    async with AsyncDidit() as aclient:
        session = await aclient.sessions.create(workflow_id="11111111-2222-3333-4444-555555555555")
        print(session.url)


asyncio.run(main())
```

您可以在 [API 参考](https://docs.didit.me/zh/api-reference/overview.md)的服务端 endpoint 页面中找到其操作的 Python 示例，但尚未在任何 1.0.1 版本中提供的端点和字段除外，它们列在[概览](https://docs.didit.me/zh/integration/server-sdks/overview.md)中。


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