개발가이드

  • 개발가이드

주민등록증 개인정보 마스킹

주민등록증의 지정 정보를 추출하고 주민등록번호 뒷자리 6자리를 마스킹합니다.

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

정보

Method
URL
POST
https://apick.app/rest/identity_document_id_card
OCR 추출과 마스킹을 한 번의 호출로 처리합니다. 추출용 API와 마스킹용 API를 각각 호출할 필요가 없습니다. 주민등록번호는 뒷자리 7자리 중 첫 자리만 남기고 6자리를 가린 PNG로 반환합니다. 필수 정보 또는 마스킹 위치를 확정하지 못하면 무과금 실패하며, 이미지와 부분 추출값을 반환하지 않습니다. 이 경우 HTTP 상태코드는 401, api.cost는 0입니다. 이미지는 처리 직후 서버에서 삭제되며, 응답에는 OCR 원문과 전체 주민등록번호를 포함하지 않습니다.

요청

Header
이름
필수
설명
CL_AUTH_KEY
O
인증키(MD5)
FormData
이름
타입
필수
설명
image
File
O
주민등록증 이미지
PNG 또는 JPEG
50MB 이하

응답

Body
이름
타입
설명
data
Object
조회 데이터
result
Object
추출 결과
실패 시 미반환
document_type
String
문서 종류
id_card 고정
fields
Object
추출 항목
name
String
성명
한자 병기는 제외하고 한글만 반환
rrn_front
String
주민등록번호 앞 6자리
rrn_back_first
String
주민등록번호 뒷자리 첫 숫자
나머지 6자리는 반환하지 않음
issue_date
String
발급일자
YYYYMMDD
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_id_card" \
-H "CL_AUTH_KEY: $API_KEY" \
-F "image=@/C:/Users/user/Desktop/id_card.jpg"

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


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

const response = await fetch("https://apick.app/rest/identity_document_id_card", {
    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);
    fs.writeFileSync("masked.png", Buffer.from(body.data.result.masked_image, "base64"));
} else {
    console.error(body.data.error);
}
응답 예시

{
    "data": {
        "result": {
            "document_type": "id_card",
            "fields": {
                "name": "홍길동",
                "rrn_front": "900101",
                "rrn_back_first": "1",
                "issue_date": "20200115"
            },
            "masked_image": "iVBORw0KGgoAAAANSUhEUgAA...(생략)",
            "image_mime": "image/png",
            "elapsed_ms": 332
        },
        "success": 1
    },
    "api": {
        "success": true,
        "cost": 30,
        "ms": 470,
        "pl_id": 1595643
    }
}
현재 페이지 북마크