{"openapi":"3.0.3","info":{"title":"APICK eKYC 본인확인","version":"1.0.0","description":"사진이 있는 신분증(주민등록증·운전면허증·여권·외국인등록증) 사진과, 고개를 좌우로 돌린 짧은 촬영 영상(또는 얼굴 사진)을 함께 받아 ① 신분증 사진이 실물 카메라 촬영본인지(화면 캡처·편집 여부) ② 지금 실제 사람이 움직였는지(라이브니스) ③ 신분증 얼굴과 촬영한 얼굴이 같은 사람인지 한 번에 판정합니다. 등본·주민등록등초본처럼 사진이 없는 서류는 대상이 아닙니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/kyc_session":{"post":{"summary":"eKYC 본인확인","description":"사진이 있는 신분증(주민등록증·운전면허증·여권·외국인등록증) 사진과, 고개를 좌우로 돌린 짧은 촬영 영상(또는 얼굴 사진)을 함께 받아 ① 신분증 사진이 실물 카메라 촬영본인지(화면 캡처·편집 여부) ② 지금 실제 사람이 움직였는지(라이브니스) ③ 신분증 얼굴과 촬영한 얼굴이 같은 사람인지 한 번에 판정합니다. 등본·주민등록등초본처럼 사진이 없는 서류는 대상이 아닙니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"verified":{"type":"boolean"},"result":{"type":"integer"},"reason":{"type":"string"},"message":{"type":"string"},"session_id":{"type":"string"},"document":{"type":"object","properties":{"verdict":{"type":"string"},"reason":{"type":"string"},"camera_capture":{"type":"boolean"},"edited":{"type":"boolean"},"screen_capture":{"type":"boolean"},"capture_age_days":{"type":"number"}}},"liveness":{"type":"object","properties":{"verdict":{"type":"string"},"duration_seconds":{"type":"number"},"motion":{"type":"number"},"pan_shift":{"type":"number"},"failed":{"type":"array","items":{}},"manual":{"type":"array","items":{}}}},"face":{"type":"object","properties":{"verdict":{"type":"string"},"similarity":{"type":"number"},"similarity_avg":{"type":"number"},"matched_frames":{"type":"integer"},"frames":{"type":"integer"},"threshold":{"type":"number"}}},"elapsed_ms":{"type":"integer"},"similarity":{"type":"number"},"success":{"type":"integer"}}},"api":{"type":"object","properties":{"success":{"type":"boolean"},"cost":{"type":"integer"},"ms":{"type":"integer"},"pl_id":{"type":"integer"}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"challenge":{"type":"string","description":"좌우 방향을 직접 지정합니다. turn_left_right·turn_right_left. 생략하면 서버가 무작위로 정합니다. (string)"},"data[result][session_id]":{"type":"string","description":"1회용 세션 식별자(32자)입니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"data[result][challenge]":{"type":"string","description":"좌우 지시 방향입니다. SDK 가 이 방향으로 고개를 돌리게 안내합니다. (string)"},"data[result][nonce]":{"type":"string","description":"서명에 묶이는 1회용 값입니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"data[result][expires_at]":{"type":"string","description":"세션 만료 시각(밀리초)입니다. 기본 15분입니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (integer)"},"session_id":{"type":"string","description":"kyc_session 이 준 세션 식별자입니다. 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다. (string)","example":"입력값"},"nonce":{"type":"string","description":"kyc_session 이 준 nonce 값입니다. 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다. (string)","example":"입력값"},"frames[0]":{"type":"string","description":"촬영 중 확인한 프레임 지문입니다. 6~128자 hex, 1~60개입니다. (string)","example":"입력값"},"session":{"type":"string","description":"촬영 세션 서명(/rest/kyc_session 발급 → /rest/kyc_seal 서명) (string)","example":"입력값"},"document_image":{"type":"string","description":"사진이 있는 신분증 사진(PNG·JPEG, 최대 20MB)입니다. multipart/form-data로 전송하며, 파일 경로가 아니라 파일 본문을 첨부합니다. (file)","format":"binary"},"face_video":{"type":"string","description":"고개를 좌우로 돌린 촬영 영상(MP4·MOV·WebM·3GP, 1~60초, 최대 30MB)입니다. face_image 와 둘 중 하나는 필수입니다. (file)","format":"binary"},"face_image":{"type":"string","description":"촬영 영상 대신 보내는 정지 얼굴 사진(JPEG·PNG, 최대 10MB)입니다. 라이브니스는 담당자 확인으로 내려갑니다. (file)","format":"binary"},"threshold":{"type":"string","description":"얼굴 일치 기준 점수 (범위: 0.2 ~ 0.8, 기본값 0.4) 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (number)"},"data[result]":{"type":"string","description":"1 통과, 0 실패, 2 담당자 확인입니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (integer)"},"data[verified]":{"type":"string","description":"result == 1 과 같습니다. true/false로 보내며, 생략하면 서버 기본값이 적용됩니다. true = 이 필드가 나타내는 조건이 성립한 경우, false = 성립하지 않은 경우입니다. 두 값 모두 정상 응답에 올 수 있으며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. (boolean)"},"data[reason]":{"type":"string","description":"사유 코드입니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"data[message]":{"type":"string","description":"사용자에게 보여 줄 문구입니다. 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. (string)"},"data[similarity]":{"type":"string","description":"가장 높은 얼굴 유사도(MCP 연동 편의 필드)입니다. 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (number)"}},"required":["session_id","nonce","frames[0]","session","document_image"]}}}}}},"/rest/kyc_verify":{"post":{"summary":"eKYC 본인확인","description":"사진이 있는 신분증(주민등록증·운전면허증·여권·외국인등록증) 사진과, 고개를 좌우로 돌린 짧은 촬영 영상(또는 얼굴 사진)을 함께 받아 ① 신분증 사진이 실물 카메라 촬영본인지(화면 캡처·편집 여부) ② 지금 실제 사람이 움직였는지(라이브니스) ③ 신분증 얼굴과 촬영한 얼굴이 같은 사람인지 한 번에 판정합니다. 등본·주민등록등초본처럼 사진이 없는 서류는 대상이 아닙니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"verified":{"type":"boolean"},"result":{"type":"integer"},"reason":{"type":"string"},"message":{"type":"string"},"session_id":{"type":"string"},"document":{"type":"object","properties":{"verdict":{"type":"string"},"reason":{"type":"string"},"camera_capture":{"type":"boolean"},"edited":{"type":"boolean"},"screen_capture":{"type":"boolean"},"capture_age_days":{"type":"number"}}},"liveness":{"type":"object","properties":{"verdict":{"type":"string"},"duration_seconds":{"type":"number"},"motion":{"type":"number"},"pan_shift":{"type":"number"},"failed":{"type":"array","items":{}},"manual":{"type":"array","items":{}}}},"face":{"type":"object","properties":{"verdict":{"type":"string"},"similarity":{"type":"number"},"similarity_avg":{"type":"number"},"matched_frames":{"type":"integer"},"frames":{"type":"integer"},"threshold":{"type":"number"}}},"elapsed_ms":{"type":"integer"},"similarity":{"type":"number"},"success":{"type":"integer"}}},"api":{"type":"object","properties":{"success":{"type":"boolean"},"cost":{"type":"integer"},"ms":{"type":"integer"},"pl_id":{"type":"integer"}}}}}}}},"default":{"description":"HTTP 상태 및 서비스 오류코드 확인","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"session":{"type":"string","description":"촬영 세션 서명(/rest/kyc_session 발급 → /rest/kyc_seal 서명) (string)","example":"입력값"},"document_image":{"type":"string","description":"사진이 있는 신분증 사진(PNG·JPEG, 최대 20MB)입니다. multipart/form-data로 전송하며, 파일 경로가 아니라 파일 본문을 첨부합니다. (file)","format":"binary"},"face_video":{"type":"string","description":"고개를 좌우로 돌린 촬영 영상(MP4·MOV·WebM·3GP, 1~60초, 최대 30MB)입니다. face_image 와 둘 중 하나는 필수입니다. (file)","format":"binary"},"face_image":{"type":"string","description":"촬영 영상 대신 보내는 정지 얼굴 사진(JPEG·PNG, 최대 10MB)입니다. 라이브니스는 담당자 확인으로 내려갑니다. (file)","format":"binary"},"threshold":{"type":"string","description":"얼굴 일치 기준 점수 (범위: 0.2 ~ 0.8, 기본값 0.4) 숫자로 보내며, 허용 범위를 벗어나면 요청이 거부됩니다. (number)"}},"required":["session","document_image"]}}}}}}},"x-code-tables":[{"title":"오류와 대처","columns":["HTTP","data.error","대처"],"rows":[["400","촬영 세션(session)이 없습니다. …","먼저 kyc_session 과 kyc_seal 을 호출하세요."],["400","신분증 사진(document_image)이 없습니다.","document_image 를 보내세요."],["400","얼굴 사진 또는 촬영 영상(face_image, face_video)이 없습니다.","face_video 또는 face_image 중 하나를 보내세요."],["413","얼굴 영상은 30MB, 얼굴 사진은 10MB 이하여야 합니다.","촬영 길이·해상도를 줄이세요(SDK 기본값으로 촬영하면 넘지 않습니다)."],["422","촬영 영상에서 실제 사람의 움직임을 확인하지 못했습니다. …","안내에 따라 고개를 좌우로 크게 돌려 다시 촬영하세요."],["422","화면 캡처로 만든 신분증 사진은 사용할 수 없습니다. …","실물 신분증을 카메라로 촬영하세요."],["422","이미 사용했거나 만료된 촬영 세션입니다. …","촬영 세션은 1회만 쓸 수 있습니다. 새 세션을 받으세요."],["422","신분증 사진과 촬영한 얼굴이 일치하지 않습니다.","다른 사람의 신분증인지 확인하고 다시 촬영하세요."],["424","본인 확인 서비스를 사용할 수 없습니다. … / 영상 처리 시간이 길어 …","잠시 뒤 한 번 더 요청하세요(과금 없음)."]]}],"x-service-errors":[],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}