> ## 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 Ruby SDK: KYC, AML 스크리닝, 거래 모니터링 연동

> Didit 공식 Ruby SDK 퀵스타트입니다. net/http 기반 서버 API 호출, Rails에 적합한 webhook 검증, 인증 token 확인 방법을 안내합니다.

Ruby용 Didit 공식 젬입니다. Ruby 3.1 이상이 필요하며 표준 라이브러리의 `net/http`를 사용합니다. 모든 SDK가 공유하는 내용은 [서버 SDK 개요](https://docs.didit.me/ko/integration/server-sdks/overview.md)를 참고하세요.

## 설치

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

이 젬은 [RubyGems의 `didit-sdk`](https://rubygems.org/gems/didit-sdk)입니다. 소스 코드와 변경 로그는 GitHub의 [didit-protocol/sdk-ruby](https://github.com/didit-protocol/sdk-ruby)에 있습니다.

또는 Gemfile에 `gem "didit-sdk"`를 추가하고 `bundle install`을 실행하세요. `require "didit"`로 로드합니다.

## 클라이언트 구성

`Didit::Client.new`는 환경 변수에서 `DIDIT_API_KEY`를 읽습니다. 이 값을 재정의하거나, 애플리케이션 범위 호출(케이스, 네트워크, 규제 보고서)에 필요한 조직 ID와 애플리케이션 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/ko/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/ko/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]`을 모두 전달하세요. 이벤트와 서명 방식은 [웹훅](https://docs.didit.me/ko/integration/webhooks.md) 페이지를 참고하세요.

## 거래 모니터링

결제, 출금 또는 암호화폐 이체를 [거래 모니터링](https://docs.didit.me/ko/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}"
```

## 인증 토큰 검증

`Didit::Authentication`은 [Authentication](https://docs.didit.me/ko/authentication/overview.md) 발급자가 서명한 액세스 토큰을 백엔드에서 검증하며, 요청마다 Didit을 호출하지 않습니다. 또한 코드 교환, 토큰 갱신, 세션 확인 및 해지, 단계 상향(step-up)도 실행합니다.

> [!NOTE]
>
> 토큰 검증은 애플리케이션의 발급자와 서명 키를 기준으로 [서버에서 토큰 검증하기](https://docs.didit.me/ko/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/ko/api-reference/overview.md)의 서버 엔드포인트 페이지에는 각 작업에 대한 Ruby 샘플이 있습니다. 다만 1.0.1 릴리스에 아직 없는 엔드포인트와 필드는 예외이며, 이는 [개요](https://docs.didit.me/ko/integration/server-sdks/overview.md)에 명시되어 있습니다.


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