택배조회API 레퍼런스 - 실시간 배송추적 | WhereParcel
무료 플랜 제공 실시간 배송추적 API. CJ대한통운, 한진택배, 롯데택배 등 전 세계 택배사 조회. 단건/다건 조회, 코드 예제 제공.
POST
/v2/track 택배 조회 (과금 대상)
개요
최대 5건까지 한 번에 조회. 1건당 평균 응답 시간 5초. CJ대한통운, 한진택배 등 500개 택배사 지원.
이 엔드포인트의 용도:
/v2/track은 단발성 조회에 사용하세요. 예: 쇼핑몰에서 고객이 주문 상태를 확인할 때.
지속적인 모니터링은 웹훅을 사용하세요.
DB 업데이트, 알림 발송 등 배송 상태를 지속적으로 추적해야 한다면 /v2/webhooks/register에서 recurring: true로 구독을 등록하세요. 폴링 대신 상태가 변경될 때만 푸시 알림을 받으므로 훨씬 효율적입니다.
요청 한도:
플랜별로 분당/월간 요청 한도가 적용됩니다. 한도 초과 시 HTTP 429를 반환합니다. 응답 헤더 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset에서 현재 사용량을 확인하세요.
| 플랜 | 분당 요청 | 월간 요청 |
|---|---|---|
| Free | 1 | 5 |
| Starter | 30 | 10,000 |
| Pro | 60 | 30,000 |
| Business | 200 | 300,000 |
요청 예제
// npm install whereparcel
import { WhereParcel } from 'whereparcel';
const wp = new WhereParcel('wp_test_public_demo_key_do_not_use_in_production', 'sk_test_public_demo_secret_do_not_use_in_production');
const response = await wp.trackBulk([
{
"carrier": "kr.cj",
"trackingNumber": "123456789012"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687"
}
]);
console.log(response.summary);
for (const result of response.results) {
if (result.status === 'success') {
console.log(result.data.deliveryStatus);
}
}curl -X POST https://api.whereparcel.com/v2/track \
-H "Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production" \
-H "Content-Type: application/json" \
-d '{
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "123456789012"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687",
"postalCode": "04179"
}
]
}'const response = await fetch('https://api.whereparcel.com/v2/track', {
method: 'POST',
headers: {
"Authorization": "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production",
"Content-Type": "application/json"
},
body: JSON.stringify({
"trackingItems": [
{
"carrier": "kr.cj",
"trackingNumber": "123456789012"
},
{
"carrier": "de.gls",
"trackingNumber": "48117308687",
"postalCode": "04179"
}
]
})
});
const data = await response.json();
console.log(data);<?php
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/track');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');
$headers = [
'Authorization: Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
$data = [
'trackingItems' => [
'0' => [
'carrier' => "kr.cj",
'trackingNumber' => "123456789012"
],
'1' => [
'carrier' => "de.gls",
'trackingNumber' => "48117308687",
'postalCode' => "04179"
]
]
];
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
$response = curl_exec($ch);
curl_close($ch);
$result = json_decode($response, true);
print_r($result);import requests
import json
url = 'https://api.whereparcel.com/v2/track'
headers = {
'Authorization': 'Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production',
'Content-Type': 'application/json'
}
data = {
'trackingItems': {
'0': {
'carrier': "kr.cj",
'trackingNumber': "123456789012"
},
'1': {
'carrier': "de.gls",
'trackingNumber': "48117308687",
'postalCode': "04179"
}
}
}
response = requests.post(url, headers=headers, json=data)
result = response.json()
print(result)package main
import (
"bytes"
"encoding/json"
"fmt"
"io"
"net/http"
)
func main() {
url := "https://api.whereparcel.com/v2/track"
payload := []byte(`{"trackingItems":[{"carrier":"kr.cj","trackingNumber":"123456789012"},{"carrier":"de.gls","trackingNumber":"48117308687","postalCode":"04179"}]}`)
req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))
req.Header.Add("Authorization", "Bearer wp_test_public_demo_key_do_not_use_in_production:sk_test_public_demo_secret_do_not_use_in_production")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
} 💡 참고: 테스트 API 키를 대시보드에서 발급받은 실제 API 키로 교체하세요.
요청 본문
| Name | Type | Required | Description |
|---|---|---|---|
trackingItems | array | Required | |
trackingItems[].carrier | string | Required | 택배사 코드 (예: 'kr.cj', 'us.fedex', 'de.gls') |
trackingItems[].trackingNumber | string | Required | 송장번호 |
trackingItems[].clientId | string | Optional | 클라이언트 추적 ID (응답에 그대로 반환) |
trackingItems[].postalCode | string | Optional | 우편번호 (일부 택배사 필수/선택, 예: GLS Germany) |
trackingItems[].phoneNumber | string | Optional | 전화번호 (일부 택배사 필수/선택) |
응답
성공 응답 (200)
200 OK
성공적인 조회 응답
Response Body
{
"success": true,
"results": [
{
"carrier": "kr.cj",
"trackingNumber": "123456789012",
"clientId": "order-123",
"success": true,
"data": {
"carrier": "kr.cj",
"carrierName": "CJ대한통운",
"trackingNumber": "123456789012",
"status": "delivered",
"statusText": "배달완료",
"events": [
{
"timestamp": "2026-02-05T14:30:00+09:00",
"status": "delivered",
"statusText": "배달완료",
"location": "서울 강남구",
"description": "고객님께 배달이 완료되었습니다"
},
{
"timestamp": "2026-02-05T09:15:00+09:00",
"status": "out_for_delivery",
"statusText": "배달 출발",
"location": "서울 강남구 센터"
},
{
"timestamp": "2026-02-04T18:00:00+09:00",
"status": "in_transit",
"statusText": "집하",
"location": "서울 송파구 센터"
}
]
}
},
{
"carrier": "kr.hanjin",
"trackingNumber": "987654321098",
"success": true,
"data": {
"carrier": "kr.hanjin",
"carrierName": "한진택배",
"trackingNumber": "987654321098",
"status": "in_transit",
"statusText": "배송 중",
"events": [
{
"timestamp": "2026-02-05T12:00:00+09:00",
"status": "in_transit",
"statusText": "간선상차",
"location": "경기 성남시"
}
]
}
}
]
} 오류 응답 (401)
401 Unauthorized
인증 실패 - API 키가 없거나 잘못됨
Response Body
{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Invalid or missing API key"
}
} 오류 응답 (429)
429 Too Many Requests
요청 한도 초과
Response Body
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Please try again later."
}
}