본문 바로가기
개발가이드등기부등본부동산종합증명서 열람

부동산종합증명서 열람 API

명세 내보내기
OpenAPI 3.0.3Postman 컬렉션Markdown

토지·건물의 부동산종합증명서를 열람해 JSON과 PDF로 받습니다. 접수 후 결과조회로 받습니다.

POSThttps://apick.app/rest/kras_cert_jobs전체 3개 경로
인증
Bearer 키
요청 형식
form-data
응답
JSON · 파일
경로
3개

왜 부동산종합증명서 열람인가

부동산종합증명서, 주소만 보내면 열람이 끝납니다

매물·담보 검토 때마다 토지와 건물 대장을 따로 찾아 열람하고 PDF로 내려받는 일이 반복됩니다. 주소와 지번을 보내면 접수한 뒤 결과를 자동으로 받아 두어, 계약 검토에 필요한 대장 서류를 한 번에 모읍니다.

도입 효과

  • 대장 열람을 접수·조회 두 번의 호출로 끝냄
  • 완료된 열람을 JSON과 PDF로 함께 확보
  • 처리되지 않으면 요청한 만큼 돌려받음

이런 곳에서 많이 씁니다

  • 부동산 중개 매물 권리 검토
  • 금융사 담보 물건 서류 확인
  • 토지·건물 소유 관계 사전 조사
가입하고 API 키 받기API 키 하나로 바로 호출 · 실패한 요청은 과금되지 않습니다

알아둘 점

지원 API 요약

접수(제출)와 상태·결과 조회(조회), PDF 다운로드(다운로드) 세 API로 나뉩니다. 접수 직후 200P가 예약 차감되고 job_id와 status(waiting)를 돌려줍니다. 완료되면 상태 조회가 원문 내용(JSON)을, 다운로드가 PDF 문서를 응답합니다(다운로드는 무료).

Method
API entry point
기능
성공 결과
POST
/rest/kras_cert_jobs
열람 접수(200P 예약 차감)
job_id·status: "waiting"
POST
/rest/kras_cert_jobs/status
상태·결과(JSON) 조회(무료)
status·완료 시 result
POST
/rest/kras_cert_jobs/pdf
PDF 문서 다운로드(무료)
application/pdf

과금·환급

항목
설명
단가
건당 200P입니다.
과금 시점
접수 직후 200P 예약 차감이고, 완료되면 확정됩니다.
상태 조회·PDF 다운로드
무료(0P)입니다.
환급
조회가 실패(failed)하거나 처리 기한을 넘기면 예약 차감한 200P를 전액 환급합니다. 별도 호출이 필요 없습니다.
처리 제한 시간
접수 후 최대 180초까지 작업을 처리합니다. 넘기면 실패(환급)로 끝납니다.

요청과 응답

1API 요청
POST/rest/kras_cert_jobs
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 9개 · 필수 4
파라미터
설명
sido_nmstring필수
시·도 이름 (예: 서울특별시) 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다.
최대 길이
40자
예시
경기도
sgg_nmstring필수
시·군·구 이름 (예: 강남구) 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다.
최대 길이
40자
예시
성남시 분당구
emd_nmstring필수
읍·면·동 이름 (예: 역삼동) 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다.
최대 길이
40자
예시
정자동
ri_nmstring선택
리 이름 (읍·면 지역일 때) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.
최대 길이
40자
bobnstring필수
본번 (예: 123) 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다.
형식
^[0-9]{1,4}$
예시
1
bubnstring선택
부번 (없으면 생략) 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다.
형식
^[0-9]{1,4}$
예시
1
real_gbnstring선택
토지(L)·건물(B)·집합건물(M), 기본 L 문자열로 보내며, 생략하면 서버 기본값이 적용되거나 해당 조건이 해제됩니다. 가능한 값은 3가지입니다. L = L 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. B = 주요사항보고(B)입니다. 합병·분할·대규모 계약처럼 중요한 사건이 생겼을 때 공시됩니다. M = M 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요.
허용값
L B M
예시
L
doc_formatstring선택
받을 형식. PDF 를 원하면 pdf (JSON 결과는 항상 조회됩니다) 가능한 값은 2가지입니다. json = json 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요. pdf = pdf 값을 뜻하며, 같은 응답의 다른 필드와 함께 해석하세요.
허용값
json pdf
idempotency_keystring선택
같은 요청을 다시 보낼 때 중복 접수·과금을 막는 고유 키입니다. 요청 내용이 같으면 같은 키를 유지하고, 내용이 바뀌면 새 키를 만드세요. 키를 생략할 수 있는 API에서 생략하면 같은 요청은 기존 작업으로 처리됩니다.
최대 길이
64자
응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

