개발가이드배송택배 배송조회

택배 배송조회 API

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

국내 택배부터 일본·중국·유럽 국제배송까지 하나의 형식으로 배송현황을 조회합니다. 호출할 때마다 그 시점의 최신 배송현황을 돌려주며, 운송장번호만 있고 택배사를 모를 때는 자동조회(/rest/parcel_tracking_auto)를 쓰면 됩니다.

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

왜 택배 배송조회인가

택배사 수십 곳, API 하나로 끝

택배사마다 화면도 응답 형식도 제각각이라 연동이 끝없이 늘어납니다. 운송장번호 하나로 국내외 배송현황과 이동내역을 같은 형식으로 받아 고객 화면에 바로 띄우세요.

도입 효과

  • 택배사별 연동 개발을 한 번에 정리
  • "배송 어디예요" 문의를 화면에서 해결
  • 이동내역을 같은 형식으로 저장·분석

이런 곳에서 많이 씁니다

  • 쇼핑몰 주문상세 배송 추적 화면
  • 고객센터 챗봇 배송 문의 자동 응답
  • 물류 관제 대시보드 지연 건 감시
  • 중고거래 앱 안전결제 배송 확인
가입하고 API 키 받기API 키 하나로 바로 호출 · 실패한 요청은 과금되지 않습니다

알아둘 점

기능·제공 범위 전체 펼쳐 보기
국내외 38개 택배사 지원

국내 택배·편의점·당일배송과 일본우편·TNT·4PX 등 해외배송을 한 API로 조회

통일된 배송상태

택배사마다 다른 상태 문구를 13가지 표준 상태값(status)으로 맞춰 제공

택배사 자동인식

운송장번호만으로 택배사를 판별해 조회

이용 전 확인

조회에 성공한 호출만 과금됩니다. 배송정보가 없거나 조회에 실패하면 data.error와 data.code로 응답하며 과금되지 않습니다.

택배사를 알면 지정조회(/rest/parcel_tracking)가 더 빠르고 저렴합니다. 자동조회는 택배사를 모를 때만 쓰세요.

국내 운송장번호와 헷갈리지 않도록 일본 택배사의 숫자 10자리·12자리 번호는 자동조회에서 판별하지 않습니다. 야마토운수는 carrier=yamato_japan, 일본우편 숫자 12자리는 carrier=japan_post를 지정해 호출하세요. 일본우편 숫자 11·13자리와 국제우편(UPU S10, 예: EE123456789JP) 형식은 자동조회할 수 있습니다.

SF Express, ECMS, 롯데 국제조회는 현재 지원 목록에 없습니다.

SF Express, ECMS, 롯데 국제조회는 지원하지 않습니다.

비용

엔드포인트
비용
설명
택배사 지정조회
/rest/parcel_tracking
5pt
carrier + trackingNumber 지정 조회
택배사 자동조회
/rest/parcel_tracking_auto
10pt
최대 5개 후보 택배사 동시 조회
택배사 목록 조회
/rest/parcel_tracking_carriers
무료
파라미터 없이 정상조회 가능·점검중 택배사 목록 조회

배송정보가 없거나 조회에 실패하면 과금되지 않습니다.

요청과 응답

