TheTrack

Developer Docs

TheTrack API

RESTful API 하나로 국내외 주요 택배사의 배송 상태를 실시간 추적하세요. 표준화된 JSON 응답과 간단한 인증으로 5분 만에 연동할 수 있습니다.

Base URLhttps://api.thetrack.kr
API 키 발급받기

개요#

TheTrack API는 RESTful HTTP API입니다. 모든 요청과 응답은 JSON 형식이며, UTF-8 인코딩을 사용합니다.

프로토콜

HTTPS

응답 형식

JSON

인증

API KEY (헤더)

빠른 시작 (cURL)
curl "https://api.thetrack.kr/v1/track?carrier={택배사코드}&trackingNumber={운송장번호}" \
  -H "X-API-Key: {발급받은 API 키}"

인증#

모든 API 요청에는 X-API-Key 헤더가 필요합니다. API 키는 대시보드에서 발급받을 수 있습니다.

인증 헤더 예시
GET /v1/track?carrier={택배사코드}&trackingNumber={운송장번호} HTTP/1.1
Host: api.thetrack.kr
X-API-Key: {발급받은 API 키}

보안 주의사항

API 키는 서버 측 코드에서만 사용하세요. 클라이언트(브라우저, 앱)에 API 키를 노출하면 악용될 수 있습니다.

사용량 확인 헤더#

모든 API 응답 헤더에 남은 사용량 정보가 포함됩니다. 엔드포인트와 무관하게 공통으로 내려갑니다.

응답 헤더
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2026-06-15T00:00:00Z
헤더타입설명
X-RateLimit-LimitInteger이용권의 이용 기간 운송장 한도
X-RateLimit-RemainingInteger이번 이용 기간 남은 운송장 건수
X-RateLimit-ResetISO 8601한도가 초기화되는 시각 - 이용권 종료일 다음날 00:00

엔드포인트#

배송 조회#

GET/v1/track

파라미터

요청 예시

cURL
curl "https://api.thetrack.kr/v1/track?carrier={택배사코드}&trackingNumber={운송장번호}" \
  -H "X-API-Key: {발급받은 API 키}"

응답 예시

200 OK
{
  "code": "200",
  "data": {
    "carrierId": "{택배사코드}",
    "trackingNumber": "{운송장번호}",
    "sender": "김**",
    "recipient": "이**",
    "lastEvent": {
      "status": "DELIVERED",
      "statusText": "배달완료",
      "time": "2026-03-25 14:30:00",
      "location": "서울 강남구",
      "description": "배달 완료되었습니다."
    },
    "events": [
      {
        "status": "DELIVERED",
        "statusText": "배달완료",
        "time": "2026-03-25 14:30:00",
        "location": "서울 강남구",
        "description": "배달 완료되었습니다."
      },
      {
        "status": "OUT_FOR_DELIVERY",
        "statusText": "배달출발",
        "time": "2026-03-25 08:00:00",
        "location": "서울 강남 배달센터",
        "description": "배달을 위해 출발하였습니다."
      }
    ],
    "carrier": {
      "id": "{택배사코드}",
      "name": "CJ대한통운",
      "country": "KR"
    },
    "templateUrl": "https://www.thetrack.kr/tracking/{택배사코드}/{운송장번호}?sig={서명값}"
  }
}

응답 필드

배송 이력의 time 필드 포맷: YYYY-MM-DD HH:mm:ss (KST, 한국 표준시 UTC+9)

응답 예시 - 조회 결과 없음

200 OK - 조회 결과 없음
{
  "code": "200",
  "data": {
    "code": "NO_TRACKING",
    "message": "운송장 정보를 찾을 수 없습니다. 운송장 번호를 다시 확인해주세요."
  }
}

운송장 번호가 잘못된 경우뿐 아니라, 택배사에 접수만 되고 아직 배송 이력(스캔 이벤트)이 없는 경우에도 동일하게 이 응답이 내려갑니다 - 잠시 후 다시 조회해주세요.

응답 필드

codestring
결과코드 (200: 성공)
dataObject
조회 결과
└─codestring
조회 결과 코드
└─messagestring
code 에 대한 안내 메시지