2API 요청
POST/rest/kras_cert_jobs/status
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 1개 · 필수 1
파라미터
설명
job_idstring필수
접수 응답의 job_id 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다.
형식
^[a-f0-9]{32}$
예시
접수에서_반환한_ID
응답 필드

이 경로의 응답 형식은 오른쪽 응답 예시를 확인하세요.

3API 요청
POST/rest/kras_cert_jobs/pdf
  • Bearer 인증
  • multipart/form-data
  • 파일 응답
요청 파라미터 1개 · 필수 1
파라미터
설명
job_idstring필수
접수 응답의 job_id 문자열로 보내며, 빼거나 빈 값으로 보내면 요청이 거부됩니다.
형식
^[a-f0-9]{32}$
예시
접수에서_반환한_ID
응답 필드 파일

정상 응답은 파일 본문입니다. 실패 시 JSON 오류가 올 수 있으므로 HTTP 상태와 Content-Type을 먼저 확인하세요.

입력 조건·전송 규칙

접수 요청

접수(대기열 등록) 직후 200P가 예약 차감됩니다. 처리가 끝나면 완료 건에 확정 차감되고, 실패·기한 초과 건은 전액 환급됩니다(아래 과금·환급 참고). 접수 직후에는 취소할 수 없습니다.

응답 처리

HTTP 성공과 업무 결과를 구분하세요. 경로별 응답 필드와 예시는 위 요청과 응답에 함께 있습니다.

접수에 성공하면 job_id와 status: "waiting"을 담은 JSON이 옵니다. 이후 상태 조회 API로 확인합니다. 상태는 waiting → processing → completed(성공) 또는 failed(실패)로 바뀝니다.

상황
응답
접수 성공
data.job_id·data.status: "waiting"
상태 조회 · 처리 중
data.status: "waiting"|"processing"와 예상 대기 시간(초). 과금 없음(202)
상태 조회 · 완료
data.status: "completed", data.result(원문 JSON)·data.pdf_available
상태 조회 · 실패
data.error·data.error_code. 접수 때 차감한 금액 환급
PDF 다운로드 · 완료
Content-Type: application/pdf 본문(200)

오류 코드

응답을 아래 순서로 확인하세요. 결과 유무와 과금 여부는 서로 다릅니다.

  1. HTTP 상태전송·인증·입력 오류
  2. api.successAPI 처리 여부
  3. data · result업무 결과와 오류 문구
  4. api.cost이번 요청의 과금
업무 실패 응답 data.error
  • 입력값이 맞지 않거나 대상 자료가 없거나 일시적으로 처리하지 못하면 data.error(사유 문구)와 data.success=0을 돌려줍니다. HTTP 상태는 사유에 따라 400·404·408·424 중 하나입니다.
  • 이때 api.cost는 0이며 과금되지 않습니다. data.error 문구를 그대로 기록하고 사용자에게 보여 주세요.
  • 입력 오류(400)는 값을 고친 뒤 다시 요청하세요. 408·424는 잠시 후 한 번 다시 시도하고, 같은 입력으로 짧은 간격의 자동 반복은 하지 마세요.
{
  "data": {
    "error": "입력값을 확인해 주세요.",
    "success": 0
  },
  "api": {
    "success": true,
    "cost": 0,
    "ms": 5
  }
}
서비스 코드·조건

오류

오류는 data.error(안내 문구)와 data.error_code로 옵니다. waiting(처리 중)이면 과금하지 않습니다.