1API 요청
POST/rest/parcel_tracking
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 2개 · 필수 2
파라미터
설명
carrierstring필수
택배사 코드 (예: cj, hanjin, lotte, logen, epost-domestic)
예시
cj
trackingNumberstring필수
조회할 운송장번호입니다. 택배사별 자릿수·형식이 다르며, 하이픈 없이 숫자만 입력하는 것을 권장합니다.
예시
123456789012
응답 필드 28개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.carrierobject
택배사 정보 묶음입니다. 택배사 코드와 표시 이름을 함께 제공하며, 코드는 이후 배송 조회 요청의 carrier 값으로 사용합니다.
data.trackingNumberstring
하이픈을 빼고 대문자로 맞춘 운송장번호입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.statusstring
현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다.
data.carrierStatusstring
택배사가 표시한 상태 문구 그대로입니다. 예: 배달완료. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.queriedAtstring
조회 시각(ISO 8601)입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.lastEventobject
가장 최근 배송 이력입니다. 이력이 없으면 null입니다. 항목 구조는 events[]와 같습니다. null 허용.
data.eventsarray
배송 이벤트 목록입니다. 오래된 순서에서 최신 순서로 정렬되며, 이벤트가 없으면 빈 배열입니다.
data.successinteger
업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.
data.requestedCarrierobject
요청한 택배사가 다른 택배사에 배송을 맡긴 경우에만 옵니다. 요청한 택배사 {code, name}입니다.
data.actualCarrierobject
위 경우 실제로 배송하는 택배사입니다. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costinteger
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.msinteger
서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
하위 필드 12개 더 보기
응답 필드
설명
data.carrier.codestring
택배사를 구분하는 코드입니다. 예: cj, hanjin, lotte. 같은 택배사는 조회마다 같은 코드로 오며, 배송 조회 요청의 carrier에 그대로 넣습니다.
data.carrier.namestring
택배사의 표시 이름입니다. 고객 화면에 보여 줄 이름이며, 코드와 달리 표기가 바뀔 수 있습니다.
data.lastEvent.timestring
'time' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
data.lastEvent.locationstring
위치·지역 정보입니다. 제공되지 않으면 null이거나 생략됩니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.lastEvent.statusstring
현재 처리 상태입니다. 서비스별 상태 값과 다음 행동은 같은 문서의 상태 표를 확인하세요.
data.lastEvent.carrierStatusstring
'carrierStatus' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
data.lastEvent.descriptionstring
대상의 설명문입니다. 게시자·서비스가 작성한 소개문이며, 줄바꿈과 이모지가 포함될 수 있습니다. 비어 있으면 설명이 등록되지 않은 것입니다.
data.events[].timestring
배송 이벤트가 발생한 시각입니다. 한국시간 ISO 8601 형식이며, 이벤트는 오래된 순서에서 최신 순서로 정렬됩니다.
data.events[].locationstring
이벤트를 처리한 지점·지역입니다. 택배사가 제공하지 않으면 null이거나 생략됩니다.
data.events[].statusstring
정규화된 배송 상태입니다. 택배사마다 다른 원문 문구를 공통 값으로 변환한 결과입니다. 가능한 값은 13가지입니다. UNKNOWN = 판별 불가, INFO_RECEIVED = 운송장 접수, PICKED_UP = 집화 완료, AT_ORIGIN = 출발 영업소 도착, IN_TRANSIT = 간선 이동 중, AT_HUB = 중간 허브 도착, AT_DESTINATION = 배송지 영업소 도착, OUT_FOR_DELIVERY = 배송 출발, DELIVERED = 배송 완료, DELIVERY_FAILED = 수취 실패, EXCEPTION = 분실·파손·주소 오류 등 예외, RETURNING = 반송 중, RETURNED = 반송 완료입니다. carrierStatus에는 택배사 원문이 그대로 오므로 두 값을 함께 보세요.
data.events[].carrierStatusstring
택배사가 표시한 원문 상태 문구입니다. 정규화 값과 함께 보관하면 문의 대응에 도움이 됩니다.
data.events[].descriptionstring
이벤트 상세 설명입니다. 원문 상태와 같은 문구가 오는 경우가 많습니다.
2API 요청
POST/rest/parcel_tracking_auto
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 1개 · 필수 1
파라미터
설명
trackingNumberstring필수
조회할 운송장번호입니다. 택배사별 자릿수·형식이 다르며, 하이픈 없이 숫자만 입력하는 것을 권장합니다.
예시
123456789012
응답 필드 28개
응답 필드
설명
dataobject
요청 처리 결과 묶음입니다. 조회한 값·작업 상태·오류 설명이 이 안에 들어 있으며, 실제 하위 필드 구성은 서비스마다 다릅니다. 값이 없으면 null·빈 배열·필드 생략 중 해당 서비스의 규칙을 따릅니다.
data.carrierobject
택배사 정보 묶음입니다. 택배사 코드와 표시 이름을 함께 제공하며, 코드는 이후 배송 조회 요청의 carrier 값으로 사용합니다.
data.trackingNumberstring
하이픈을 빼고 대문자로 맞춘 운송장번호입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.statusstring
현재 처리 상태 코드입니다. 괄호 안 설명은 이 서비스에서의 상태 의미이며, 값별 다음 행동은 이 문서의 상태 표를 확인하세요. 상태가 바뀌면 같은 경로를 다시 조회합니다.
data.carrierStatusstring
택배사가 표시한 상태 문구 그대로입니다. 예: 배달완료. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.queriedAtstring
조회 시각(ISO 8601)입니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.lastEventobject
가장 최근 배송 이력입니다. 이력이 없으면 null입니다. 항목 구조는 events[]와 같습니다. null 허용.
data.eventsarray
배송 이벤트 목록입니다. 오래된 순서에서 최신 순서로 정렬되며, 이벤트가 없으면 빈 배열입니다.
data.successinteger
업무 처리 결과 코드입니다. 1은 정상 결과, 0은 실패 또는 무료 응답입니다. 서비스에 따라 2·3처럼 추가 코드를 쓰므로 같은 응답의 status·msg·error 필드도 함께 확인하세요.
data.requestedCarrierobject
요청한 택배사가 다른 택배사에 배송을 맡긴 경우에만 옵니다. 요청한 택배사 {code, name}입니다.
data.actualCarrierobject
위 경우 실제로 배송하는 택배사입니다. 하위 필드에 코드·이름·상태 같은 세부 값이 들어 있으며, 자료가 없으면 빈 객체이거나 생략됩니다.
apiobject
API 호출 메타데이터입니다. 이번 요청의 서버 처리 성공 여부(api.success), 실제 차감 포인트(api.cost), 결제 기록 ID(api.pl_id)를 담습니다. 처리 시간(api.ms)은 응답에 포함된 경우에만 제공됩니다. 업무 결과는 data에서 확인합니다.
api.successboolean
API 서버가 이번 요청을 정상 처리했는지 여부입니다. true여도 업무 결과가 실패일 수 있으므로 data.success·data.status와 함께 판단합니다. 인증 실패·잘못된 입력·서버 오류 응답에서는 false입니다.
api.costinteger
이번 호출에서 실제로 차감된 포인트입니다. 유료 성공 응답에서만 단가만큼 차감되며, 실패·무료 조회·같은 요청의 멱등 재전송은 0입니다. 화면의 표시 단가와 실제 차감액이 다를 수 있으므로 정산은 이 값을 기준으로 합니다.
api.msinteger
서버가 요청을 받아 응답 본문을 만들기까지 걸린 처리 시간(밀리초)입니다. 네트워크 왕복 시간과 클라이언트 대기 시간은 포함되지 않습니다.
api.pl_idinteger
포인트 차감 기록 ID입니다. 차감이 발생한 호출에만 값이 있으며, 과금 내역을 문의할 때 이 번호를 사용합니다. 무과금 응답은 -1·null이거나 필드가 생략됩니다.
하위 필드 12개 더 보기
응답 필드
설명
data.carrier.codestring
택배사를 구분하는 코드입니다. 예: cj, hanjin, lotte. 같은 택배사는 조회마다 같은 코드로 오며, 배송 조회 요청의 carrier에 그대로 넣습니다.
data.carrier.namestring
택배사의 표시 이름입니다. 고객 화면에 보여 줄 이름이며, 코드와 달리 표기가 바뀔 수 있습니다.
data.lastEvent.timestring
'time' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
data.lastEvent.locationstring
위치·지역 정보입니다. 제공되지 않으면 null이거나 생략됩니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
data.lastEvent.statusstring
현재 처리 상태입니다. 서비스별 상태 값과 다음 행동은 같은 문서의 상태 표를 확인하세요.
data.lastEvent.carrierStatusstring
'carrierStatus' 문자열 값입니다. 값이 없으면 빈 문자열이거나 필드가 생략됩니다.
data.lastEvent.descriptionstring
대상의 설명문입니다. 게시자·서비스가 작성한 소개문이며, 줄바꿈과 이모지가 포함될 수 있습니다. 비어 있으면 설명이 등록되지 않은 것입니다.
data.events[].timestring
배송 이벤트가 발생한 시각입니다. 한국시간 ISO 8601 형식이며, 이벤트는 오래된 순서에서 최신 순서로 정렬됩니다.
data.events[].locationstring
이벤트를 처리한 지점·지역입니다. 택배사가 제공하지 않으면 null이거나 생략됩니다.
data.events[].statusstring
정규화된 배송 상태입니다. 택배사마다 다른 원문 문구를 공통 값으로 변환한 결과입니다. 가능한 값은 13가지입니다. UNKNOWN = 판별 불가, INFO_RECEIVED = 운송장 접수, PICKED_UP = 집화 완료, AT_ORIGIN = 출발 영업소 도착, IN_TRANSIT = 간선 이동 중, AT_HUB = 중간 허브 도착, AT_DESTINATION = 배송지 영업소 도착, OUT_FOR_DELIVERY = 배송 출발, DELIVERED = 배송 완료, DELIVERY_FAILED = 수취 실패, EXCEPTION = 분실·파손·주소 오류 등 예외, RETURNING = 반송 중, RETURNED = 반송 완료입니다. carrierStatus에는 택배사 원문이 그대로 오므로 두 값을 함께 보세요.
data.events[].carrierStatusstring
택배사가 표시한 원문 상태 문구입니다. 정규화 값과 함께 보관하면 문의 대응에 도움이 됩니다.
data.events[].descriptionstring
이벤트 상세 설명입니다. 원문 상태와 같은 문구가 오는 경우가 많습니다.
3API 요청
POST/rest/parcel_tracking_carriers
  • Bearer 인증
  • multipart/form-data
  • JSON 응답