통관정보조회#

GET/v1/customs

배송 조회와 동일한 이용건수(고유 운송장)를 사용하며, 동일 운송장을 이미 배송 조회로 조회한 이력이 있으면 추가 차감되지 않습니다.

파라미터

요청 예시

cURL
curl "https://api.thetrack.kr/v1/customs?trackingNumber={운송장번호}&year={입항연도}" \
  -H "X-API-Key: {발급받은 API 키}"

응답 예시

200 OK
{
  "code": "200",
  "data": {
    "carrierId": "customs",
    "trackingNumber": "{운송장번호}",
    "lastEvent": {
      "status": "IN_CUSTOMS",
      "statusText": "통관중",
      "time": "2026-03-25 14:30:00",
      "location": "인천공항 특송장",
      "description": "수입신고 수리되었습니다."
    },
    "events": [
      {
        "status": "IN_CUSTOMS",
        "statusText": "통관중",
        "time": "2026-03-25 14:30:00",
        "location": "인천공항 특송장",
        "description": "수입신고 수리되었습니다."
      }
    ],
    "carrier": {
      "id": "customs",
      "name": "통관정보조회",
      "country": "KR"
    },
    "templateUrl": "https://www.thetrack.kr/tracking/customs/{운송장번호}?sig={서명값}"
  }
}

templateUrl은 응답에 포함되지만, 통관정보조회 공유 페이지는 아직 지원하지 않습니다(연도 파라미터를 전달할 수 없어 항상 "조회된 결과 없음"으로 표시됩니다).

응답 필드

응답 예시 - 조회 결과 없음

200 OK - 조회 결과 없음
{
  "code": "200",
  "data": {
    "code": "NO_TRACKING",
    "message": "운송장 정보를 찾을 수 없습니다. 운송장 번호를 다시 확인해주세요."
  }
}

year 를 잘못 선택한 경우(실제 입항연도와 다름)에도 대부분 이 응답이 내려갑니다 - year 를 바꿔 다시 시도해보세요.

응답 필드

codestring
결과코드 (200: 성공)
dataObject
조회 결과
└─codestring
조회 결과 코드
└─messagestring
code 에 대한 안내 메시지

택배사 목록 조회#

GET/v1/carriers

요청 예시

cURL
curl "https://api.thetrack.kr/v1/carriers" \
  -H "X-API-Key: {발급받은 API 키}"

응답 예시

200 OK
{
  "code": "200",
  "data": {
    "carriers": [
      { "id": "cjlogistics", "name": "CJ대한통운", "country": "KR" },
      { "id": "hanjin", "name": "한진택배", "country": "KR" }
    ],
    "count": 35
  }
}

응답 필드

배송조회 템플릿#

API 응답의 templateUrl 필드를 활용하면 별도의 UI 개발 없이 배송 추적 페이지를 고객에게 제공할 수 있습니다. 3가지 테마 중 원하는 스타일을 선택하세요.

테마 미리보기

Modern기본
✓
접수
✓
집하
✓
이동중
✓
배송출발
✓
배송완료

CJ대한통운

1234567890

배송완료
배송완료04.01 14:30

서울 강남구

배송출발04.01 08:15

강남 배송센터

도착03.31 22:10

강남 집중국

발송03.31 18:30

대전 허브

Powered by TheTrack
Minimal심플

CJ대한통운

1234567890

● 배송완료

04.01 14:30

배송완료

서울 강남구

04.01 08:15

배송출발

강남 배송센터

03.31 22:10

도착

강남 집중국

03.31 18:30

발송

대전 허브

03.31 15:00

집하

부산 해운대

Powered by TheTrack
Dark다크
✓
접수
✓
집하
✓
이동중
✓
배송출발
✓
배송완료

CJ대한통운

1234567890

배송완료
배송완료04.01 14:30

서울 강남구

배송출발04.01 08:15

강남 배송센터

도착03.31 22:10

강남 집중국

발송03.31 18:30

대전 허브

Powered by TheTrack

URL 형식

templateUrl
# 기본 (모던)
https://www.thetrack.kr/tracking/{carrier}/{trackingNumber}?sig={서명값}

