메인 콘텐츠로 건너뛰기
PATCH
curl

이 기능의 역할

인증 세션은 신분증 인증/OCR, 라이브니스 감지, 얼굴 대조, AML, 주소 증명, 전화번호 인증 등 개별 기능(단계)으로 구성됩니다. 이 엔드포인트를 사용하면 그중 하나의 단계 상태를 Approved, Declined 또는 In Review로 설정할 수 있습니다. 세션 전체를 승인, 거부 또는 다시 열어야 할 때는 세션 상태 업데이트를 사용합니다. 단일 단계에 대한 결정만 기록하려는 경우에는 이 엔드포인트를 사용합니다. 예를 들어 자체 검토 워크플로에서 얼굴 대조 단계를 Declined로 표시하는 경우가 있습니다. 이미 결정이 내려진 세션은 그 결정을 유지하며, 변경되는 것은 해당 단계뿐입니다. 세션에 아직 결정이 없고 워크플로가 바로 이 단계를 기다리고 있다면, 재정의를 적용하면 해당 단계를 정상적으로 완료했을 때와 같이 단계가 완료됩니다. 워크플로는 다음 단계로 넘어가고, 이후 단계가 실행되며, 상태 노드가 세션 결정을 설정하고 status.updated webhook을 발생시킬 수 있습니다.

node_id로 단계 지정하기

그래프 기반 워크플로에서 각 단계에는 node_id가 있습니다(예: feature_ocr_1, feature_liveness_1, feature_aml_1). 이 값은 세션 결정에서 확인할 수 있으며, V3 결정의 각 기능에는 해당 기능의 node_id가 포함되어 있습니다. 그래프가 아닌(단일 단계) 워크플로에서는 기반 기능에 노드 ID가 없습니다. 이 경우 nodeId에 리터럴 값 default를 전달하여 해당 기능을 지정합니다. 이러한 워크플로의 어떤 단계에도 노드 ID가 없으므로 feature_type(예: LIVENESS, AML 또는 FACE_MATCH)도 함께 전달하여 대상 단계를 지정해야 합니다. 알 수 없는 feature_type을 전달하면 400이 반환됩니다.

사용자가 흐름을 마칠 때까지 기다리기

기본적으로 재정의는 즉시 적용됩니다. 사용자가 아직 흐름을 진행 중이라면 실행 중인 흐름의 단계가 변경되며, 이 경우 재정의는 forced: true와 함께 기록됩니다. 대신 기다리려면 defer_until_flow_finishes: true를 설정합니다. 세션이 Not Started, In Progress 또는 Resubmitted 상태이고 사용자가 흐름을 아직 마치지 않은 동안에는 재정의가 pending_until_flow_finishes로 저장됩니다. 재정의는 사용자가 흐름을 마칠 때, 즉 흐름이 자체 결정에 도달한 뒤에 적용됩니다. 이미 종료된 흐름의 세션에서는 어느 경우든 즉시 적용됩니다. 대기 중인 재정의는 다음의 경우 적용되지 않고 취소됩니다.
  • 사용자가 흐름을 마치기 전에 단계를 다시 수행하는 경우(check_changed)
  • 같은 단계에 대해 더 새로운 재정의가 이를 대체하는 경우(replaced)
  • 세션이 흐름을 끝내지 못하고 중단됨, 만료됨 또는 흐름 도중 결정됨 상태로 종료되는 경우(session_closed)
  • 기능 재정의 취소로 직접 취소하는 경우(cancelled_by_reviewer)
응답의 override에서 결과를 확인할 수 있습니다. state는 applied 또는 pending_until_flow_finishes이며, 재정의가 적용되면 applied_at이 설정됩니다. 최상위 new_status는 해당 단계에 저장된 상태이므로, 재정의가 대기하는 동안에도 변경되지 않습니다. 세션의 모든 재정의와 사용자가 아직 흐름 안에 있는지 여부를 보려면 기능 재정의 목록을 사용합니다.

KYC 및 KYB 지원

사용자 인증(KYC) 및 기업 확인(KYB) 세션 모두에서 동일하게 작동하며, Didit은 두 유형 모두에서 sessionId를 조회합니다. 지원되는 단계 유형은 신분증 인증/OCR, 라이브니스 감지, 얼굴 대조, NFC, AML, 주소 증명, 전화번호 인증, 이메일 인증, 데이터베이스 검증, 설문지 및 KYB 법인 등기부, 문서, 주요 인물 확인입니다.
독립형 API 세션(독립형 인증 API로 생성된 세션, session_type = API)은 개별 기능 상태를 변경할 수 없으며, 이 경우 엔드포인트는 400을 반환합니다.

예시

업데이트 후 일어나는 일

  • Webhook: 재정의가 즉시 적용되거나 흐름이 끝나 적용될 때 data.updated 이벤트가 발생합니다. 대기 중이거나 취소된 경우에는 아무것도 전송되지 않습니다.
  • 활동: 모든 재정의는 세션의 활동에 FEATURE_OVERRIDE_PENDING, FEATURE_OVERRIDE_APPLIED 또는 FEATURE_OVERRIDE_CANCELLED로 기록되며, 행위자(API 키, 사용자, 또는 대기 중인 재정의가 적용될 때는 시스템)가 함께 기록됩니다. 요청에 대한 항목에는 comment로 입력한 내용이 사유로 포함됩니다. 세션 결정의 reviews 배열에서 이 항목들은 new_status: null로 표시되며, 요청 항목의 사유는 comment에 들어 있습니다.
  • 세션 결정: 이미 결정이 내려진 세션은 그 결정을 유지합니다. 최종 결정을 변경하려면 세션 상태 업데이트를 별도로 호출합니다.