요청 파라미터 없음

추가 폼 항목이 없습니다. 인증 헤더만 보내면 됩니다.

응답 필드 50개
응답 필드
설명
successboolean
목록 조회 성공 여부. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 해당 처리가 정상 완료된 경우, false = 실패·대상 없음으로 결과를 쓸 수 없는 경우입니다.
updatedAtstring
목록의 최근 갱신 시각. ISO 8601 일시. 이력이 없으면 null. null 허용.
summaryobject
택배사 상태를 한눈에 보여 주는 요약 집계입니다. 전체·조회 가능·점검 중인 택배사 수를 담으며, 개별 목록은 아래 배열에서 확인하세요.
summary.totalinteger
상태 집계 대상 택배사의 전체 수입니다. 조회 가능·점검 중인 수를 합한 값과 일치합니다.
summary.activeinteger
현재 정상적으로 배송 조회를 지원하는 택배사 수입니다. 전체 중 점검·확인 중인 곳을 제외한 값입니다.
summary.maintenanceinteger
점검·확인 중이어서 일시적으로 조회가 제한된 택배사 수입니다. 0이면 모든 택배사가 정상입니다.
activeCarriersarray
현재 조회 가능한 택배사 목록입니다. 각 항목의 코드·이름·별칭을 함께 제공하며, 없으면 빈 배열입니다.
activeCarriers[].codestring
택배사 코드. 지정 조회의 carrier에 사용합니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
activeCarriers[].namestring
택배사 표시 이름. 대상의 표시 이름입니다. 같은 API에서도 사람·상품·채널 이름을 뜻할 수 있습니다.
activeCarriers[].aliasesarray
같은 택배사를 가리키는 다른 이름 목록입니다. 고객이 입력한 이름이 별칭과 일치하면 같은 택배사로 매핑할 수 있습니다.
activeCarriers[].serviceTypestring
택배사의 배송 서비스 분류입니다. 택배·화물·국제 등 서비스 범위를 구분합니다.
activeCarriers[].lookupTypestring
배송 조회에 필요한 입력 방식입니다. 운송장번호만으로 조회되는지, 택배사 코드가 필요한지 나타냅니다.
activeCarriers[].publicTrackingboolean
택배사가 고객용 배송 조회 페이지를 공개하는지 여부입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 택배사가 고객용 배송 조회 페이지를 공개한 경우, false = 택배사가 공개 배송 조회 페이지를 제공하지 않는 경우입니다.
activeCarriers[].statusstring
ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음. 가능한 값은 4가지입니다. ACTIVE = 정상 조회 가능한 상태입니다. 바로 요청할 수 있습니다. MAINTENANCE = 점검 중이라 조회할 수 없는 상태입니다. 복구된 뒤 같은 요청으로 다시 확인합니다. CHECKING = 상태를 확인 중인 값입니다. 잠시 후 같은 요청으로 다시 조회합니다. UNAVAILABLE = 상태 정보를 얻지 못한 값입니다. 일시 장애일 수 있으므로 재시도하고, 계속되면 문의하세요.
허용값
ACTIVE MAINTENANCE CHECKING UNAVAILABLE
activeCarriers[].availableboolean
현재 이 택배사의 조회가 가능한지 여부입니다. false면 점검 중이거나 일시적으로 조회할 수 없는 상태입니다. true = 지금 조회 가능한 경우, false = 점검 등으로 지금은 조회할 수 없는 경우입니다.
activeCarriers[].staleboolean
택배사 상태 정보가 갱신 기준 시간을 넘겼는지 여부입니다. true면 표시된 상태가 오래되었을 수 있습니다. true = 상태 정보가 갱신 기준 시간을 넘겨 오래된 경우, false = 최신 상태인 경우입니다.
activeCarriers[].checkedAtstring
최근 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
activeCarriers[].lastSuccessAtstring
최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
activeCarriers[].lastFailureAtstring
최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
activeCarriers[].errorCodestring
최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요. null 허용.
activeCarriers[].sourcestring
상태가 마지막으로 갱신된 방식의 구분값. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
maintenanceCarriersarray
점검·확인 중인 택배사 목록입니다. 조회가 제한된 기간에는 이 목록에만 나타날 수 있습니다.
maintenanceCarriers[].codestring
택배사 코드. 지정 조회의 carrier에 사용합니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
maintenanceCarriers[].namestring
택배사 표시 이름. 대상의 표시 이름입니다. 같은 API에서도 사람·상품·채널 이름을 뜻할 수 있습니다.
maintenanceCarriers[].aliasesarray
점검 중인 택배사의 별칭 목록입니다. 고객 입력 이름을 정규화할 때 사용하세요.
maintenanceCarriers[].serviceTypestring
점검 중인 택배사의 배송 서비스 분류입니다. 정상 복구 후 activeCarriers에서 다시 확인하세요.
maintenanceCarriers[].lookupTypestring
점검 중인 택배사의 조회 입력 방식입니다. 복구 후에도 같은 방식으로 조회합니다.
maintenanceCarriers[].publicTrackingboolean
점검 중인 택배사의 공개 조회 페이지 제공 여부입니다. false면 고객 안내에 자체 조회 화면을 쓰세요. true = 택배사가 고객용 배송 조회 페이지를 공개한 경우, false = 택배사가 공개 배송 조회 페이지를 제공하지 않는 경우입니다.
maintenanceCarriers[].statusstring
ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음. 가능한 값은 4가지입니다. ACTIVE = 정상 조회 가능한 상태입니다. 바로 요청할 수 있습니다. MAINTENANCE = 점검 중이라 조회할 수 없는 상태입니다. 복구된 뒤 같은 요청으로 다시 확인합니다. CHECKING = 상태를 확인 중인 값입니다. 잠시 후 같은 요청으로 다시 조회합니다. UNAVAILABLE = 상태 정보를 얻지 못한 값입니다. 일시 장애일 수 있으므로 재시도하고, 계속되면 문의하세요.
허용값
ACTIVE MAINTENANCE CHECKING UNAVAILABLE
maintenanceCarriers[].availableboolean
점검 중인 택배사의 현재 조회 가능 여부입니다. 점검 중에는 false입니다. true = 지금 조회 가능한 경우, false = 점검 등으로 지금은 조회할 수 없는 경우입니다.
maintenanceCarriers[].staleboolean
점검 중인 택배사의 상태 정보가 갱신 기준을 넘겼는지 여부입니다. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 상태 정보가 갱신 기준 시간을 넘겨 오래된 경우, false = 최신 상태인 경우입니다.
maintenanceCarriers[].checkedAtstring
최근 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
maintenanceCarriers[].lastSuccessAtstring
최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
maintenanceCarriers[].lastFailureAtstring
최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
maintenanceCarriers[].errorCodestring
최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요. null 허용.
maintenanceCarriers[].sourcestring
상태가 마지막으로 갱신된 방식의 구분값. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
carriersarray
전체 택배사 목록. 상태 집계 대상 밖의 항목은 UNAVAILABLE일 수 있습니다.
carriers[].codestring
택배사 코드. 지정 조회의 carrier에 사용합니다. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
carriers[].namestring
택배사 표시 이름. 대상의 표시 이름입니다. 같은 API에서도 사람·상품·채널 이름을 뜻할 수 있습니다.
carriers[].aliasesarray
같은 택배사를 가리키는 이름 목록. 각 항목의 구성은 서비스에 따라 다르며, 값이 없으면 빈 배열입니다. 항목 수와 순서를 함께 확인하세요.
carriers[].serviceTypestring
배송 서비스 분류. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
carriers[].lookupTypestring
조회 유형. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요.
carriers[].publicTrackingboolean
공개 배송 조회 지원 여부. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 택배사가 고객용 배송 조회 페이지를 공개한 경우, false = 택배사가 공개 배송 조회 페이지를 제공하지 않는 경우입니다.
carriers[].statusstring
ACTIVE=조회 가능, MAINTENANCE=점검 중, CHECKING=확인 중, UNAVAILABLE=상태 정보 없음. 가능한 값은 4가지입니다. ACTIVE = 정상 조회 가능한 상태입니다. 바로 요청할 수 있습니다. MAINTENANCE = 점검 중이라 조회할 수 없는 상태입니다. 복구된 뒤 같은 요청으로 다시 확인합니다. CHECKING = 상태를 확인 중인 값입니다. 잠시 후 같은 요청으로 다시 조회합니다. UNAVAILABLE = 상태 정보를 얻지 못한 값입니다. 일시 장애일 수 있으므로 재시도하고, 계속되면 문의하세요.
허용값
ACTIVE MAINTENANCE CHECKING UNAVAILABLE
carriers[].availableboolean
현재 조회 가능한지 여부. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 지금 조회 가능한 경우, false = 점검 등으로 지금은 조회할 수 없는 경우입니다.
carriers[].staleboolean
상태 정보가 갱신 기준을 넘겼는지 여부. true/false로 오며, 값이 없으면 필드가 생략되거나 null일 수 있습니다. true = 상태 정보가 갱신 기준 시간을 넘겨 오래된 경우, false = 최신 상태인 경우입니다.
carriers[].checkedAtstring
최근 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
carriers[].lastSuccessAtstring
최근 정상 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
carriers[].lastFailureAtstring
최근 실패 확인 시각. ISO 8601 일시. 이력이 없으면 null. 문자열로 오며, 값이 없으면 빈 문자열이거나 필드가 생략됩니다. 같은 응답의 다른 필드와 함께 해석하세요. null 허용.
carriers[].errorCodestring
최근 상태 확인 코드. 문제가 없거나 이력이 없으면 null. 알려지지 않은 코드도 처리하세요. null 허용.
하위 필드 0개 더 보기

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

