{"openapi":"3.0.3","info":{"title":"APICK 외국인등록증 개인정보 마스킹","version":"1.0.0","description":"외국인등록증·영주증·외국국적동포 국내거소신고증의 지정 정보를 추출하고 등록번호 또는 거소신고번호 뒷자리 6자리를 마스킹합니다."},"servers":[{"url":"https://apick.app"}],"paths":{"/rest/identity_document_residence_card":{"post":{"summary":"외국인등록증 개인정보 마스킹","description":"외국인등록증·영주증·외국국적동포 국내거소신고증의 지정 정보를 추출하고 등록번호 또는 거소신고번호 뒷자리 6자리를 마스킹합니다.","security":[{"bearerAuth":[]}],"parameters":[],"responses":{"200":{"description":"서비스별 성공·처리 상태 응답","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"result":{"type":"object","properties":{"document_type":{"type":"string","description":"문서 종류입니다. 세 신분증 모두 residence_card입니다."},"fields":{"type":"object","properties":{"registration_number_front":{"type":"string","description":"외국인등록번호 또는 거소신고번호 앞 6자리입니다. 예: 900101"},"registration_number_back_first":{"type":"string","description":"번호 뒷자리의 첫 숫자 한 자리입니다. 나머지 6자리는 응답에 담지 않습니다."},"name":{"type":"string","description":"카드에 적힌 로마자 성명(대문자)입니다. 예: JOHN SMITH"},"country_region":{"type":"string","description":"카드에 적힌 국가/지역입니다. 예: UNITED STATES"},"residence_status":{"type":"string","description":"카드에 적힌 체류자격입니다. 예: 결혼이민(F-6), 거주(F-2)"}},"description":"이미지에서 읽은 항목입니다. 성공 응답에서는 아래 다섯 항목이 모두 채워져 있습니다."},"masked_image":{"type":"string","description":"번호 뒷자리 6자리를 가린 PNG 이미지의 Base64 문자열입니다. 디코딩해 .png 파일로 저장하세요."},"image_mime":{"type":"string","description":"masked_image의 형식입니다. 항상 image/png입니다."},"elapsed_ms":{"type":"integer","description":"항목 인식과 가림 처리에 걸린 시간(밀리초)입니다. 네트워크 전송 시간은 포함되지 않습니다."}},"description":"읽은 항목과 가린 이미지입니다. 실패 응답에는 없습니다."},"success":{"type":"integer","description":"처리 상태입니다. 1이면 성공(요금 차감), 0이면 실패(차감 없음)입니다."},"error":{"type":"string","description":"실패 사유 문구입니다. 성공 응답에는 없습니다."},"error_code":{"type":"string","description":"실패 원인 코드입니다. 아래 오류 표의 코드로 분기하세요. 성공 응답에는 없습니다."}},"description":"처리 결과 묶음입니다. 성공하면 result가, 실패하면 error·error_code가 들어 있습니다."},"api":{"type":"object","properties":{"success":{"type":"boolean","description":"요청을 정상적으로 받아 처리했는지 여부입니다. 인식 성공 여부는 data.success로 확인하세요."},"cost":{"type":"integer","description":"이번 호출에서 차감된 포인트입니다. 실패 응답은 0입니다."},"ms":{"type":"integer","description":"요청을 받아 응답을 만들기까지 걸린 시간(밀리초)입니다. 네트워크 왕복 시간은 포함되지 않습니다."},"pl_id":{"type":"integer","description":"포인트 차감 기록 번호입니다. 차감이 있었던 호출에만 값이 있으며 과금 문의 때 사용합니다."}},"description":"호출 공통 정보입니다. 처리 여부·차감 포인트·처리 시간·차감 기록 번호가 들어 있습니다."}}}}}},"default":{"description":"OCR_IMAGE_MISSING (400): 이미지 파일을 첨부하세요.\nOCR_UNSUPPORTED_IMAGE (400): 지원하는 이미지 형식을 사용하세요.\nOCR_IMAGE_TOO_LARGE (413): 서비스의 파일 크기 제한을 확인하세요.\nIDENTITY_TEXT_UNREADABLE (422): 판독할 수 있는 문서 이미지를 첨부하세요.\nIDENTITY_DOCUMENT_MISMATCH (400): 요청한 종류와 일치하는 문서를 첨부하세요.\nIDENTITY_PROCESSING_FAILED (424): 문서 처리에 실패했습니다. 다시 시도하거나 문의하세요.","content":{"application/json":{"schema":{"type":"object"}}}}},"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"image":{"type":"string","description":"외국인등록증·영주증·외국국적동포 국내거소신고증 중 한 장의 앞면 이미지입니다. PNG 또는 JPEG만 받으며 50MB 이하입니다. (file)","format":"binary"}},"required":["image"]}}}}}}},"x-code-tables":[{"title":"입력 오류","columns":["HTTP / 오류 코드","data.error","조치"],"rows":[["400OCR_IMAGE_MISSING","첨부파일이 없습니다.","image 항목에 파일 하나를 multipart/form-data로 첨부하세요."],["400OCR_UNSUPPORTED_IMAGE","PNG 또는 JPEG 이미지 파일만 허용됩니다.","PNG·JPEG로 바꿔 다시 보내세요. 손상된 파일이면 \"지원되지 않거나 손상된 이미지입니다.\"가 옵니다."],["413OCR_IMAGE_TOO_LARGE","이미지 파일은 50MB 이하여야 합니다.","해상도를 줄이거나 JPEG로 압축해 50MB 이하로 보내세요."]]},{"title":"오류 응답","columns":["HTTP / 오류 코드","설명"],"rows":[["422IDENTITY_TEXT_UNREADABLE","글자가 일부 가려졌거나 선명하지 않아 필요한 정보를 정확히 인식할 수 없습니다. 문서 전체와 글자가 선명하게 보이는 이미지를 업로드해 주세요."],["400IDENTITY_DOCUMENT_MISMATCH","요청한 신분증 종류와 이미지가 일치하지 않습니다. 올바른 신분증 이미지를 업로드해 주세요."],["424IDENTITY_PROCESSING_FAILED","이미지 처리 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요."]]}],"x-service-errors":[{"code":"OCR_IMAGE_MISSING","status":400,"message":"이미지 파일을 첨부하세요."},{"code":"OCR_UNSUPPORTED_IMAGE","status":400,"message":"지원하는 이미지 형식을 사용하세요."},{"code":"OCR_IMAGE_TOO_LARGE","status":413,"message":"서비스의 파일 크기 제한을 확인하세요."},{"code":"IDENTITY_TEXT_UNREADABLE","status":422,"message":"판독할 수 있는 문서 이미지를 첨부하세요."},{"code":"IDENTITY_DOCUMENT_MISMATCH","status":400,"message":"요청한 종류와 일치하는 문서를 첨부하세요."},{"code":"IDENTITY_PROCESSING_FAILED","status":424,"message":"문서 처리에 실패했습니다. 다시 시도하거나 문의하세요."}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}}}