시작하기
연동 / SDK
사용자 인증
기업 확인
거래 모니터링
변경 내역vin이나 bank_account_number가 여기에 해당합니다. 따라서 이 필드를 보내는 서비스 페이지에는 cURL 샘플만 표시됩니다.
설치
구성
모든 SDK는 같은 환경 변수를 읽으므로, 옵션 없이 만든 클라이언트를 바로 사용할 수 있습니다. 엣지 런타임에는 프로세스 환경이 없습니다. 이 경우 Node.js 클라이언트에 API 키를 옵션으로 전달합니다.
환경 변수로 설정할 수 있는 값은 모두 클라이언트에 직접 전달할 수도 있습니다. 기본 URL, 타임아웃, 재시도, 기본 헤더, 자체 HTTP 클라이언트도 마찬가지입니다. 프로세스당 클라이언트 하나를 만들어 공유하세요. 클라이언트는 연결 풀을 유지하며, 여러 스레드나 태스크에서 안전하게 사용할 수 있습니다.
account 메서드(프로그래밍 방식 등록: 등록, 로그인, 조직 및 애플리케이션)는 https://apx.didit.me/auth/v2를 호출하며, API 키를 전송하지 않습니다. account.login으로 로그인한 다음, 반환된 액세스 토큰을 계정 토큰으로 클라이언트에 전달하세요.
모든 SDK의 기능
- 리소스와 메서드. 호출은 API의 리소스를 따릅니다. 예를 들어
client.<resource>.<method>(...)형태이며,sessions.create,sessions.retrieve_decision,transactions.create처럼 각 언어의 표기법에 맞춥니다. 경로 ID는 위치 인수로 전달합니다. 본문과 쿼리는 이름이 지정된 하나의 필드 집합입니다. Python, Node.js, PHP, Ruby는 API의 필드 이름(workflow_id)을 그대로 사용합니다. Go, Java, .NET은 각 언어의 표기법(WorkflowID,workflowId,WorkflowId)을 사용합니다. - 목록. 목록 메서드는
limit과offset을 내부적으로 사용해 모든 결과를 자동으로 페이지 단위로 순회합니다. 또한 각 페이지를count,next,previous,results와 함께 직접 제공합니다. Ruby에서는auto_paging_each가 모든 페이지를 순회하며, 페이지의total_count,next_url,previous_url은 API의count,next,previous에 해당합니다. - 파일. 업로드(문서 이미지, 셀피, 주소 증명, 가져오기 파일)는 경로, 바이트 또는 스트림을 받습니다. 다운로드(세션 PDF, 보고서)는 바이트 또는 스트림을 반환하며, 파싱된 JSON을 반환하지 않습니다.
- 하위 호환성. SDK 버전이 아직 알지 못하는 응답 필드나 열거형 값은 오류가 되지 않고 유지되어 읽을 수 있습니다. 따라서 API에 추가된 항목이 배포된 연동을 깨뜨리지 않습니다.
- webhook.
webhooks.verify는 webhook 전송의X-Signature-V2및X-Signature헤더와 타임스탬프를 webhook 시크릿으로 검증하고, 타입이 지정된 webhook 이벤트를 반환합니다. 시크릿을 교체하는 동안에는 여러 시크릿이 포함된 목록을 허용합니다. 서명 방식은 webhook을 참고하세요. - 인증.
Authentication헬퍼는 Authentication 발급자가 서명한 액세스 토큰과 ID 토큰을 검증하며, 토큰, 세션, 단계별 인증(step-up) endpoint를 호출합니다. API 키는 사용하지 않습니다.
에러, 재시도 및 타임아웃
모든 에러는
DiditError에서 파생됩니다. Go에서는 모든 에러가 didit.Error 인터페이스를 구현하며, *didit.NotFoundError와 같은 포인터 타입입니다. Java, PHP, .NET에서는 각 언어의 일반적인 Exception 접미사를 사용하고, API는 Api로 표기합니다: DiditException, ApiStatusException, NotFoundException.
SDK는 실패한 요청을 최대 2번 재시도하며, 재시도 간격은 0.5초에서 시작하는 지수 백오프(전체 지터 적용, 최대 8초)를 따르고 Retry-After를 준수합니다. GET, HEAD, PUT, DELETE 요청은 연결 에러, 타임아웃, 408, 429, 5xx에서 재시도됩니다. POST와 PATCH 요청은 429이거나 요청이 전송되기 전에 연결이 실패한 경우에만 재시도되므로, 재시도로 세션이나 거래가 두 번 생성되는 일은 없습니다. 기본 타임아웃은 60초입니다. 모든 응답은 원시 HTTP 상태 코드, 헤더, 요청 ID도 제공합니다. 429의 기준이 되는 한도는 속도 제한을 참고하십시오.
버전 관리 및 지원
- SDK는 시맨틱 버저닝을 따르며, API 변경에 대한 규칙이 하나 있습니다. Didit API를 그대로 반영한 변경은 마이너 릴리스로 제공됩니다. 타입이 지정된 코드를 깨뜨릴 수 있는 변경(타입이 바뀐 필드, null이 될 수 있게 된 필드, 제거된 엔드포인트, 필드 또는 열거형 값)이라도 마찬가지입니다. API가 모든 호출자에게 이미 그렇게 동작하므로, 이전 SDK 버전이 더 안전한 것은 아닙니다. 릴리스 노트에는 이러한 변경이 “타입이 지정된 코드를 깨뜨릴 수 있는 API 변경”이라는 항목 아래에 나열됩니다.
- 메이저 버전은 SDK 자체 설계의 변경에만 사용됩니다. 예를 들어 API가 그대로 유지하는 메서드나 리소스가 이름이 바뀌거나 제거된 경우, 클라이언트 구성, 에러, 재시도, 페이지네이션 또는 webhook 검증 동작이 변경된 경우, 지원 중단된 런타임 버전이 제외된 경우가 해당합니다. API에서 엔드포인트가 제거되거나 메서드 이름이 바뀌는 경우, 기존 메서드는 최소 한 번의 마이너 버전 동안 유지되며 지원 중단(deprecated)으로 표시됩니다. 따라서 새 메서드로 옮기는 동안에도 기존 코드가 계속 빌드됩니다. 각 언어는 고유한 버전 번호를 유지합니다. Node.js, PHP, Ruby는 2.x이고 나머지는 1.x입니다. 이 세 언어는 이 규칙이 적용되기 전에 API 변경을 메이저 버전으로 릴리스했기 때문입니다.
- SDK는 게시된 API 계약(
openapi-25.json및openapi-auth.json)에서 생성되며, Didit 인증 메서드는openapi-authentication.json과 대조하여 검사합니다. 세 가지 모두 매일 검사하므로, 새 엔드포인트나 필드는 7개 SDK 모두의 정기 릴리스에 포함되어 제공됩니다. - 각 SDK는 표에 나온 최소 런타임과 그보다 새로운 모든 릴리스를 지원합니다. 테스트는 최소 런타임과 그보다 새로운 각 릴리스에서 실행되며, Node.js와 Java의 경우에는 각 장기 지원(LTS) 릴리스에서 실행됩니다.
- 각 저장소의
CHANGELOG.md에는 모든 릴리스의 변경 사항이 나열되어 있습니다. - 보안 문제는 SDK 저장소의 보안 어드바이저리 또는 support@didit.me를 통해 비공개로 신고하십시오.