메인 콘텐츠로 건너뛰기
POST
Python
이 가이드를 참고하면 다른 제공업체에서 Didit으로 데이터를 옮길 때 알맞은 가져오기 경로를 고를 수 있습니다. 고객이 “가져오기”라고 부르는 작업에는 서로 다른 두 가지가 있습니다.
  • 과거 인증 작업 가져오기: 완료된 KYC, KYB, 거래 모니터링 또는 워크플로 규칙 기록을 다시 만들어 Didit에서 기존 제공업체의 이력이 보이도록 합니다. POST /v3/session/imports/를 사용합니다.
  • 운영 데이터 가져오기: 향후 검사에서 Didit이 사용할 수 있도록 사용자, 기업, 프로필 얼굴, 차단 목록 항목 또는 허용 목록 항목을 생성합니다. 엔티티, 얼굴, 목록 API를 사용합니다.
인증 가져오기는 KYC와 KYB에 대해 session_type: "MIGRATED"인 과거 기록을 만듭니다. 이 가져오기는 최종 사용자에게 이메일을 보내지 않고, 사용자를 호스팅 인증 흐름으로 리디렉션하지 않으며, 원래 인증을 다시 실행하지 않습니다. 가져온 기록은 해당되는 경우 세션 목록, 엔티티 프로필, 거래 보기, GET /v3/session/{session_id}/decision/에 나타납니다.

어떤 가져오기를 사용해야 하나요?

사용자 또는 기업 프로필만 향후 검사에 필요하다면 과거 인증 세션을 가져오지 마세요. 사용자 또는 기업 엔티티 API를 사용합니다. 기존 제공업체의 결정, 문서 필드, 경고 또는 증거가 Didit에서 컴플라이언스 이력으로 보여야 한다면 POST /v3/session/imports/를 사용합니다.

제공업체별로 무엇을 이전할 수 있나요?

Didit은 표준 CSV 또는 NDJSON 파일을 받으므로, 데이터를 내보내고 변환하기만 하면 어느 제공업체에서든 이전할 수 있습니다. 가져오기 형식은 항상 Didit의 표준 스키마입니다.

이전 워크플로

  1. 이력, 프로필, 얼굴, 목록, 거래, 규칙 중 무엇을 가져올지 결정하십시오.
  2. 기존 제공업체에서 데이터를 직접 내보내십시오. 기존 제공업체의 API 키는 Didit에 보내지 마십시오.
  3. 제공업체 내보내기 데이터를 해당하는 Didit 표준 CSV 또는 NDJSON 템플릿으로 변환하십시오.
  4. 대규모 이전에는 NDJSON을 사용하고, 각각 독립적으로 재시도할 수 있는 파일로 나누십시오.
  5. 가져오기 작업을 생성하고 진행 상황을 확인하십시오.
  6. 행 오류를 조회하고, 실패한 행만 수정한 뒤 재시도하십시오. 모든 가져오기 작업은 자연 키인 외부 ID를 기준으로 멱등성이 보장됩니다.

가져오기 작업 생성

단일 multipart 요청으로 가져오기 작업을 생성하십시오:
소규모 스프레드시트 기반 이전에는 CSV를, 대규모 이전에는 NDJSON을 사용하십시오. 100k+ 행이라면 NDJSON이 스트리밍, 분할, 검증, 재시도에 더 편리합니다. 애플리케이션당 최대 4개의 가져오기 작업을 동시에 실행할 수 있으므로, 대규모 이전은 여러 파일로 나누고 파일마다 작업을 시작하십시오. 각 작업은 행의 미디어 파일을 병렬로 내려받습니다. 배포나 워커 재시작으로 중단된 작업은 마지막으로 가져온 행부터 자동으로 이어서 진행되므로, 직접 다시 시작할 필요가 없습니다. 거래 가져오기의 경우 workflow_id를 생략하십시오:

요청 필드

기록 추적 및 중복 제거 방식