입력 조건·전송 규칙

인증 헤더는 Authorization: Bearer 내 계정의 API 인증키입니다.

택배사 목록 조회(/rest/parcel_tracking_carriers)는 파라미터가 없고 무료입니다. 응답의 activeCarriers에는 지금 조회 가능한 택배사, maintenanceCarriers에는 점검중인 택배사가 담깁니다.

사용 예시

상황별로 보내는 값과 응답에서 확인할 값을 모았습니다. 언어 탭에서 그대로 복사해 쓸 수 있습니다.

예시 1. 택배사를 알 때 지정조회

주문 시스템에 택배사 코드가 저장돼 있으면 지정조회가 빠르고 저렴합니다.

요청POST/rest/parcel_tracking
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=123456789012'
  • data.status가 DELIVERED이면 배송 완료 처리합니다. 화면 문구는 data.carrierStatus를 씁니다.
  • data.lastEvent로 최근 위치·시각을 한 줄로 보여 줄 수 있습니다.
예시 2. 우체국 택배 조회

택배사 코드는 목록 조회 결과의 code 값을 그대로 씁니다.

요청POST/rest/parcel_tracking
curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'carrier=epost-domestic' \
  --form-string 'trackingNumber=6012345678901'
  • data.code가 NOT_FOUND이면 발송 직후일 수 있으니 몇 시간 뒤 다시 조회합니다(과금 없음).