# 테마 지정
https://www.thetrack.kr/tracking/{carrier}/{trackingNumber}?sig={서명값}&theme=minimal
https://www.thetrack.kr/tracking/{carrier}/{trackingNumber}?sig={서명값}&theme=dark

# sig는 API 응답의 templateUrl에 자동으로 포함됩니다. 직접 생성하지 않아도 됩니다.

활용 예시

카카오톡 알림톡, 이메일, SMS 등에서 고객에게 배송 추적 링크를 제공할 때templateUrl 값을 그대로 사용하세요.

알림톡 메시지 예시
[배송 알림] 고객님의 주문이 발송되었습니다.
운송장 번호: {운송장번호}
배송 조회: {응답의 templateUrl 값}

iframe 임베드

자사 웹사이트에 배송 조회 페이지를 iframe으로 임베드할 수도 있습니다.

HTML
<iframe
  src="{응답의 templateUrl 값}"
  width="100%"
  height="600"
  frameborder="0"
></iframe>

상태 코드#

배송 이력의 status 필드는 다음 값 중 하나입니다. 모든 택배사의 상태가 동일한 코드로 표준화됩니다.

상태 코드설명
INFORMATION_RECEIVED접수
AT_PICKUP집하완료
IN_TRANSIT배송중 (간선이동)
IN_CUSTOMS통관중
OUT_FOR_DELIVERY배송출발
DELIVERED배송완료
AVAILABLE_FOR_PICKUP수령가능 (보관중)
ATTEMPT_FAIL배송실패 (재시도 예정)
EXCEPTION배송이상 / 지연
RETURNED반송
UNKNOWN확인중

에러 코드#

인증 실패·요청 한도 초과 등 호출 자체가 실패하면 실제 HTTP 상태 코드와 함께 아래 형식의 JSON 이 반환됩니다. code 필드로 HTTP 상태를, message 필드로 상세 내용을 확인하세요. 운송장 조회 자체는 정상 처리됐지만 결과가 없는 경우(에러 아님)는 배송 조회 섹션의 data.code 코드 표를 참고하세요.

에러 응답 형식 (예: 잘못된 API 키)
{
  "code": "401",
  "message": "유효하지 않은 API 키입니다."
}
HTTP설명message
200성공정상적으로 처리되었습니다.
400파라미터 오류잘못된 요청입니다. carrier 코드와 운송장 번호 형식을 확인해주세요.
401API 키 없음X-API-Key 헤더가 없습니다.
401API 키 인증 실패유효하지 않은 API 키입니다.
403계정 비활성화비활성화된 계정입니다.
429동일운송장 일일 조회 한도초과동일한 운송장을 하루 조회 한도 이상으로 조회했습니다. 잠시 후 다시 시도해주세요.
429이용권 한도 초과보유하신 이용권의 조회 한도를 모두 사용했습니다. 이용권을 갱신하거나 추가로 구매해주세요.
500서버 오류외부 API 호출 중 오류가 발생했습니다. 잠시 후 재시도해주세요.

사용량 제한#

운송장 기준 과금 (API 호출 수 아님)

동일 운송장을 여러 번 조회해도 30일 이내라면 1건으로 카운팅됩니다. 즉, 배송 완료 전까지 주기적으로 조회하더라도 추가 비용이 발생하지 않습니다.

추가로 동일 운송장의 일일 조회 횟수가 제한됩니다. 이는 불필요한 과도한 요청을 방지하기 위한 것입니다.

이용권 (제공건수)건당 단가금액 (부가세 별도)동일번호 일 조회

표시된 금액은 부가세(VAT) 별도이며, 부가세 포함 금액은 함께 표기했습니다. 100,000건 초과 대용량은 별도 문의해 주세요. 요금 문의하기 ↗

응답 헤더로 남은 사용량을 확인하는 방법은 사용량 확인 헤더 섹션을 참고하세요. 이용권에 대한 자세한 정보는 이용권 페이지를 참조하세요.

지원 택배사#

현재 지원하고 있는 택배사입니다.

지금 바로 연동하세요

무료 이용권으로 월 100건까지 배송 추적을 시작할 수 있습니다.

무료로 시작하기이용권 보기