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

# 관리 API v3: 워크플로 및 결제

> API 키로 워크플로, 설문지, 사용자, 결제, 차단 목록을 설정하세요. 에이전트 네이티브 및 MCP 지원. Didit의 사용량 기반 요금, 계약 없음.

## 인증

모든 관리 API endpoint는 애플리케이션 API 키를 사용합니다. URL에 조직 또는 애플리케이션 UUID를 넣을 필요가 없으며, 애플리케이션은 API 키로 식별됩니다.

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...
```

아직 API 키가 없으신가요? [API 호출 2회로 프로그래밍 방식 등록하기](https://docs.didit.me/ko/integration/programmatic-registration.md).

***

## 워크플로

워크플로는 사용자가 거치는 인증 단계를 정의합니다(신분증 스캔, 라이브니스 감지, 얼굴 대조, AML 스크리닝 등). 각 워크플로는 세션에 연결해 재사용할 수 있는 구성입니다.

**GET /v3/workflows/** `GET`

애플리케이션의 모든 워크플로를 나열합니다. 각 워크플로의 기능, 임계값, 기본 워크플로 여부를 반환합니다.

**POST /v3/workflows/** `POST`

새 워크플로를 생성합니다. 사용할 인증 기능을 정의하고, 임계값을 설정하고, 허용할 문서 유형 등을 구성합니다.

**GET /v3/workflows/\{uuid}/** `GET`

특정 워크플로의 전체 세부 정보를 가져옵니다. 모든 기능 구성과 임계값이 포함됩니다.

**PATCH /v3/workflows/\{uuid}/** `PATCH`

워크플로 구성을 업데이트합니다. 기능 설정, 임계값, 허용 문서를 자유롭게 수정할 수 있습니다.

**DELETE /v3/workflows/\{uuid}/** `DELETE`

워크플로를 삭제합니다. 이 워크플로를 이미 사용 중인 세션에는 영향을 주지 않습니다.

> [!WARNING]
>
> 워크플로를 생성하고 구성할 때는 **비즈니스 콘솔**을 사용하시기를 강력히 권장합니다. 시각적 워크플로 빌더에서는 템플릿, 드래그 앤 드롭 방식의 기능 구성, 문서 설정, 임계값 조정, 미리보기를 코드 작성 없이 사용할 수 있습니다. API는 워크플로를 자동화하거나 프로그래밍 방식으로 관리해야 할 때만 사용하십시오.

### 빠른 예시: 워크플로 생성

`workflow_type`은 기본 기능 세트를 결정합니다. 개별 기능은 `is_*_enabled` 플래그로 켜거나 끕니다.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/workflows/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "workflow_type": "kyc",
    "is_default": true,
    "is_face_match_enabled": true,
    "is_liveness_enabled": true,
    "is_aml_enabled": false
  }'
```

사용 가능한 `workflow_type` 값: `kyc`, `kyb`, `adaptive_age_verification`, `biometric_authentication`, `address_verification`, `questionnaire_verification`, `email_verification`, `phone_verification`.

`kyc` 워크플로에는 신분증 인증이 자동으로 포함되므로 이를 위한 별도 플래그는 필요하지 않습니다. 얼굴 대조, 라이브니스, AML, NFC, 전화번호, 이메일, 주소 증명, 기기 및 IP 분석 등 선택적 기능을 추가하거나 제거하려면 `is_*_enabled` 플래그를 사용하십시오.

그다음 세션을 생성할 때 해당 워크플로를 사용합니다.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/callback",
    "workflow_id": "WORKFLOW_UUID_FROM_ABOVE"
  }'