예시 3. 택배사를 모를 때 자동조회

사용자가 운송장번호만 입력한 경우 택배사를 판별해 조회합니다.

요청POST/rest/parcel_tracking_auto
curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking_auto' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'trackingNumber=123456789012'
  • 판별된 택배사는 data.carrier.code에 담깁니다. 저장해 두고 다음부터는 지정조회를 씁니다.
  • data.code가 UNSUPPORTED_CARRIER이면 택배사를 사용자에게 고르게 한 뒤 지정조회합니다.
예시 4. 국제우편 번호 자동조회

국제우편 형식(영문 2자 + 숫자 9자 + 국가코드 2자)은 자동조회로 판별됩니다.

요청POST/rest/parcel_tracking_auto
curl --fail-with-body --request POST 'https://apick.app/rest/parcel_tracking_auto' \
  --header "Authorization: Bearer $APICK_API_KEY" \
  --form-string 'trackingNumber=EE123456789JP'
  • 일본 택배사의 숫자 10·12자리 번호는 자동조회되지 않으므로 carrier=yamato_japan·japan_post로 지정조회합니다.

응답 처리

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

배송상태(status) 값

data.status와 각 events[].status는 아래 값 중 하나만 반환합니다. 택배사별 원문 문구는 carrierStatus에 그대로 담깁니다.

