개발가이드

  • 개발가이드

여권 개인정보 마스킹

여권의 지정 정보를 추출하고 여권번호 및 MRZ 영역을 마스킹합니다.

업로드 용량 제한: 50MB
첨부 이미지는 최대 50MB이며 PNG 또는 JPEG 형식만 지원합니다.
제한을 초과하면 HTTP 413과 REQUEST_TOO_LARGE 오류가 반환되며 과금되지 않습니다.

정보

Method
URL
POST
https://apick.app/rest/identity_document_passport
OCR 추출과 마스킹을 한 번의 호출로 처리합니다. 별도의 마스킹 API를 추가로 호출할 필요가 없습니다. 여권번호와 하단 MRZ 2줄 전체를 가린 PNG로 반환합니다. 추출값은 MRZ와 표기면을 함께 사용합니다. MRZ가 촬영되지 않았거나 판독 불가한 이미지는 실패 처리됩니다. 필수 정보 또는 마스킹 위치를 확정하지 못하면 무과금 실패하며, 이미지와 부분 추출값을 반환하지 않습니다. 이 경우 HTTP 상태코드는 401, api.cost는 0입니다. 이미지는 처리 직후 서버에서 삭제되며, 응답에는 OCR 원문과 여권번호를 포함하지 않습니다.

요청

Header
이름
필수
설명
CL_AUTH_KEY
O
인증키(MD5)
FormData
이름
타입
필수
설명
image
File
O
여권 인적사항면 이미지
MRZ 2줄이 포함되도록 촬영
PNG 또는 JPEG, 50MB 이하

응답

Body
이름
타입
설명
data
Object
조회 데이터
result
Object
추출 결과
실패 시 미반환
document_type
String
문서 종류
passport 고정
fields
Object
추출 항목
country_code
String
국가코드 / 발행국
Country code / Issuing country
ISO 3166-1 alpha-3, 예: KOR
surname
String
성
Surname
given_names
String
이름
Given names
korean_name
String
한글 성명
date_of_birth
String
생년월일
YYYYMMDD
sex
String
성별
M / F / X
nationality
String
국적
Nationality
masked_image
String
마스킹 완료 이미지
PNG의 Base64 데이터
image_mime
String
마스킹 이미지 형식
image/png 고정
elapsed_ms
Integer
OCR / 추출 / 마스킹 처리 시간(ms)
error
String
실패 사유
성공 시 미반환
success
Integer
과금 여부
0: 실패
1: 성공
api
Object
API 호출 공통 데이터
success
Boolean
API 서버 정상 응답 여부
cost
Integer
API 호출 요금
실패 시 0
ms
Integer
API 응답 시간
pl_id
Integer
API 결제 로그 ID

오류 응답

실패 응답은 data.success: 0, api.cost: 0을 유지하며 data.error_code로 원인을 구분합니다.

HTTP / 오류 코드
설명
422
IDENTITY_TEXT_UNREADABLE
글자가 일부 가려졌거나 선명하지 않아 필요한 정보를 정확히 인식할 수 없습니다. 문서 전체와 글자가 선명하게 보이는 이미지를 업로드해 주세요.
400
IDENTITY_DOCUMENT_MISMATCH
요청한 신분증 종류와 이미지가 일치하지 않습니다. 올바른 신분증 이미지를 업로드해 주세요.
424
IDENTITY_PROCESSING_FAILED
이미지 처리 중 오류가 발생했습니다. 잠시 후 다시 시도해 주세요.

예시

요청 예시

curl -k -X POST "https://apick.app/rest/identity_document_passport" \
-H "CL_AUTH_KEY: $API_KEY" \
-F "image=@/C:/Users/user/Desktop/passport.jpg"

마스킹 이미지 저장 (Node.js)


const form = new FormData();
form.append("image", new Blob([fs.readFileSync("passport.jpg")]), "passport.jpg");

const response = await fetch("https://apick.app/rest/identity_document_passport", {
    method: "POST",
    headers: { CL_AUTH_KEY: process.env.API_KEY },
    body: form,
});
const body = await response.json();

if (body.data.success === 1) {
    console.log(body.data.result.fields.country_code);
    fs.writeFileSync("masked.png", Buffer.from(body.data.result.masked_image, "base64"));
} else {
    console.error(body.data.error);
}
응답 예시

{
    "data": {
        "result": {
            "document_type": "passport",
            "fields": {
                "country_code": "KOR",
                "surname": "HONG",
                "given_names": "GILDONG",
                "korean_name": "홍길동",
                "date_of_birth": "19900101",
                "sex": "M",
                "nationality": "REPUBLIC OF KOREA"
            },
            "masked_image": "iVBORw0KGgoAAAANSUhEUgAA...(생략)",
            "image_mime": "image/png",
            "elapsed_ms": 458
        },
        "success": 1
    },
    "api": {
        "success": true,
        "cost": 30,
        "ms": 610,
        "pl_id": 1595642
    }
}
현재 페이지 북마크