택배 배송조회 API 연동: 주문 화면에 배송 이력과 오류 상태 붙이기

10월 11, 2026

택배 상자와 배송 차량, 배송 단계 이력 및 조회 불가 상태를 구분한 APICK 배송조회 개념도 — 이해를 돕기 위한 AI 생성 개념 이미지입니다. 실제 API 응답 화면이 아닙니다.

배송 문의가 들어올 때마다 운영자가 택배사 홈페이지를 옮겨 다니고 있다면, 주문 상세 화면에 배송 이력을 붙이는 것부터 시작할 수 있습니다. 택배사마다 다른 응답을 서비스 내부의 한 가지 화면으로 정리하는 것이 핵심입니다.

APICK 택배 배송조회는 지정한 택배사와 운송장으로 조회하는 경로, 택배사를 자동으로 찾는 경로를 제공합니다. 주문 데이터에 택배사 코드가 있는지에 따라 두 경로를 선택하면 비용과 오인식 가능성을 함께 관리할 수 있습니다.

택배사를 알면 지정조회부터 사용하세요

지정조회: POST /rest/parcel_tracking, 필수값 carrier와 trackingNumber, 건당 5P
자동조회: POST /rest/parcel_tracking_auto, 필수값 trackingNumber, 건당 10P
택배사 목록: POST /rest/parcel_tracking_carriers, 공식 가이드에서 무료로 안내

자동조회는 최대 5개 후보를 확인합니다. 모든 운송장을 반드시 식별하는 기능으로 받아들이면 안 됩니다. 예를 들어 일본 택배의 일부 숫자형 운송장은 자동조회에서 제외되므로, 해당 택배사 코드를 지정해야 합니다. 지원 목록과 현재 연결 상태는 공식 가이드에서 확인하세요.

1. 지정조회 cURL 예제

아래 carrier=cj는 공식 문서의 CJ대한통운 코드입니다. 운송장 변수에는 본인 서비스에서 취급할 권한이 있는 운송장만 넣습니다. 예제의 시간 제한은 구현 예시이며 응답 시간 보장이 아닙니다.

curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking' \
  --header "Authorization: Bearer ${APICK_API_KEY:?서버 인증키가 필요합니다}" \
  --form-string 'carrier=cj' \
  --form-string "trackingNumber=${TRACKING_NUMBER:?조회할 운송장이 필요합니다}" \
  --connect-timeout 10 --max-time 60

2. Node.js에서 실패 상태까지 화면용으로 정리하기

export async function trackParcel(carrier, trackingNumber) {
  const apiKey = process.env.APICK_API_KEY;
  if (!apiKey) throw new Error("APICK_API_KEY가 필요합니다");
  if (!carrier || !trackingNumber) throw new Error("택배사와 운송장을 입력하세요");
  const form = new FormData();
  form.set("carrier", carrier);
  form.set("trackingNumber", trackingNumber);
  const response = await fetch("https://apick.app/rest/parcel_tracking", {
    method: "POST",
    headers: { Authorization: `Bearer ${apiKey}` },
    body: form,
    signal: AbortSignal.timeout(60_000)
  });
  if (!response.ok) throw new Error(`배송조회 HTTP ${response.status}`);
  const result = await response.json();
  if (result.api?.success !== true) throw new Error("조회 서버 응답을 확인하세요");
  if (result.data?.success !== 1) {
    return { ok: false, code: result.data?.code ?? "UNSPECIFIED",
      costPoints: result.api.cost };
  }
  return {
    ok: true,
    carrier: result.data.carrier,
    status: result.data.status,
    carrierStatus: result.data.carrierStatus,
    events: Array.isArray(result.data.events) ? result.data.events : [],
    checkedAt: new Date().toISOString(),
    costPoints: result.api.cost
  };
}

자동조회로 바꾸려면 요청 URL을 /rest/parcel_tracking_auto로 바꾸고 carrier 필드를 보내지 않습니다. 자동조회가 이미 성공해 택배사를 확인했다면, 이후 조회에서 그 코드를 이용하는 설계를 검토할 수 있습니다. 운송장 형식이 바뀌거나 반품 운송장이 새로 생성되는 경우에는 원 주문과 반품 배송을 별도 레코드로 관리하세요.