데이터 소스를 지정하는 요청 필드는 없습니다. 모든 가져오기는 Didit의 표준 스키마를 사용합니다. 가져온 각 기록은 추적을 위해 metadata.imported_from = "generic"을 저장합니다. user_verification과 business_verification 가져오기는 애플리케이션 내에서 external_id를 기준으로 행의 중복을 제거하므로, 같은 파일을 다시 시도해도 중복이 생기지 않습니다. transactions 가져오기는 대신 transaction_id를 기준으로 중복을 제거합니다. 제공업체 이전(source=provider)은 각 기록을 <provider>:<id> 형식으로 저장합니다. 예를 들어 sumsub:5f8c0e2a9b1d4c3e2f1a0b9c와 같습니다. 제공업체의 순수 ID(5f8c0e2a9b1d4c3e2f1a0b9c)를 전송한 사용자 인증 파일 가져오기는 두 방향 모두에서 같은 기록으로 인식됩니다. 따라서 파일로 이전을 시작하고 제공업체 이전으로 마무리하거나, 그 반대로 진행해도 기록이 두 번 가져와지지 않습니다.

문서 사진, 영상, 셀피 증거 가져오기

import_type=user_verification의 경우, 이전 제공업체의 원본 문서 사진, 문서/라이브니스 촬영 영상, 셀피 이미지를 가져올 수 있습니다. 다음 표준 열을 사용합니다: 대용량 마이그레이션에는 HTTPS URL을 사용합니다. Didit은 각 파일을 다운로드하고, URL이 안전한지 검증한 뒤, Didit이 소유하는 사본을 저장하고 이를 가져온 세션에 연결합니다. 이미지는 압축되고, 영상은 원본 그대로 저장됩니다. 소규모 가져오기에서는 이미지에 한해 base64 인라인 전달을 허용하지만, 영상은 반드시 URL로 제공해야 합니다. base64를 사용하면 각 영상의 크기가 약 33% 늘어나 파일당 가져오기 한도를 쉽게 초과하기 때문입니다. 제공업체가 호스팅하는 미디어 URL이 포함된 NDJSON 행 예시:
중요한 미디어 규칙:
  • URL은 https를 사용해야 합니다.
  • URL은 사설 IP, localhost, 링크 로컬 범위, 내부 메타데이터 호스트로 해석되면 안 됩니다.
  • 이미지는 URL 열 또는 해당하는 *_base64 대체 열 중 하나를 사용할 수 있습니다. 둘 다 설정된 경우 base64가 우선합니다. 영상은 URL만 사용할 수 있으며 *_video_base64 열은 없습니다.
  • 영상은 mp4, webm, mov 형식이어야 하며, 각 영상은 최대 10 MB까지 가능합니다. 더 크거나 영상이 아닌 파일은 행 오류로 거부됩니다.
  • Didit은 연결/읽기 시간 제한과 최대 파일 크기를 적용하고, 무한 재시도를 방지합니다.
  • 미디어 다운로드 실패는 행 오류로 저장되므로 나머지 가져오기는 계속 진행됩니다.
  • 제공업체에 미디어가 없다면 이 열들을 비워 둡니다. Didit은 여전히 구조화된 결정 및 문서 필드를 가져옵니다.
  • 가져온 이미지와 영상은 과거 검토를 위한 증거입니다. Didit은 기본적으로 가져온 과거 미디어에 대해 OCR, 라이브니스, 문서 위조 분석을 다시 실행하지 않습니다.

진행 상황 조회

응답에는 status, import_type, total_rows, processed_rows, created_count, updated_count, skipped_count, failed_count, checkpoint_row가 포함됩니다.

행 오류 다운로드

각 오류에는 row_number, external_id, error, raw_row가 포함되므로, 실패한 행만 수정하고 재시도할 수 있습니다.

남용 방지

POST /v3/session/imports/를 통한 과거 데이터 가져오기 작업은 기본적으로 비활성화되어 있습니다. Didit은 이러한 작업이 수백만 행을 처리하고 미디어를 다운로드할 수 있기 때문에, 검토 후 조직 단위로 이 기능을 활성화합니다. 이 가이드의 일반 운영 데이터 가져오기, 즉 사용자 생성, 기업 생성, 프로필 얼굴 업로드, 얼굴 차단 목록 업로드, 목록 항목 추가는 해당 엔드포인트의 일반 API 키 권한, 제품 제공 여부, 속도 제한 외에 별도의 마이그레이션 활성화가 필요하지 않습니다. 과거 데이터 가져오기 작업은 또한 격리된 워커에서 실행되며, 파일 크기 제한, 행 처리 한도, HTTPS 전용 미디어 URL, 비공개 네트워크 URL 차단, 애플리케이션당 활성 가져오기 작업 4개 제한, 행별 오류 기록이 적용됩니다.

표준 상태

멱등성

