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 키를 노출하면 악용될 수 있습니다.

엔드포인트#

배송 조회#

GET/v1/track

파라미터

carrierstring필수
택배사 코드 (예: cjlogistics, hanjin, fedex)
trackingNumberstring필수
운송장 번호

요청 예시

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

응답 예시

200 OK
{
  "code": "200",
  "data": {
    "carrier": {
      "id": "{택배사코드}",
      "name": "CJ대한통운",
      "country": "KR"
    },
    "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": "배달을 위해 출발하였습니다."
      }
    ],
    "templateUrl": "https://www.thetrack.kr/tracking/{택배사코드}/{운송장번호}?sig=식별코드"
  }
}

응답 필드

carrierobject
택배사 정보 (id, name, country)
trackingNumberstring
조회된 운송장 번호
senderstring | null
발송인 (택배사에 따라 미제공)
recipientstring | null
수령인 (택배사에 따라 미제공)
lastEventobject | null
최신 배송 이벤트 (status, statusText, time, location, description)
eventsarray
전체 배송 이벤트 목록 — 최신순 (status, statusText, time, location, description)
templateUrlstring
배송조회 웹 페이지 URL (임베드/공유용)

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

배송조회 템플릿#

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>

택배사 목록 조회#

GET/v1/carriers

요청 예시

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

응답 예시

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

상태 코드#

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

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

에러 코드#

에러 발생 시 적절한 HTTP 상태 코드와 JSON 에러 응답이 반환됩니다.code 필드로 HTTP 상태를, message 필드로 상세 내용을 확인하세요.

에러 응답 형식
{
  "code": "404",
  "message": "운송장 정보를 찾을 수 없습니다. 운송장 번호를 다시 확인해주세요."
}
HTTP설명message
400파라미터 오류잘못된 요청입니다. carrier 코드와 운송장 번호 형식을 확인해주세요.
401API 키 없음X-API-Key 헤더가 없습니다.
401API 키 인증 실패유효하지 않은 API 키입니다.
403계정 비활성화비활성화된 계정입니다.
403활성 구독 없음활성 구독 플랜이 없거나 이용 기간이 종료되었습니다.
404지원하지 않는 택배사지원하지 않는 택배사입니다.
404운송장 조회 결과 없음운송장 정보를 찾을 수 없습니다. 운송장 번호를 다시 확인해주세요.
429일일 조회 한도 초과동일 운송장 일일 조회 횟수를 초과했습니다.
429월간 운송장 한도 초과월간 고유 운송장 한도를 초과했습니다.
500서버 오류외부 API 호출 중 오류가 발생했습니다. 잠시 후 재시도해주세요.

사용량 제한#

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

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

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

플랜월간 운송장 한도동일번호 일 조회

사용량 확인 헤더

모든 API 응답 헤더에 남은 사용량 정보가 포함됩니다.

응답 헤더
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2026-06-15T00:00:00Z
X-RateLimit-Limitinteger
플랜의 구독 기간 운송장 한도 (무제한 플랜은 -1)
X-RateLimit-Remaininginteger
이번 구독 기간 남은 운송장 건수 (무제한 플랜은 -1)
X-RateLimit-ResetISO 8601
한도가 초기화되는 시각 — 구독 종료일 다음날 00:00

요금제에 대한 자세한 정보는 요금제 페이지를 참조하세요.

지원 택배사#

현재 지원하는 택배사 목록입니다. 아래 목록은 API에서 실시간으로 가져옵니다.

지금 바로 연동하세요

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

무료로 시작하기요금제 보기