Developer Reference
등기고 API
등기고 API를 통해 부동산 등기부등본 조회, 문서함 관리, 변동 알림을 자동화하고 외부 시스템과 연동할 수 있습니다.
개요
모든 API 엔드포인트의 Base URL은 다음과 같습니다.
Base URL
https://deunggigo.kr/api/v1요청/응답 Body는 모두 application/json 형식입니다.
등기부등본 열람은 비동기로 처리됩니다. 요청 시 id가 반환되며, 이후 해당 id로 결과를 폴링합니다. 처리 완료까지 수 분이 소요될 수 있습니다.
인증
API 요청은 API 키 또는 로그인 세션 쿠키 중 하나로 인증합니다. 외부 서버에서 호출할 때는 API 키를 사용하세요.
API 키는 설정 페이지 또는 API 키 관리 페이지에서 발급받습니다.
헤더 형식 (둘 중 하나 사용)
Request Header
# 방법 1 - Authorization Bearer
Authorization: Bearer dgg_xxxxxxxxxxxxxxxx
# 방법 2 - X-Api-Key
X-Api-Key: dgg_xxxxxxxxxxxxxxxxcurl 예시
bash
curl -X GET "https://deunggigo.kr/api/v1/credits/balance" \
-H "Authorization: Bearer dgg_xxxxxxxxxxxxxxxx"infoAPI 키는 서버 측에서만 사용하고 외부에 노출하지 마세요. 키가 없거나 유효하지 않으면
401 Unauthorized가 반환됩니다.크레딧
GET
/api/v1/credits/balance잔액 조회현재 계정의 크레딧 잔액을 조회합니다.
bash
curl -X GET "https://deunggigo.kr/api/v1/credits/balance" \
-H "Authorization: Bearer dgg_xxx"응답 200
json
{
"creditBalance": 15000
}GET
/api/v1/credits/transactions거래 내역크레딧 충전/사용 내역을 페이지네이션으로 조회합니다.
Query Parameters
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| page | number | 1 | 페이지 번호 |
| limit | number | 20 | 페이지당 항목 수 |
bash
curl -X GET "https://deunggigo.kr/api/v1/credits/transactions?page=1&limit=10" \
-H "Authorization: Bearer dgg_xxx"응답 200
json
{
"items": [
{
"id": "tx_abc123",
"type": "usage",
"amount": -50,
"balanceAfter": 14950,
"description": "등기부등본 열람 (1341-2004-008457)",
"referenceType": "inquiry",
"createdAt": "2024-06-01T09:01:24.000Z"
},
{
"id": "tx_abc124",
"type": "charge",
"amount": 10000,
"balanceAfter": 15000,
"description": "크레딧 충전",
"referenceType": "payment",
"createdAt": "2024-06-01T08:00:00.000Z"
}
],
"total": 42,
"page": 1,
"totalPages": 5
}부동산 검색
POST
/api/v1/property-search주소 검색주소 키워드로 부동산을 검색합니다. IROS 간편검색 기반입니다.
json - 요청
{
"address": "서울 강남구 테헤란로 123",
"kindCls": "0",
"recordStatus": "0"
}파라미터
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| address* | string | — | 주소 키워드 (지번 또는 도로명) |
| kindCls | '0'~'3' | '0' | 부동산구분. 0=전체, 1=집합건물, 2=토지, 3=건물 |
| recordStatus | '0'~'2' | '0' | 등기기록상태. 0=현행, 1=전산폐쇄, 2=현행+전산폐쇄 |
응답 200
json
{
"items": [
{
"uniqueNo": "1168-2024-001234",
"address": "서울특별시 강남구 테헤란로 123",
"propertyType": "집합건물",
"dong": "101동",
"ho": "501호"
}
],
"total": 15
}POST
/api/v1/property-lookup고유번호 조회고유번호로 부동산 정보를 직접 조회합니다.
json - 요청
{
"uniqueNo": "1341-2004-008457"
}응답 200
json
{
"uniqueNo": "1341-2004-008457",
"address": "경기도 성남시 분당구 ...",
"propertyType": "집합건물"
}문서함 관리
GET
/api/v1/bulk-inquiries문서함 목록생성된 문서함(대량조회) 목록을 조회합니다.
Query Parameters
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| page | number | 1 | 페이지 번호 |
| limit | number | 10 | 페이지당 항목 수 |
json - 응답
{
"items": [
{
"id": "bulk_clxyz1234",
"fileName": "강남구_조회.xlsx",
"totalCount": 50,
"completedCount": 48,
"failedCount": 2,
"status": "completed",
"createdAt": "2024-06-01T09:00:00.000Z"
}
],
"total": 5,
"page": 1,
"totalPages": 1
}POST
/api/v1/inquiries/cart문서함 생성/항목 추가문서함을 생성하거나 기존 문서함에 항목을 추가합니다. 등기번호(고유번호)로 직접 추가하거나, 주소 검색을 통해 추가할 수 있습니다.
등기번호로 추가
items 배열에 uniqueNo를 직접 지정합니다 (14자리 숫자 검증).
json - 요청
{
"bulkId": "bulk_clxyz1234",
"items": [
{ "uniqueNo": "13412004008457", "address": "경기도 성남시 ...", "kindCls": "1" },
{ "uniqueNo": "1168-2024-001234", "address": "서울특별시 강남구 ...", "kindCls": "1" }
]
}새 문서함 생성과 동시에 추가
bulkId를 생략하면 새 문서함이 자동 생성됩니다. boxName으로 이름을 지정할 수 있습니다.
json - 요청
{
"boxName": "강남구 조회",
"items": [
{ "uniqueNo": "13412004008457", "address": "경기도 성남시 ...", "kindCls": "1" }
]
}응답 200
json
{
"success": true,
"bulkId": "bulk_clxyz1234",
"count": 2
}GET
/api/v1/bulk-inquiries/{id}문서함 상세문서함의 상세 정보와 포함된 항목 목록을 조회합니다.
json - 응답
{
"bulkInquiry": {
"id": "bulk_clxyz1234",
"fileName": "강남구_조회.xlsx",
"totalCount": 50,
"completedCount": 48,
"failedCount": 2,
"status": "completed",
"totalCost": 4800
},
"items": [
{
"id": "clxyz1111",
"uniqueNumber": "1341-2004-008457",
"status": "completed",
"cost": 100,
"hasPdf": true,
"createdAt": "2024-06-01T09:00:00.000Z"
}
]
}PATCH
/api/v1/bulk-inquiries/{id}문서함 수정 (이름 변경)json - 요청
{
"name": "강남구 2024년 2분기"
}json - 응답
{
"message": "문서함이 수정되었습니다."
}DELETE
/api/v1/bulk-inquiries/{id}문서함 삭제문서함과 포함된 모든 열람 데이터, PDF 파일이 삭제됩니다. 되돌릴 수 없습니다.
json - 응답
{
"message": "문서함이 삭제되었습니다."
}POST
/api/v1/bulk-inquiries/{id}/execute일괄 열람 실행문서함에 포함된 모든 항목의 열람을 일괄 실행합니다. 항목별로 크레딧이 차감됩니다.
json - 응답
{
"message": "일괄 열람이 시작되었습니다.",
"totalCount": 50,
"creditDeducted": 2500
}GET
/api/v1/bulk-inquiries/{id}/excel엑셀 다운로드문서함의 열람 결과를 엑셀 파일로 다운로드합니다.
응답: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet 바이너리
GET
/api/v1/bulk-inquiries/{id}/downloadPDF ZIP 다운로드문서함의 모든 PDF를 ZIP 파일로 다운로드합니다.
응답: application/zip 바이너리
단건 열람
POST
/api/v1/inquiries열람 요청등기부등본 열람을 요청합니다. 비동기로 처리되며 결과는 별도 조회합니다.
주요 파라미터
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| issueType* | '0'|'1' | '1' | 0=발급, 1=열람 |
| searchDiv* | '1'|'2'|'3'|'4' | '1' | 1=고유번호, 2=간편검색, 3=소재지번, 4=도로명 |
| uniqueNo | string | — | 14자리 고유번호 (searchDiv=1일 때 필수) |
| address | string | — | 주소 키워드 (searchDiv=2일 때 필수) |
| display | '1'|'2' | '2' | 1=현재유효사항, 2=말소사항 포함 |
| dupChk | 'Y'|'N' | 'N' | 재열람 우선 시도 여부 |
json - 요청 예시
{
"issueType": "1",
"searchDiv": "1",
"uniqueNo": "1341-2004-008457",
"display": "2"
}응답 200
json
{
"message": "조회 요청이 접수되었습니다.",
"inquiry": {
"id": "clxyz1234abcd",
"uniqueNumber": "1341-2004-008457",
"issueType": "1",
"status": "pending",
"cost": 50
}
}에러 응답
json - 크레딧 부족 (402)
{
"error": "크레딧이 부족합니다. 필요: 50원, 현재: 0원"
}json - 중복 요청 (409)
{
"error": "동일한 등기부등본이 이미 처리 중입니다."
}GET
/api/v1/inquiries/{id}열람 결과열람 요청의 처리 상태와 결과를 조회합니다.status가 completed 또는 failed가 될 때까지 폴링합니다.
status 값
pending
접수 완료
processing
처리 중
completed
성공
failed
실패
json - 성공 응답
{
"inquiry": {
"id": "clxyz1234abcd",
"uniqueNumber": "1341-2004-008457",
"propertyType": "building",
"issueType": "1",
"status": "completed",
"cost": 50,
"pdfPath": "/downloads/registry_clxyz1234abcd.pdf",
"parsedData": {
"titleSection": [...],
"exclusiveSection": [...],
"rightSection": [...]
},
"createdAt": "2024-06-01T09:00:00.000Z",
"completedAt": "2024-06-01T09:01:24.000Z"
}
}GET
/api/v1/inquiries/{id}/pdfPDF 다운로드열람 완료된 등기부등본을 PDF로 다운로드합니다.
응답: application/pdf 바이너리. 본인 소유 열람 건만 허용. PDF 미생성 또는 실패 시 404.
변동 알림
부동산 등기 변동(실거래, 등기신청사건)을 모니터링하고 SMS로 알림을 받습니다. 매시간 자동으로 변동을 체크하며, 변동 감지 시 등록된 수신자에게 알림을 발송합니다.
GET
/api/v1/alerts알림 목록Query Parameters
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| page | number | 1 | 페이지 번호 |
| limit | number | 20 | 페이지당 항목 수 |
| search | string | — | 고유번호/주소/연락처 검색 |
| status | 'active'|'inactive' | — | 활성 상태 필터 |
json - 응답
{
"items": [
{
"id": "alert_abc123",
"uniqueNumber": "1341-2004-008457",
"address": "경기도 성남시 분당구 ...",
"propertyType": "building",
"ownerName": "홍길동",
"isActive": true,
"createdAt": "2024-06-01T09:00:00.000Z",
"recipients": [
{ "name": "담당자", "phone": "010-1234-5678" }
]
}
],
"total": 10,
"page": 1,
"totalPages": 1
}POST
/api/v1/alerts알림 등록부동산 변동 알림을 등록합니다. 등록 시 월 과금(100원/건)이 크레딧에서 차감됩니다.
json - 요청
{
"uniqueNumber": "1341-2004-008457",
"address": "경기도 성남시 분당구 ...",
"propertyType": "building",
"ownerName": "홍길동",
"recipients": [
{ "name": "담당자", "phone": "010-1234-5678" }
]
}파라미터
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| uniqueNumber* | string | — | 14자리 고유번호 |
| recipients* | array | — | 수신자 배열 [{name, phone}] |
| ownerName | string | — | 소유자 이름 (미전달 시 최근 열람에서 자동 추출) |
| address | string | — | 주소 |
| propertyType | string | 'building' | 부동산 유형 |
응답 200
json
{
"message": "알림이 등록되었습니다.",
"alert": {
"id": "alert_abc123",
"uniqueNumber": "1341-2004-008457",
"isActive": true,
"recipients": [
{ "name": "담당자", "phone": "010-1234-5678" }
]
}
}에러 응답
json - 크레딧 부족 (400)
{
"error": "크레딧이 부족합니다."
}json - 중복 등록 (409)
{
"error": "이미 등록된 부동산입니다."
}PATCH
/api/v1/alerts/{id}알림 수정알림의 활성/비활성 토글, 수신자 연락처 업데이트 등을 수행합니다. 비활성 상태에서 다시 활성화할 때 월 과금이 적용될 수 있습니다.
활성/비활성 토글
json - 요청
{
"isActive": true
}수신자 업데이트
json - 요청
{
"recipients": [
{ "name": "담당자A", "phone": "010-1111-2222" },
{ "name": "담당자B", "phone": "010-3333-4444" }
]
}응답 200
json
{
"id": "alert_abc123",
"uniqueNumber": "1341-2004-008457",
"isActive": true,
"recipients": [
{ "name": "담당자A", "phone": "010-1111-2222" },
{ "name": "담당자B", "phone": "010-3333-4444" }
]
}DELETE
/api/v1/alerts/{id}알림 삭제등록된 알림을 삭제합니다. 관련 수신자와 알림 로그도 함께 삭제됩니다.
json - 응답
{
"message": "알림이 삭제되었습니다."
}GET
/api/v1/alerts/owner-name소유자 조회고유번호에 대한 소유자 이름을 최근 열람 데이터에서 조회합니다.
Query Parameters
| 파라미터 | 타입 | 기본값 | 설명 |
|---|---|---|---|
| uniqueNumber* | string | — | 고유번호 |
bash
curl -X GET "https://deunggigo.kr/api/v1/alerts/owner-name?uniqueNumber=1341-2004-008457" \
-H "Authorization: Bearer dgg_xxx"json - 응답
{
"ownerName": "홍길동"
}에러 코드
공통 에러 응답 형식
json
{
"error": "에러 메시지"
}HTTP 상태 코드
| 상태 코드 | 설명 |
|---|---|
| 400 | 필수 파라미터 누락 또는 잘못된 값 |
| 401 | API 키가 없거나 유효하지 않음 |
| 402 | 크레딧 부족 — 충전 후 재시도 |
| 404 | 요청한 리소스를 찾을 수 없음 |
| 409 | 중복 요청 |
| 500 | 서버 오류 — 잠시 후 재시도 |