권한

write:sessions 권한이 필요하며, 클라이언트 API 키(x-api-key) 또는 사용자 인증 헤더 중 하나를 사용할 수 있습니다. 범위가 지정된 API 키에는 결정에 대한 쓰기 권한이 있어야 합니다.

관련 문서

인증

x-api-key
string
header
필수

Business Console의 Developers -> API keys에서 발급받은 귀하 애플리케이션의 API 키입니다. 기본 키는 전체 접근 권한을 갖습니다. 이름이 지정된 키는 리소스별 none, read, write 범위로 권한을 제한할 수 있으며 특정 워크플로나 승인된 세션, IP 주소 목록, 만료일 등으로 제한할 수도 있습니다. 401은 키가 잘못되었거나 폐기되었거나 만료되었음을 의미합니다. 403은 키가 전송되지 않았거나, 키에 해당 리소스나 작업에 대한 접근 권한이 없거나, 요청이 허용된 IP 목록 외부 주소에서 발생했음을 의미합니다. 세션 경로에서의 404는 해당 세션이 키의 허용 워크플로 또는 상태 범위를 벗어났음을 의미합니다. 미디어 접근 권한이 없는 키는 이미지, 비디오, PDF URL을 null로 수신하며, 세션 write 권한이 없는 키는 세션 링크와 token을 null로 수신합니다. https://docs.didit.me/console/api-keys 를 참고하십시오.

경로 매개변수

sessionId
string<uuid>
필수

인증 세션의 UUID입니다. 사용자(KYC) 및 기업(KYB) 세션 ID를 모두 지원하며, 서비스는 두 세션 유형 전체에서 ID를 확인합니다.

예시:

"11111111-2222-3333-4444-555555555555"

nodeId
string
필수

업데이트할 기능의 워크플로 그래프 노드 ID입니다(예: feature_ocr_1). 기능에 노드 ID가 없는 비그래프(단일 단계) 워크플로의 경우 리터럴 값 default를 사용하십시오.

예시:

"feature_ocr_1"

본문

application/json
new_status
enum<string>
필수

이 기능의 대상 상태입니다. 현재 값과 달라야 합니다.

사용 가능한 옵션:
Approved,
Declined,
In Review
예시:

"Approved"

comment
string

이 기능 변경에 대해 세션의 검토 기록에 기록되는 선택적 자유 텍스트 메모입니다.

예시:

"Document manually verified by compliance."

feature_type
enum<string>

대상으로 지정할 단계의 종류입니다. 모든 단계가 노드를 공유하지 않는 비그래프 워크플로(nodeId = default)에서 필요하며, 그렇지 않은 경우 선택 사항입니다. 알 수 없는 값은 400을 반환합니다.

사용 가능한 옵션:
ID_VERIFICATION,
OCR,
OCR_BACK,
NFC,
LIVENESS,
FACE,
AGE_ESTIMATION,
AGE_VERIFICATION,
FACE_SEARCH,
FACE_MATCH,
IP_ANALYSIS,
AML,
PHONE,
PHONE_VERIFICATION,
EMAIL,
EMAIL_VERIFICATION,
POA,
PROOF_OF_ADDRESS,
DATABASE_VALIDATION,
DATA_VALIDATION,
QUESTIONNAIRE,
DOCUMENT_AI,
KYB_REGISTRY,
KYB_DOCUMENTS,
KYB_KEY_PEOPLE,
BANK_VERIFICATION,
GEOLOCATION
예시:

"LIVENESS"

defer_until_flow_finishes
boolean
기본값:false

사용자가 아직 플로우에 있는 동안 재정의를 즉시 적용하는 대신 pending_until_flow_finishes로 저장하고 플로우가 끝날 때 적용합니다. 생략하거나 false로 설정하면 재정의가 즉시 적용됩니다. 플로우가 이미 종료된 세션의 경우 어느 쪽이든 즉시 적용됩니다.

예시:

false

응답

오버라이드가 기록되었습니다. new_status는 저장된 검사 상태입니다. 오버라이드가 적용되면 요청된 상태가 되고, 흐름이 완료되기를 기다리는 동안에는 변경되지 않은 상태가 됩니다. override는 어떤 경우가 발생했는지를 나타냅니다.

session_id
string<uuid>
필수
node_id
string | null
필수

업데이트된 단계의 워크플로 노드이거나, 노드가 없는 단계(비그래프 워크플로의 default 경로)의 경우 null입니다.

예시:

"feature_ocr_1"

feature_type
string
필수

업데이트된 기능의 모델 이름입니다(예: KYC, Face, FaceMatch, AML, POA).

예시:

"KYC"

new_status
string
필수

검사의 저장된 상태입니다. 재정의가 적용되면 요청된 상태가 되고, 재정의가 흐름 완료를 기다리는 동안에는 변경되지 않은 상태가 됩니다.

예시:

"Approved"

override
object
필수

PATCH /v3/session/{sessionId}/features/{nodeId}/update-status/로 수행된 검사(기능) 상태의 재정의 항목 하나입니다. 변경 내용, 적용 여부 또는 사용자가 플로우를 완료할 때까지 대기 중인지 여부, 요청한 주체 및 사유를 포함합니다.

마지막 수정일 2026년 11월 7일