배송 상태와 조회 오류를 다른 영역에 표시하기

성공 응답의 data.status는 배송 단계를 표시하며, data.carrierStatus에는 택배사의 원문 상태가 들어갑니다. data.events는 오래된 이력부터 정렬됩니다. 화면에서 최신 이력을 위에 보여주려면 원본 배열을 복사한 뒤 역순으로 표시하세요. IN_TRANSIT, OUT_FOR_DELIVERY, DELIVERED 등의 값을 서비스 문구로 매핑하되, UNKNOWN은 원문 상태를 함께 보여주는 편이 낫습니다.

NOT_FOUND: 송장 발급 직후 미등록일 수 있습니다. 배송 실패로 단정하지 말고 등록 여부와 입력값을 확인합니다.
UPSTREAM_TIMEOUT·UPSTREAM_UNAVAILABLE: 택배사 응답 지연과 일시 장애입니다. 재시도 간격을 두고 마지막 성공 조회 시각을 표시합니다.
AUTH_REQUIRED·LOGIN_REQUIRED: 공개 조회로 확인할 수 없는 경우입니다. 고객의 추가 인증을 임의로 우회하지 않습니다.

주문 페이지가 새로고침될 때마다 전체 배송 이력을 요청하는 방식은 피하는 편이 좋습니다. 내부 동시 요청을 합치고, 배달 완료 건에는 자동 조회를 멈추는 규칙을 둘 수 있습니다. APICK 문서는 실시간 조회 결과를 저장하지 않는다고 설명합니다. 우리 서비스가 따로 보관하는 내역에는 별도의 접근 권한과 삭제 정책이 필요합니다. 조회 응답에 수취인 이름·전화번호·상세주소가 제공된다고 가정하지 마세요.

비용: 지정조회와 자동조회를 구분해야 합니다

2026-10-11 기준 지정조회 5P, 자동조회 10P입니다. 예를 들어 성공한 지정조회 10,000건은 50,000P, 같은 수의 자동조회는 100,000P입니다. 공식 문서는 배송정보 없음이나 택배사 오류 등 조회 실패에는 과금하지 않는다고 안내합니다. 단순히 월 주문 수를 비용 기준으로 쓰지 말고, 주문당 실제 조회 횟수를 곱해 계산하세요. 원화 결제금액과 세금 조건은 충전 시 별도 확인합니다.

자주 묻는 질문

Q. 38개 택배사가 항상 정상 조회되나요?
지원 목록과 실시간 연결 상태는 다릅니다. 가이드의 상태 목록을 확인하고 장애 안내를 준비하세요.

Q. 자동조회가 지정조회보다 더 정확한가요?
문서에서는 택배사를 모를 때 사용하는 경로로 제공합니다. 코드가 확보돼 있으면 지정조회로 대상을 분명하게 정할 수 있습니다.

Q. 배송조회 성공과 배달 완료는 같은 뜻인가요?
다릅니다. data.success는 조회 결과의 성공 여부이고, 실제 배송 단계는 data.status로 확인합니다.

공식 문서에서 다음 단계 확인하기

APICK 택배 배송조회 개발가이드에서 전체 필드와 최신 조건을 확인해 보세요. 먼저 비식별 테스트 입력으로 응답 분기를 검토한 뒤, 서버 연동과 사용량 집계를 붙이는 순서가 좋습니다.

문서·요금 확인일: 2026-10-11 (UTC). 공식 요금표 · 인증·연동 시작하기 · 공식 Node.js SDK 가이드. 이 글의 코드는 공개 명세를 바탕으로 만든 설명용 예제이며 실제 API 호출로 실행 검증하지 않았습니다. 실제 개인정보나 인증키를 예제에 넣지 않았습니다.

#APICK #택배배송조회 #쇼핑몰개발 #API연동

이 블로그 검색

apick