다운로드는 끝났는데 PDF가 안 열린다: 등기 자동수집에 파일 검증 단계를 넣는 법

에이픽 API를 소개하는 홍보 글입니다. 아래 업무는 실제 고객 후기가 아닌 가상 도입 시나리오입니다. 공식 명세는 2026년11월5일 확인했으며, API를 실제 호출하거나 유료 발급을 수행하지 않았습니다. 화면4장은 2026년10월28일 공개 문서 보관 캡처입니다.

반복업무에서 먼저 풀 문제

부동산 관리팀은 “다운로드 완료”라고 표시된 파일을 회의 직전에 열었습니다. 그런데 PDF 뷰어가 오류를 냅니다. 가상 시나리오에서 원인은 모든 HTTP 응답을 등본.pdf라는 이름으로 저장한 코드였습니다.

등기 열람·발급의 정상 결과는 PDF 바이너리지만 오류나 처리 대기 안내는 JSON일 수 있습니다. 파일이 존재한다는 사실만으로 문서 수신을 완료 처리하면 사람은 뒤늦게 실패를 발견합니다.

화면 1. 정보를 입력하지 않은 APICK 회원가입 양식. 2026년 10월 28일 보관 캡처이며 실제 가입 완료나 키 발급을 의미하지 않습니다.

에이픽 연동과 우리 업무의 연결

응답을 임시 파일로 받고 HTTP 상태, Content-Type, 파일 시작부분을 차례로 확인합니다. PDF 헤더는 형식의 1차 확인에 불과하므로 이후 내부 PDF 파서의 정상 열림 여부도 점검합니다. 문서의 진위나 대상 일치는 별도 확인입니다. API 원문을 공개 로그에 복사하지 않습니다.

먼저 apick.app에서 계정과 해당 상품의 이용 조건을 확인합니다. API 키는 서버의 환경변수 APICK_API_KEY로 참조하고 브라우저·글·캡처에 값이 나타나지 않게 합니다. 대상 식별정보는 업무 권한과 목적을 확인한 뒤 서버에서 연결합니다. 아래 내부 설계 코드는 APICK이 기본 제공하는 업무관리 기능이 아닙니다.

화면 2. 공식 인증키·서버 환경변수 안내의 보관 캡처(2026년 10월 28일). 실제 API 키를 노출하지 않는 설명용 화면입니다.

요청 curl과 응답 형식

공식 문서 기반의 정적 요청 예시입니다. 실제 값과 실행 결과가 없으며 환경변수는 실행 전에 승인된 범위에서 준비해야 합니다. 아래는 열람(view) 요청입니다. 발급(issue)은 용도와 비용을 별도로 확인해야 합니다.

curl --request POST 'https://apick.app/rest/registry_realestate_jobs' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string "pin=${APICK_PROPERTY_PIN}" \
  --form-string 'usage=view' \
  --form-string "idempotency_key=${APICK_REQUEST_ID}" \
  --dump-header response.headers \
  --output result.bin

정상 응답 형식은 아래와 같습니다. 실제 수신 로그가 아닌 형식 설명입니다. PDF 원문과 실제 작업번호는 공개하지 않습니다.

Content-Type: application/pdf
본문: PDF 바이너리 (문서 원문 비공개)

오류·지연 응답은 JSON일 수 있습니다. HTTP 상태와 Content-Type을 확인하고, 문서 형식 검증 이후에 완료 처리합니다. 지연 예외에 data.pdf=preparing 및 data.job_id가 안내되지만 모든 응답이 같은 JSON이라는 뜻은 아닙니다.

화면 3. 부동산 등기 검색 API 공식 명세의 보관 캡처(2026년 10월 28일). 검색 단계의 안내이며 PDF 열람·발급 성공 결과가 아닙니다.

이 시나리오의 핵심 구현

# 우리 서버의 응답 분류 예시. 본문을 로그로 출력하지 않습니다.
def classify_response(http_status, content_type, body):
    if http_status < 200 or http_status >= 300:
        return "요청 결과 검토"
    mime = content_type.split(";", 1)[0].strip().lower()
    if mime == "application/pdf" and body.startswith(b"%PDF-"):
        return "PDF 파서 검증 대기"
    if mime == "application/json":
        return "오류 또는 처리 상태 확인"
    return "알 수 없는 형식: 수동 검토"

지연 JSON에 data.pdf=preparing과 data.job_id가 올 수 있다는 공식 안내가 있습니다. 이를 빈 PDF로 취급하거나 즉시 새 발급으로 대체하지 않습니다. 상태 확인·동일 작업 재시도 방법은 현재 문서와 저장된 요청 이력에 맞춥니다.

비용과 운영 조건

공식 안내상 열람850P, 발급1250P이며 무료 포인트 사용 불가·최소1회 결제 조건이 있습니다. 포인트는 원화 청구액이나 매출과 구분합니다. 최대180초 처리 안내와 요청 제한이 있으므로 5초 또는 대량 작업 몇 분 완료를 보장하지 않습니다. 문서 보관은72시간, 별도 재다운로드는30P입니다. 최초 요청과 별도 재다운로드를 혼동하지 않습니다.

화면 4. 공식 시작하기의 정적 info cURL 예시 보관 캡처(2026년 10월 28일). 위 부동산 검색·PDF 요청의 실행 화면이나 응답 결과가 아니며 일반적인 API 요청 형식을 설명하는 참고 화면입니다.

도입 후 무엇을 확인할까

사용자에게 보여줄 “완료”의 기준을 파일 생성에서 검증된 문서 연결로 바꾸면 회의 직전 오류를 찾는 일이 줄어들도록 설계할 수 있습니다. 오류 감소율은 운영 전후에 직접 측정해야 합니다.

운영 전후에 담당자의 수작업 시간, 확인이 필요한 건수, 검증 완료 건수와 비용을 같은 기준으로 기록하세요. 수동 한 건2~3분이라는 가정을 사용하더라도 실제 절감시간은 대상 확인·승인·기관 처리·예외 대응 시간을 포함해 측정해야 합니다. 이름·주소·대상번호·키·PDF·다운로드 링크는 공개 글과 공유 로그에서 제외합니다.

공식 서비스: apick.app
공식 API 명세: registry_realestate_jobs