status
의미
INFO_RECEIVED
접수·발송준비·수거지정 등 집화 전 상태
PICKED_UP
집화 완료(상품 인수·수거 완료)
AT_ORIGIN
출발지 거점 도착/처리
IN_TRANSIT
이동 중(간선·터미널·상하차 등 운송 구간)
AT_HUB
허브·교환국 등 주요 거점 도착
AT_DESTINATION
배송지(도착지) 인근 거점 도착
OUT_FOR_DELIVERY
배송 출발(배달원 배송 중)
DELIVERED
배달 완료
DELIVERY_FAILED
배달 실패·미배달(부재 등)
EXCEPTION
예외 상황(취소·분실·지연·사고 등)
RETURNING
반송 진행 중
RETURNED
반송 완료
UNKNOWN
정규화 불가(원문 상태만 carrierStatus로 제공)
오류 코드(data.code) 값

배송정보를 찾지 못했거나 조회에 실패하면 data.error(안내 문구)와 data.code(오류 코드)가 담기며 과금되지 않습니다. data.code는 아래 값 중 하나입니다.

code
의미
대처
INVALID_TRACKING_NUMBER
운송장번호가 비었거나 형식이 맞지 않습니다.
영문·숫자·하이픈만으로 다시 보냅니다. 같은 번호로 재시도해도 결과는 같습니다.
UNSUPPORTED_CARRIER
지원하지 않는 carrier 코드이거나, 자동조회에서 택배사를 판별하지 못했습니다.
택배사 목록의 code로 지정조회합니다.
NOT_FOUND
배송정보가 없습니다(아직 집화 전, 운송장 오탈자, 다른 택배사 등).
번호와 택배사를 확인합니다. 발송 직후라면 몇 시간 뒤 다시 조회합니다.
UPSTREAM_TIMEOUT
택배사 응답이 늦어 조회하지 못했습니다.
잠시 후 다시 조회합니다.
UPSTREAM_NETWORK_ERROR
일시적으로 택배사에 연결하지 못했습니다.
잠시 후 다시 조회합니다.
UPSTREAM_RATE_LIMITED
택배사 조회가 일시적으로 제한됐습니다.
몇 분 뒤 다시 조회합니다. 같은 번호를 짧은 간격으로 반복 조회하지 마세요.
UPSTREAM_BLOCKED
택배사 조회가 일시적으로 거부됐습니다.
몇 분 뒤 다시 조회합니다.
UPSTREAM_UNAVAILABLE
택배사 조회 시스템이 일시적으로 응답하지 않습니다.
택배사 상태 표를 확인하고 잠시 후 다시 조회합니다.
RESPONSE_CHANGED
일시적으로 결과를 읽지 못했습니다.
잠시 후 다시 조회합니다. 계속되면 문의해 주세요.
PARSE_FAILED
일시적으로 결과를 읽지 못했습니다.
잠시 후 다시 조회합니다. 계속되면 문의해 주세요.
LOGIN_REQUIRED
택배사 회원 로그인 후에만 볼 수 있는 운송장입니다.
지원하지 않습니다. 택배사 앱·홈페이지에서 확인하도록 안내합니다.
AUTH_REQUIRED
이름·전화번호 같은 본인확인이 필요한 운송장입니다.
지원하지 않습니다. 택배사 앱·홈페이지에서 확인하도록 안내합니다.
PUBLIC_TRACKING_UNAVAILABLE
공개 배송조회를 제공하지 않는 택배사·서비스입니다.
지원하지 않습니다.
INTERNAL_ERROR
알 수 없는 이유로 실패했습니다.
잠시 후 다시 조회합니다. 계속되면 문의해 주세요.