Didit은 사용자 인증 및 기업 확인(KYB) 가져오기에서 external_id를 가져오기 멱등성 키로 사용하며, 이는 애플리케이션 단위로 범위가 지정됩니다. 거래 가져오기는 애플리케이션별 transaction_id를 사용합니다. 같은 파일을 다시 시도하면 이미 가져온 행은 건너뛰고, 아직 처리되지 않은 행은 새로 생성합니다.

사용자, 프로필 얼굴, 차단 목록 가져오기

완료된 인증 세션을 다시 만들지 않는 경우에는 다음 경로를 사용합니다.

사용자 프로필 가져오기

POST /v3/users/create/ 또는 사용자 가져오기 및 내보내기의 Business Console CSV 가져오기로 사용자를 생성합니다. 이 작업은 VendorUser 프로필만 생성하거나 업데이트합니다. 인증 세션, KYC 결정, 문서 보고서, 경고, webhook 기록은 생성하지 않습니다. Didit이 향후 검사 전에 고객의 존재를 알아야 하거나 display_name, 태그, 메타데이터처럼 CRM과 유사한 필드를 나중에 채워 넣어야 할 때 이 방법을 사용합니다.

신뢰할 수 있는 프로필 얼굴 업로드

사용자가 생성된 후에는 POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/를 사용하여 신뢰할 수 있는 프로필 얼굴을 업로드합니다. 이 작업은 생체 증거를 사용자 프로필에 연결하고 중복 감지와 얼굴 검색을 위해 색인합니다. 이 작업은 얼굴을 차단 목록에 추가하지 않습니다. 이전 KYC 제공업체의 신뢰할 수 있는 프로필 이미지가 있고 향후 Didit 검사에서 이를 비교 대상으로 사용하려는 경우에 유용합니다.

얼굴 차단 목록 및 허용 목록 가져오기

얼굴을 직접 차단하거나 허용하려면 얼굴 유형 목록과 함께 POST /v3/lists/{list_uuid}/entries/face-upload/를 사용합니다. Didit이 생체 임베딩을 추출하고 목록 항목을 저장합니다. 알려진 사기꾼의 이미지, 허용 목록에 추가할 신뢰할 수 있는 얼굴, 또는 제공업체 사기 목록 마이그레이션에 이 방법을 사용합니다. 얼굴이 기존 Didit 세션에서 온 경우에는 reference_session_id와 함께 POST /v3/lists/{list_uuid}/entries/를 사용하는 것이 좋습니다. 이 경우 Didit이 세션에서 올바른 얼굴을 추출하고 항목을 원본에 다시 연결합니다.

사용자, 기업, 문서, 지갑, 이메일, 전화번호, IP, 기기 목록 가져오기

얼굴이 아닌 목록 값에는 POST /v3/lists/{list_uuid}/entries/를 사용합니다. 제공업체 차단 목록, 허용 목록, 차지백 목록, 지갑 주소, 알려진 위험 IP, 기기 지문, 문서 번호, 이메일, 전화번호, 사용자 또는 기업을 가져올 때 적합한 경로입니다.

다음 단계

사용자 가져오기

사용자 프로필을 불러오고 신뢰할 수 있는 프로필 얼굴을 연결합니다.

기업 가져오기

KYB를 실행하기 전에 기업 프로필을 불러옵니다.

프로필 얼굴 업로드

가져온 사용자에게 신뢰할 수 있는 얼굴 이미지를 연결합니다.

목록에 얼굴 업로드

차단 목록 또는 허용 목록에 얼굴을 추가합니다.

목록 항목 생성

전화번호, 이메일, 지갑, 문서, IP, 기기, 사용자 또는 기업을 목록으로 가져옵니다.

속도 제한

안전한 마이그레이션 루프와 재시도를 설계합니다.

인증

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 를 참고하십시오.

본문

import_type
enum<string>
기본값:user_verification

가져올 항목: 이전 사용자 인증 세션, 이전 기업 확인 세션, 워크플로 커스텀 상태 규칙, 또는 이전 거래 모니터링 기록.

사용 가능한 옵션:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

가져온 세션이나 상태 규칙을 연결할 워크플로 UUID입니다. user_verification, business_verification, status_rules의 경우 필수입니다. 거래(transactions)의 경우 생략합니다.

source_format
enum<string>

선택 사항입니다. 생략 시 업로드된 파일 확장자에서 유추됩니다.