```

***

## 설문지

워크플로에 추가하여 사용자에게서 추가 정보를 수집할 수 있는 맞춤형 양식입니다.

**GET /v3/questionnaires/** `GET`

모든 설문지를 나열합니다.

**POST /v3/questionnaires/** `POST`

맞춤형 질문, 분기 로직, 번역본을 포함한 새 설문지를 생성합니다.

**GET /v3/questionnaires/\{uuid}/** `GET`

모든 질문과 양식 구조를 포함한 설문지 세부 정보를 가져옵니다.

**PATCH /v3/questionnaires/\{uuid}/** `PATCH`

설문지를 업데이트합니다.

**DELETE /v3/questionnaires/\{uuid}/** `DELETE`

설문지를 삭제합니다.

***

## 사용자

애플리케이션의 인증된 개인(사용자)을 관리합니다. 각 사용자는 세션을 생성할 때 제공하는 `vendor_data` 문자열로 식별됩니다.

**GET /v3/users/** `GET`

애플리케이션의 모든 사용자를 나열합니다. 인증 상태와 세션 이력이 포함됩니다.

**GET /v3/users/\{vendor\_data}/** `GET`

사용자의 vendor\_data 식별자로 사용자 세부 정보를 가져옵니다.

**PATCH /v3/users/\{vendor\_data}/** `PATCH`

사용자 메타데이터를 업데이트합니다.

**POST /v3/users/delete/** `POST`

사용자를 일괄 삭제합니다. 요청 본문: `{"vendor_data_list": ["user-1", "user-2"]}` 또는 `{"delete_all": true}`. 해당 사용자에 대해 보관 중인 생체 인식 템플릿도 모두 영구 삭제합니다.

***

## 생체 인식 템플릿

옵트인한 애플리케이션이 세션을 삭제한 후에도 보관하는, 이미지가 없는 얼굴 생체 인식 템플릿입니다. [생체 인식 템플릿](https://docs.didit.me/ko/management-api/biometric-templates/overview.md)을 참조하십시오.

**GET /v3/biometric-templates/** `GET`

필터(`vendor_data`, `vendor_user_uuid`, `status`, `source_type`, `retained_from`, `retained_to`, `ordering`)를 적용할 수 있는 페이지 단위 목록입니다.

**GET /v3/biometric-templates/count/** `GET`

같은 필터를 적용한 개수를 반환합니다.

**GET /v3/biometric-templates/\{template\_uuid}/** `GET`

템플릿 하나의 정보입니다. 소유 사용자, 출처 참조, 만료일, 지침, 상태가 포함됩니다.

**DELETE /v3/biometric-templates/\{template\_uuid}/** `DELETE`

템플릿 하나를 영구 삭제합니다. `{"uuid": "...", "outcome": "purged" | "already_purged"}`를 반환합니다.

**POST /v3/biometric-templates/delete/** `POST`

템플릿을 일괄 영구 삭제합니다. 요청 본문: `{"template_uuids": [...]}` 또는 `{"delete_all": true}`와 선택적 필터.

***

## 세션 작업

**POST /v3/sessions/delete/** `POST`

세션을 일괄 삭제합니다. `delete:sessions` 권한이 필요합니다. 요청 본문: `{"session_numbers": ["1", "2", "3"]}` 또는 `{"delete_all": true}`(`delete_all`은 `filter_`로 시작하는 세션 목록 필터, 예: `filter_status`로 좁힐 수 있습니다). 여기에 선택 항목으로 `retain_face_embeddings`, `face_retention_days`, `face_retention_deadline`, `deletion_instruction`, `instruction_id`를 함께 보낼 수 있습니다. 일치하는 세션이 최대 20개이면 세션별 `face_retention_outcome`과 함께 `200`을 반환합니다. 그보다 많으면 삭제 작업을 나타내는 `202`를 반환합니다.

**GET /v3/sessions/delete/\{job\_id}/** `GET`

`202`를 반환한 일괄 세션 삭제 작업의 진행 상황과 결과별 개수를 가져옵니다.

**GET /v3/sessions/\{uuid}/reviews/** `GET`

세션의 검토 목록과 활동 로그를 나열합니다.

**POST /v3/sessions/\{uuid}/reviews/** `POST`

세션에 검토 메모 또는 상태 변경을 추가합니다.

***

## 결제

**GET /v3/billing/balance/** `GET`

현재 크레딧 잔액과 자동 충전 설정을 조회합니다.

```json theme={null}
{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}
```

**POST /v3/billing/top-up/** `POST`

크레딧을 충전하기 위한 Stripe 결제 세션을 생성합니다. 충전 건당 금액은 \$50에서 \$20,000 사이이며, 액면가 그대로 추가됩니다.

```json theme={null}
{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}
```

***

## 목록(차단 목록, 허용 목록 및 사용자 정의)

차단 목록, 허용 목록, 사용자 정의 워크플로 조건에 사용하는 유형별 목록을 관리합니다. 전체 [Lists API 문서](https://docs.didit.me/ko/management-api/lists/overview.md)를 참조하세요.

**GET /v3/lists/** `GET`

애플리케이션의 모든 목록(차단 목록, 허용 목록, 사용자 정의)을 조회합니다.

**POST /v3/lists/\{list\_uuid}/entries/** `POST`

목록에 항목을 추가합니다. `reference_session_id`를 지정하면 세션에서 데이터를 자동으로 추출하고, `reference_object_uuid`를 지정하면 거래, 사용자, 기업과의 추적 연결을 설정할 수 있습니다.

**DELETE /v3/lists/\{list\_uuid}/entries/\{entry\_uuid}/** `DELETE`

목록에서 항목을 삭제합니다.

**POST /v3/lists/\{list\_uuid}/entries/face-upload/** `POST`

얼굴 차단 목록에 얼굴 이미지를 업로드합니다(base64).

***

## webhook 구성

**GET /v3/webhook/** `GET`

webhook URL, 버전, webhook 서명 검증용 시크릿 키, 애플리케이션의 데이터 보존 및 생체 인식 템플릿 보존 정책을 포함한 현재 webhook 구성을 조회합니다.
응답에는 아래 `PATCH /v3/webhook/`에서 설명하는 `allowed_domains`도 포함됩니다.

```json theme={null}
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null,
  "face_retention_policy": "delete_with_session",
  "face_retention_days": null,
  "allowed_return_hosts": ["app.example.com"],
  "allowed_domains": ["https://app.example.com"]
}
```

**PATCH /v3/webhook/** `PATCH`

webhook URL과 버전을 업데이트하거나 시크릿 키를 교체합니다. `rotate_secret_key: true`를 설정하면 새 webhook 시크릿이 생성되며, 기존 시크릿은 즉시 무효화됩니다. 또한 애플리케이션의 보존 정책을 설정합니다. 여기에는 `data_retention_months`와 `face_retention_policy`(기본값은 `delete_with_session`, 또는 `retain_until_user_deleted`)가 포함되며, 얼굴 보존이 활성화되면 `face_retention_days`(1\~3650)를 유한한 값으로 반드시 지정해야 합니다. 자세한 내용은 [생체 인식 템플릿 보존](https://docs.didit.me/ko/console/data-retention.md#생체-인식-템플릿-보존)을 참조하세요. 또한 `allowed_return_hosts`를 등록합니다. 이는 최대 20개의 호스트명으로, 스킴, 포트, 경로, 와일드카드 없이 입력합니다(예: `app.example.com`). [Digital ID wallet API](https://docs.didit.me/ko/standalone-apis/digital-id-wallets.md#반환-대상-등록) 검증 시 사용자는 이 호스트로 HTTPS를 통해 돌아갈 수 있습니다. 새 목록은 기존에 등록된 목록을 대체하며, 애플리케이션의 화이트 라벨 도메인은 항상 허용됩니다.

또한 `allowed_domains`를 설정합니다. 이는 호스팅 인증 흐름을 임베드할 수 있고, 세션 `callback`으로 사용자를 되돌려 보낼 수 있는 최대 50개의 웹 출처입니다(예: `https://app.example.com`).
각 항목은 스킴, 호스트, 선택적 포트로 구성되며, 경로, 쿼리, 와일드카드는 포함할 수 없습니다.
`https`를 사용하세요. `http`는 `localhost`, `127.0.0.1`, `::1`에 대해서만 허용됩니다.
Didit은 각 출처를 소문자로 저장하고 기본 포트 없이 저장하며, 목록은 `allowed_domains`에 반환됩니다.
`allowed_domains`에 잘못된 항목이 있으면 400 오류가 반환됩니다.
새 목록은 등록된 목록을 대체하며, 빈 목록은 제한을 제거합니다.
목록이 비어 있지 않은 동안 [`POST /v3/session/`](https://docs.didit.me/ko/sessions-api/create-session)은 목록에 없는 웹 `callback`을 400 오류로 거부하며, 호스팅 흐름은 저장된 콜백이나 워크플로 기본 콜백이 목록에 없으면 사용자를 해당 주소로 리디렉션하지 않습니다.
사용자 정의 URL 스킴(앱 딥 링크)과 서버 간 API 호출은 영향을 받지 않습니다.

`endpoints`를 보내면 목록에서 빠진 모든 webhook 대상이 영구적으로 삭제되며, 해당 서명 비밀 키와 전체 전송 로그도 함께 삭제됩니다. 이는 [`DELETE /v3/webhook/destinations/{destination_uuid}/`](https://docs.didit.me/ko/management-api/webhook/delete-destination)와 동일하게 작동합니다.
이 작업은 되돌릴 수 없습니다.
대상을 하나씩 관리하려면 [webhook 대상 엔드포인트](https://docs.didit.me/ko/management-api/webhook/list-destinations.md)를 사용하세요.

```json theme={null}
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "allowed_domains": ["https://app.example.com"]
}
```

***

## API 엔드포인트 전체 요약

| 엔드포인트 | 메서드 | 설명 |
| - | - | - |
| `/v3/session/` | POST | 인증 세션 생성 |
| `/v3/sessions/` | GET | 모든 세션 조회 |
| `/v3/session/{id}/decision/` | GET | 세션 인증 결과 조회 |
| `/v3/session/{id}/update-status/` | PATCH | 세션 승인 또는 거부 |
| `/v3/session/{id}/delete/` | DELETE | 단일 세션 삭제 |
| `/v3/sessions/delete/` | POST | 세션 일괄 삭제 |
| `/v3/sessions/delete/{job_id}/` | GET | 세션 일괄 삭제 작업 상태 |
| `/v3/sessions/{id}/reviews/` | GET, POST | 세션 활동/검토 |
| `/v3/workflows/` | GET, POST | 워크플로 목록 조회/생성 |
| `/v3/workflows/{id}/` | GET, PATCH, DELETE | 워크플로 상세/수정/삭제 |
| `/v3/questionnaires/` | GET, POST | 설문지 목록 조회/생성 |
| `/v3/questionnaires/{id}/` | GET, PATCH, DELETE | 설문지 상세 |
| `/v3/users/` | GET | 인증된 사용자 목록 조회 |
| `/v3/users/{vendor_data}/` | GET, PATCH | 사용자 상세/수정 |
| `/v3/users/delete/` | POST | 사용자 일괄 삭제(보존된 생체 인식 템플릿도 함께 완전 삭제) |
| `/v3/biometric-templates/` | GET | 보존된 생체 인식 템플릿 목록 조회 |
| `/v3/biometric-templates/count/` | GET | 보존된 생체 인식 템플릿 수 조회 |
| `/v3/biometric-templates/{id}/` | GET, DELETE | 템플릿 상세 / 완전 삭제 |
| `/v3/biometric-templates/delete/` | POST | 템플릿 일괄 완전 삭제 |
| `/v3/lists/` | GET, POST | 모든 목록 조회 / 목록 생성 |
| `/v3/lists/{id}/` | GET, PATCH, DELETE | 목록 상세 / 수정 / 삭제 |
| `/v3/lists/{id}/entries/` | GET, POST | 목록 항목 조회 / 항목 추가 |
| `/v3/lists/{id}/entries/{eid}/` | DELETE | 항목 삭제 |
| `/v3/lists/{id}/entries/face-upload/` | POST | 차단 목록에 얼굴 업로드 |
| `/v3/webhook/` | GET, PATCH | webhook 구성(URL, 시크릿, 버전), 보존 정책 및 지갑 반환 호스트 |
| `/v3/billing/balance/` | GET | 크레딧 잔액 조회 |
| `/v3/billing/top-up/` | POST | 크레딧 충전 |


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