처음 보는 data.code가 와도 data.error가 있으면 실패로 처리하세요.

개인정보 보호를 위해 수취인 이름·전화번호·상세주소 등은 응답에 포함되지 않습니다.

원문 응답 필드 표 보기
택배사 상태·목록 API
이름
타입
설명
updatedAt
String|null
가장 최근 상태 반영 시각
summary
Object
전체·정상·점검중 택배사 수
activeCarriers
Array
현재 정상조회 가능한 택배사 목록
maintenanceCarriers
Array
점검중이거나 상태 확인 중인 택배사 목록
carriers[].status
String
ACTIVE, MAINTENANCE, CHECKING, UNAVAILABLE
carriers[].available
Boolean
현재 정상조회 가능 여부
carriers[].checkedAt
String|null
해당 택배사의 최근 상태 반영 시각
배송 조회 응답(지정조회·자동조회 공통)
필드
타입
설명
data.carrier
object
조회한 택배사 {code, name}입니다. 자동조회에서는 판별된 택배사입니다.
data.trackingNumber
string
하이픈을 빼고 대문자로 맞춘 운송장번호입니다.
data.status
string
표준 배송상태입니다. 아래 "배송상태(status) 값" 표를 보세요.
data.carrierStatus
string
택배사가 표시한 상태 문구 그대로입니다. 예: 배달완료.
data.queriedAt
string
조회 시각(ISO 8601)입니다.
data.lastEvent
object
가장 최근 배송 이력입니다. 이력이 없으면 null입니다. 항목 구조는 events[]와 같습니다.
data.events[]
array
배송 이력입니다. 오래된 순에서 최신 순으로 정렬됩니다.
data.events[].time
string
처리 시각(ISO 8601)입니다.
data.events[].location
string
처리 장소입니다.
data.events[].status
string
그 시점의 표준 배송상태입니다.
data.events[].carrierStatus
string
택배사 상태 문구입니다.
data.events[].description
string
이력 설명입니다.
data.requestedCarrier
object
요청한 택배사가 다른 택배사에 배송을 맡긴 경우에만 옵니다. 요청한 택배사 {code, name}입니다.
data.actualCarrier
object
위 경우 실제로 배송하는 택배사입니다.
data.success
integer
1이면 조회 성공(과금)입니다.
api.cost
integer
차감된 포인트입니다. 실패하면 0입니다.
api.pl_id
integer
결제 기록 번호입니다. 문의할 때 함께 알려 주세요.

오류 코드

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

  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
  }
}
서비스 코드·조건

택배사별 현재 조회 상태

택배사별로 지금 조회할 수 있는지 보여 줍니다. 점검중인 택배사는 조회가 실패할 수 있으며, 실패한 호출은 과금되지 않습니다. 같은 목록을 /rest/parcel_tracking_carriers로 받아 화면에서 점검중인 택배사를 미리 안내할 수 있습니다.