error_code
의미
대처
KRAS_CERT_BAD_REQUEST
요청 값이 올바르지 않습니다(400).
주소·지번 값을 확인합니다.
KRAS_CERT_POINTS_INSUFFICIENT
포인트가 부족합니다.
충전 후 다시 접수합니다.
KRAS_CERT_IDEMPOTENCY_CONFLICT
같은 멱등키의 다른 요청이 이미 접수되어 있습니다.
같은 요청이면 job_id를 확인하고, 다른 요청이면 새 키로 보냅니다.
KRAS_CERT_JOB_NOT_FOUND
작업을 찾을 수 없습니다.
job_id를 확인합니다.
KRAS_CERT_PDF_NOT_READY
PDF가 아직 준비되지 않았습니다.
작업이 완료된 뒤 다운로드합니다.
KRAS_CERT_PDF_EXPIRED
보관 기한이 지난 결과입니다(410).
다시 접수합니다.
KRAS_CERT_TEMPORARILY_UNAVAILABLE
일시적으로 처리할 수 없습니다.
잠시 후 다시 시도합니다.
인증·포인트 오류 result.error 문구
코드
HTTP
의미·조치
유효하지 않은 API키 입니다.
401
Authorization: Bearer 헤더의 인증키를 확인하세요.
허용되지 않은 IP주소 입니다.
401
마이페이지의 허용 IP 설정과 요청 서버 IP를 확인하세요.
비활성화된 계정입니다.
401
계정 이용 상태를 고객지원으로 문의하세요.
사용 가능한 포인트이 부족합니다.
200
HTTP 200이어도 result.error가 있으면 실패입니다. 포인트를 충전한 뒤 다시 요청하세요. 이 응답은 과금되지 않습니다.
무료 포인트로 사용할 수 없는 서비스입니다.
200
최소 1회 결제 후 이용할 수 있습니다. result.error 전체 문구를 그대로 표시하세요.
인증 정보를 확인할 수 없습니다.
424
일시적인 확인 실패입니다. 잠시 후 다시 시도하세요.
폼 입력 오류 error.code
코드
HTTP
의미·조치
FORM_DATA_INVALID
400
필드 이름·값의 타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.
FORM_DATA_FIELD_CONFLICT
400
같은 값과 중첩 경로를 동시에 지정하지 마세요.
MULTIPART_LIMIT_OR_PARSE_ERROR
400·413
boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·이용 조건

기본 요금열람 200P무료 포인트로는 이용할 수 없으며 최소 1회 결제 후 이용할 수 있습니다.

실제 차감 금액은 응답의 api.cost로 확인하세요. 상세 요금은 요금정책에서 볼 수 있습니다.

연동 팁

  • 요청 예제의 오류 처리 포함 모드는 시간 제한과 업무 실패 판정을 함께 보여줍니다.
  • 인증키는 서버 환경변수에 두고 브라우저·앱에 넣지 마세요.
  • HTTP 성공과 업무 결과를 구분하고, 실패 응답의 오류 문구를 그대로 기록하세요.

부동산종합증명서 열람

토지·건물의 부동산종합증명서를 열람해 JSON과 PDF로 받습니다. 접수 후 결과조회로 받습니다.

지원 API 요약

접수(제출)와 상태·결과 조회(조회), PDF 다운로드(다운로드) 세 API로 나뉩니다. 접수 직후 200P가 예약 차감되고 job_id와 status(waiting)를 돌려줍니다. 완료되면 상태 조회가 원문 내용(JSON)을, 다운로드가 PDF 문서를 응답합니다(다운로드는 무료).

Method
API entry point
기능
성공 결과
POST
/rest/kras_cert_jobs
열람 접수(200P 예약 차감)
job_id·status: "waiting"
POST
/rest/kras_cert_jobs/status
상태·결과(JSON) 조회(무료)
status·완료 시 result
POST
/rest/kras_cert_jobs/pdf
PDF 문서 다운로드(무료)
application/pdf

접수 요청

파라미터
타입
필수
설명
sido_nm
string
필수
시·도 이름입니다(예: 경기도).
sgg_nm
string
필수
시·군·구 이름입니다(예: 성남시 분당구).
emd_nm
string
필수
읍·면·동 이름입니다(예: 정자동).
ri_nm
string
선택
리 이름입니다. 읍·면 지역일 때 넣습니다.
bobn
string
필수
본번(숫자 1~4자리)입니다.
bubn
string
선택
부번(숫자 1~4자리)입니다. 부번이 없으면 생략합니다.
real_gbn
string
선택
조회 대상 유형입니다. L(토지) | B(건물) | M(복합). 기본 L.
doc_format
string
선택
원하는 결과 형식입니다. json | pdf. 기본 json. PDF 문서는 언제나 다운로드 API로 받을 수 있습니다.
reg_no_expr
boolean
선택
주민등록번호 표시 여부입니다. 기본 false.
idempotency_key
string
선택
같은 요청을 두 번 접수·과금하지 않도록 막는 키(8~128자)입니다. 네트워크 오류로 다시 보낼 때 같은 값을 쓰면 추가 과금 없이 기존 작업을 돌려줍니다.
# 1) 접수 — job_id 를 담은 JSON 응답
curl -X POST "https://apick.app/rest/kras_cert_jobs" \
  -H "Authorization: Bearer $APICK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sido_nm":"경기도","sgg_nm":"성남시 분당구","emd_nm":"정자동","bobn":"1","bubn":"1","real_gbn":"L"}'

