> ## 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.

# Ruby SDK：KYC 与 AML 筛查集成

> Didit 官方 Ruby SDK 快速入门：基于 net/http 调用服务端 API，支持 Rails 友好的 Webhook 验证，以及认证 token 校验。

适用于 Ruby 的 Didit 官方 gem。需要 Ruby 3.1 或更高版本，并使用标准库中的 `net/http`。各 SDK 的共同内容，请参阅[服务端 SDK 概览](https://docs.didit.me/zh/integration/server-sdks/overview.md)。

## 安装

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

该 gem 为 [RubyGems 上的 `didit-sdk`](https://rubygems.org/gems/didit-sdk)。其源代码和变更日志位于 GitHub 上的 [didit-protocol/sdk-ruby](https://github.com/didit-protocol/sdk-ruby)。

或者，将 `gem "didit-sdk"` 添加到您的 Gemfile 中，然后运行 `bundle install`。使用 `require "didit"` 加载。

## 配置客户端

`Didit::Client.new` 会从环境变量中读取 `DIDIT_API_KEY`。如需覆盖该值，或设置应用级调用（案件、网络、监管报告）所需的组织和应用 ID，请传入关键字参数。请求字段是使用 API 原有名称的关键字参数；响应则是对象，每个字段都有对应的读取方法，并支持 `[:field]` 和 `to_h`。

```ruby theme={null}
require "didit"

didit = Didit::Client.new(
  api_key: ENV["DIDIT_API_KEY"],
  organization_id: ENV["DIDIT_ORGANIZATION_ID"],
  application_id: ENV["DIDIT_APPLICATION_ID"],
  timeout: 30,
  max_retries: 2
)

# Options for a single call.
decision = didit.with_options(timeout: 5, max_retries: 0).sessions.retrieve_decision("11111111-2222-3333-4444-555555555555")
puts decision.status
```

## 创建会话

为某个工作流创建[验证会话](https://docs.didit.me/zh/sessions-api/create-session.md)，然后将用户引导至该会话的 URL。

```ruby theme={null}
require "didit"

didit = Didit::Client.new

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

## 读取决策

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

```ruby theme={null}
require "didit"

didit = Didit::Client.new

decision = didit.sessions.retrieve_decision("11111111-2222-3333-4444-555555555555")
puts decision.status
(decision.id_verifications || []).each do |verification|
  puts verification.status
end
```

## 验证 Webhook

传入原始请求体（按接收时的原样）以及请求头。对于任何无效或过期的投递，`verify` 都会抛出 `Didit::WebhookVerificationError`；否则返回带类型的事件。

```ruby theme={null}
require "didit"

WEBHOOK_SECRET = ENV.fetch("DIDIT_WEBHOOK_SECRET", "")

def handle_webhook(raw_body, headers)
  event = Didit::Webhooks.verify(raw_body, headers, WEBHOOK_SECRET)
  case event
  when Didit::Webhooks::StatusUpdatedEvent
    puts "#{event.session_id} #{event.status}"
  end
  200
rescue Didit::WebhookVerificationError => e
  puts "rejected: #{e.reason}"
  400
end
```

在 Rails 中，调用 `handle_webhook(request.raw_post, request.headers)`。轮换密钥期间，请同时传入两者：`[new_secret, old_secret]`。事件和签名方案详见 [Webhooks](https://docs.didit.me/zh/integration/webhooks.md)。

## 筛查交易

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

```ruby theme={null}
require "didit"

didit = Didit::Client.new

transaction = didit.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" }
)
puts "#{transaction.status} #{transaction.score}"
```

## 验证 Authentication token

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

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

```ruby theme={null}
require "didit"

# Your issuer URL, or Didit::Authentication.from_publishable_key("pk_live_...", client_id: ...).
AUTH = Didit::Authentication.new("https://your-app.auth.didit.me", client_id: "your-application-id")

def current_user(access_token)
  AUTH.verify_access_token(access_token).sub
rescue Didit::TokenVerificationError => e
  puts "rejected: #{e.reason}"
  nil
end
```

## 错误

```ruby theme={null}
require "didit"

didit = Didit::Client.new

begin
  didit.sessions.retrieve_decision("11111111-2222-3333-4444-555555555555")
rescue Didit::NotFoundError
  puts "no such session"
rescue Didit::APIStatusError => e
  puts "#{e.status} #{e.request_id}"
end
```

## 列表和文件

```ruby theme={null}
require "didit"

didit = Didit::Client.new

# Lists page through every result.
didit.sessions.list(status: "Approved").auto_paging_each do |session|
  puts session.session_id
end

# Uploads take a Pathname, an IO or Didit::FilePart. A String is sent as the file's bytes.
result = didit.id_verification.verify(
  front_image: Pathname("id-front.jpg"),
  back_image: Pathname("id-back.jpg")
)
puts result.to_h
```

[API 参考](https://docs.didit.me/zh/api-reference/overview.md) 中的服务端端点页面都为其操作提供了 Ruby 示例，但 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.