정상조회 가능 0개 점검중 38개 상태 확인 중
정상조회 가능한 택배사
No
택배사
carrier 코드
상태
-
상태 확인 중입니다.
-
확인 중
점검중인 택배사
No
택배사
carrier 코드
상태
1
CJ대한통운
cj
확인 중
2
한진택배
hanjin
확인 중
3
롯데글로벌로지스
lotte
확인 중
4
로젠택배
logen
확인 중
5
우체국 국내등기/소포
epost_domestic
확인 중
6
경동택배
kdexp
확인 중
7
일양로지스
ilyang
확인 중
8
컬리넥스트마일
kurlynextmile
확인 중
9
딜리박스
dbox
확인 중
10
CU편의점택배
cu_postbox
확인 중
11
대신택배
daesin
확인 중
12
SLX택배
slx
확인 중
13
우리택배
woori_delivery
확인 중
14
용마로지스
yongma
확인 중
15
레터스
letus
확인 중
16
두발히어로
doobalhero
확인 중
17
지니고 당일배송
geniego
확인 중
18
천일택배
chunil
확인 중
19
건영택배
kunyoung
확인 중
20
농협택배
nhlogis
확인 중
21
위니온택배
winionlogis
확인 중
22
합동택배
hdexp
확인 중
23
카카오T당일배송
todaypickup
확인 중
24
라스트마일
onedaylogis
확인 중
25
발렉스 특수물류
valex
확인 중
26
딜리래빗
drabbit
확인 중
27
성화기업택배
sunghwa
확인 중
28
EMS 국제우편
ems_international
확인 중
29
Cainiao(차이나/알리·테무 배후물류)
cainiao_global
확인 중
30
LX판토스 국제특송
lx_pantos
확인 중
31
ACT&CORE 해상수입
actcore_ocean
확인 중
32
일본우편(Japan Post)
japan_post
확인 중
33
야마토운수(일본)
yamato_japan
확인 중
34
TNT Express
tnt
확인 중
35
YunExpress
yunexpress
확인 중
36
4PX Express
four_px
확인 중
37
EFS
efs
확인 중
38
eParcel
eparcel
확인 중
인증·포인트 오류 result.error 문구
코드
HTTP
의미·조치
유효하지 않은 API키 입니다.
401
Authorization: Bearer 헤더의 인증키를 확인하세요.
허용되지 않은 IP주소 입니다.
401
마이페이지의 허용 IP 설정과 요청 서버 IP를 확인하세요.
비활성화된 계정입니다.
401
계정 이용 상태를 고객지원으로 문의하세요.
사용 가능한 포인트이 부족합니다.
200
HTTP 200이어도 result.error가 있으면 실패입니다. 포인트를 충전한 뒤 다시 요청하세요. 이 응답은 과금되지 않습니다.
인증 정보를 확인할 수 없습니다.
424
일시적인 확인 실패입니다. 잠시 후 다시 시도하세요.
폼 입력 오류 error.code
코드
HTTP
의미·조치
FORM_DATA_INVALID
400
필드 이름·값의 타입·배열 인덱스를 확인하세요. 인덱스는 0부터 연속으로 사용합니다.
FORM_DATA_FIELD_CONFLICT
400
같은 값과 중첩 경로를 동시에 지정하지 마세요.
MULTIPART_LIMIT_OR_PARSE_ERROR
400·413
boundary·파일 크기·필드 개수를 확인하세요. 서비스별 제한이 우선 적용됩니다.

요금·이용 조건

기본 요금기본 단가 5P · 건당

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

연동 팁

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

{
    "data": {
        "carrier": { "code": "cj", "name": "CJ대한통운" },
        "trackingNumber": "123456789012",
        "status": "DELIVERED",
        "carrierStatus": "배달완료",
        "queriedAt": "2026-08-02T15:00:00.000Z",
        "lastEvent": { "time": "2026-08-02T14:00:00+09:00", "location": "서울", "status": "DELIVERED", "carrierStatus": "배달완료", "description": "배달완료" },
        "events": [
            { "time": "2026-08-01T09:00:00+09:00", "location": "서울", "status": "PICKED_UP", "carrierStatus": "집화완료", "description": "집화완료" },
            { "time": "2026-08-02T14:00:00+09:00", "location": "서울", "status": "DELIVERED", "carrierStatus": "배달완료", "description": "배달완료" }
        ],
        "success": 1
    },
    "api": {
        "success": true,
        "cost": 5,
        "ms": 1820,
        "pl_id": 1595644
    }
}
            

개발가이드 검색

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

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