# → {"data":{"job_id":"...","status":"waiting",...},"api":{"success":true,"cost":0}}

# 2) 상태·결과 조회 — 완료될 때까지 같은 job_id 폴링(무료)
JOB_ID="<위 응답의 data.job_id>"
curl -X POST "https://apick.app/rest/kras_cert_jobs/status" \
  -H "Authorization: Bearer $APICK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id":"'"$JOB_ID"'"}'

# 3) PDF 다운로드(무료)
curl -X POST "https://apick.app/rest/kras_cert_jobs/pdf" \
  -H "Authorization: Bearer $APICK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"job_id":"'"$JOB_ID"'"}' \
  -o kras-cert.pdf

접수(대기열 등록) 직후 200P가 예약 차감됩니다. 처리가 끝나면 완료 건에 확정 차감되고, 실패·기한 초과 건은 전액 환급됩니다(아래 과금·환급 참고). 접수 직후에는 취소할 수 없습니다.

응답

접수에 성공하면 job_id와 status: "waiting"을 담은 JSON이 옵니다. 이후 상태 조회 API로 확인합니다. 상태는 waiting → processing → completed(성공) 또는 failed(실패)로 바뀝니다.

상황
응답
접수 성공
data.job_id·data.status: "waiting"
상태 조회 · 처리 중
data.status: "waiting"|"processing"와 예상 대기 시간(초). 과금 없음(202)
상태 조회 · 완료
data.status: "completed", data.result(원문 JSON)·data.pdf_available
상태 조회 · 실패
data.error·data.error_code. 접수 때 차감한 금액 환급
PDF 다운로드 · 완료
Content-Type: application/pdf 본문(200)

과금·환급

항목
설명
단가
건당 200P입니다.
과금 시점
접수 직후 200P 예약 차감이고, 완료되면 확정됩니다.
상태 조회·PDF 다운로드
무료(0P)입니다.
환급
조회가 실패(failed)하거나 처리 기한을 넘기면 예약 차감한 200P를 전액 환급합니다. 별도 호출이 필요 없습니다.
처리 제한 시간
접수 후 최대 180초까지 작업을 처리합니다. 넘기면 실패(환급)로 끝납니다.

오류

오류는 data.error(안내 문구)와 data.error_code로 옵니다. waiting(처리 중)이면 과금하지 않습니다.

error_code
의미
대처
KRAS_CERT_BAD_REQUEST
요청 값이 올바르지 않습니다(400).
주소·지번 값을 확인합니다.
KRAS_CERT_POINTS_INSUFFICIENT
포인트가 부족합니다.
충전 후 다시 접수합니다.
KRAS_CERT_IDEMPOTENCY_CONFLICT
같은 멱등키의 다른 요청이 이미 접수되어 있습니다.
같은 요청이면 job_id를 확인하고, 다른 요청이면 새 키로 보냅니다.
KRAS_CERT_JOB_NOT_FOUND
작업을 찾을 수 없습니다.
job_id를 확인합니다.
KRAS_CERT_PDF_NOT_READY
PDF가 아직 준비되지 않았습니다.
작업이 완료된 뒤 다운로드합니다.
KRAS_CERT_PDF_EXPIRED
보관 기한이 지난 결과입니다(410).
다시 접수합니다.
KRAS_CERT_TEMPORARILY_UNAVAILABLE
일시적으로 처리할 수 없습니다.
잠시 후 다시 시도합니다.

개발가이드 검색

API 이름·경로·파라미터·오류 코드로 찾을 수 있습니다.

표시 가격은 기본 단가입니다. 상세 과금 조건은 각 가이드에서 확인하세요.