같은 주소에서 후보가 여러 개 나왔다: 부동산 등기 API의 선택 오류를 줄이는 법

에이픽 서비스를 소개하는 홍보 글입니다. 아래는 가상 업무 시나리오이며 실제 고객 후기나 실측 결과가 아닙니다. API 설명은2026년11월5일12:19 UTC에 재확인한 공식 문서를 기준으로 작성했고, 삽입된4장은2026년10월28일의 공개 보관 화면으로 현재 성공 결과와 구분합니다.

이번에 해결하려는 문제

관리물건의 주소를 넣었는데 검색 결과가 하나가 아닙니다. 비슷한 이름의 건물, 여러 동과 호수, 도로명과 지번 표기가 섞여 있으면 ‘첫 번째 결과’를 바로 발급 요청에 넣고 싶어집니다. 하지만 검색 성공이 곧 의도한 물건을 찾았다는 뜻은 아닙니다.

가상의 관리업체 업무에서 자동화할 부분과 사람이 선택할 부분을 나눠보겠습니다. 목적은 잘못된 대상을 고른 뒤 다시 문서를 요청하는 일을 줄이는 것입니다. 소유권·권리관계 판단을 자동화하는 시나리오는 아닙니다.

화면1. 2026년10월28일 공식 공개 보관 캡처. 빈 회원가입 양식, 실제 가입·키 발급을 진행한 화면이 아닙니다.

호출 전에 정할 기준

공식 검색 응답의 targets 배열을 사용자 선택 화면에 연결합니다. 각 후보의 종류와 주소를 담당자가 비교하고 확정한 식별정보만 다음 문서 요청으로 전달합니다. 배열의 첫 항목을 무조건 선택하지 않습니다.

검색 결과는 최대 10개라는 문서 안내가 있으므로 화면에 열 건이 보인다고 전체 후보가 정확히 열 개라고 단정하지 않습니다. 주소를 더 구체화해 다시 검색해야 하는지 검토하고, 문서에 없는 페이지 번호나 전체검색 옵션을 임의로 만들지 않습니다. 다시 검색하면 결과 순서가 달라질 수 있으므로 예전 화면의 index를 새 검색에 그대로 적용하지 않습니다.

화면2. 2026년10월28일 공식 공개 보관 캡처. 서버 인증키 보관 안내, 실제 비밀키를 보여주는 화면이 아닙니다.

화면3. 2026년10월28일 공식 공개 보관 캡처. 부동산 등기 검색 공식 명세. 2026년10월28일 보관 화면이며 실제 조회·PDF 발급 결과가 아닙니다.

공식 요청을 연결하는 예시

다음 코드는 공식 문서의 경로와 필드에 기반한 정적 예시입니다. 실제 호출하지 않았습니다. 서버 환경변수의 실제 값은 글이나 로그에 공개하지 마세요.

curl --request POST 'https://apick.app/rest/registry_realestate_search' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string "query=${APICK_PROPERTY_QUERY}"

아래는 공식 응답 형식 또는 부분 구조를 설명한 정적 예시입니다. 식별정보는 가렸으며 실제 처리 로그가 아닙니다.

{"data":{"total":1,"targets":[{"index":1,"pin":"[가림]","kind":"건물","address":"[가림]","road_address":"[가림]","lot_address":"[가림]","status":"열람가능"}]},"api":{"success":true,"cost":40}}

검색과 문서요청을 분리한다

아래 curl은 검색 단계만 수행하는 공식 정적 예시입니다. 응답의 pin과 주소는 공개 글에서 가렸습니다. 실제 물건을 검색하거나 PDF를 발급한 결과가 아닙니다. 반환된 후보를 확인한 뒤 문서 요청 API의 현재 입력 조건에 맞게 연결해야 합니다.

담당자가 후보를 고르기 전에 유료 열람 요청을 자동으로 보내지 않습니다. 검색 결과 없음, 후보가 여러 개, 선택 완료를 우리 시스템의 서로 다른 상태로 기록합니다. 이 상태명은 APICK 응답값을 새로 만든 것이 아니라 업무 화면의 표시 이름입니다.

화면4. 2026년10월28일 공식 공개 보관 캡처. 공통 시작하기 info cURL 정적 예시이며 본문 해당상품의 실제 실행 결과가 아닙니다.

비용보다 먼저 확인할 선택 기준

대상이 있는 검색은 40P이며 대상 없음·실패는 0P라는 공식 안내가 있습니다. 검색은 보통40초 이내·최대120초 안내이고 클라이언트130초 이상 대기를 권장합니다. 무료 포인트 사용 불가와 최소1회결제 조건도 확인해야 합니다. 열람·발급 비용은 검색과 별도입니다.

성과를 보려면 후보 확인에 걸린 시간, 다시 검색한 건수, 잘못 선택해 재요청한 건수를 기록합니다. ‘항상 몇 초면 정확한 문서’라고 약속하는 대신, 잘못된 선택을 다음 단계로 넘기지 않는 구조를 먼저 만듭니다.

실제 운영 전에는 해당 상품의 현재 이용조건·과금·처리시간·개인정보 처리 권한을 확인하세요. 모든 업무를 몇 분 안에 끝낸다는 보장은 하지 않습니다.

공식 서비스: https://apick.app

공식 명세: https://apick.app/dev_guide/registry_realestate_search