사용 가능한 옵션:
csv,
ndjson
file
file

표준 CSV 또는 NDJSON 파일입니다. 대용량 가져오기에는 NDJSON을 사용하십시오. 최대 업로드 크기는 25MB입니다(더 큰 파일에는 source_file_url 사용). source_file_url과 상호 배타적입니다.

source_file_url
string<uri>

파일 업로드의 대안입니다. 공인 주소로 확인되는 HTTPS URL이어야 합니다(사설/루프백 네트워크는 거부됨). file과 상호 배타적입니다.

source
enum<string>

provider는 다른 신분증 인증 공급자로부터의 마이그레이션을 의미합니다. 파일 가져오기의 경우 생략하십시오.

사용 가능한 옵션:
file,
provider
provider
enum<string>

GET /v3/session/imports/providers/에서 가져온 마이그레이션 소스입니다. source가 provider인 경우 필수입니다.

사용 가능한 옵션:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

credential_fields에 나열된 필드 이름을 포함하는 공급자의 읽기 전용 키입니다. 저장 시 암호화되고, 반환되지 않으며, 가져오기가 끝나면 삭제됩니다. multipart에서 JSON 문자열로 전송하십시오.

options
object
status_mapping
object

제공업체의 기본 상태 매핑(소스 상태에서 Didit 상태로)을 수정합니다. Not Finished 및 Abandoned는 건너뛰고 카운트되며 가져오지 않습니다.

dry_run
boolean
기본값:false

마이그레이션 시 가져올 대상을 계산하고(상태별, 이미 Didit에 존재함, 동일인, 완료되지 않음) 아무것도 기록하지 않습니다. 작업은 READY 상태로 종료되며, POST /v3/session/imports/{importId}/start/로 시작합니다.

face_templates
boolean
기본값:false

가져온 셀피로 얼굴 템플릿을 생성하고 애플리케이션의 얼굴 및 차단 목록과 대조하여 검색합니다. 일치 항목은 검토용으로만 플래그가 지정됩니다. lawful_basis_confirmed가 필요합니다.

lawful_basis_confirmed
boolean
기본값:false

처리자로서 Didit과 해당 셀피를 공유할 수 있는 적법한 근거가 있음을 확인합니다.

응답

가져오기 작업이 접수되었습니다. status가 COMPLETED 또는 FAILED가 될 때까지 반환된 uuid를 폴링하십시오.

uuid
string<uuid>
필수

가져오기 작업 ID입니다. 이 값을 사용하여 진행 상황을 폴링하고 행 오류를 조회하십시오.

status
enum<string>
필수
사용 가능한 옵션:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
필수
사용 가능한 옵션:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
필수
사용 가능한 옵션:
csv,
ndjson
source_filename
string
필수
total_rows
integer<int64>
필수
processed_rows
integer<int64>
필수
created_count
integer<int64>
필수
updated_count
integer<int64>
필수
skipped_count
integer<int64>
필수
failed_count
integer<int64>
필수
checkpoint_row
integer<int64>
total_media_bytes
integer<int64>
last_error
string | null
created_at
string<date-time>
updated_at
string<date-time>
started_at
string<date-time> | null
completed_at
string<date-time> | null
state
enum<string>

콘솔에 표시되는 작업 상태입니다. errors는 거부된 행이 포함된 완료된 작업입니다.

사용 가능한 옵션:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
사용 가능한 옵션:
file,
api,
provider
provider
string

마이그레이션 소스입니다. 파일 또는 API 가져오기의 경우 비어 있습니다.

provider_options
object
credential_hint
string

마이그레이션이 보유한 키의 첫 몇 글자입니다. 키 자체는 절대 반환되지 않습니다.

credentials_expires_at
string<date-time> | null
resumes_at
string<date-time> | null

제공업체의 속도 제한으로 인해 일시 중지된 작업이 자체적으로 재개된 시점입니다.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

시험 실행에서 발견된 내용: total, by_status, already_in_didit, same_person, not_finished, failed, unmapped_statuses입니다.

face_templates_enabled
boolean
lawful_basis_confirmed_at
string<date-time> | null
not_finished_count
integer<int64>
same_person_count
integer<int64>
face_templates_count
integer<int64>
face_duplicates_count
integer<int64>
face_blocklist_hits_count
integer<int64>
created_by_name
string | null
created_by_email
string | null
마지막 수정일 2026년 11월 7일