whereparcel

궁금한 게 있으세요? 편하게 물어보세요. WhereParcel을 만든 개발자가 직접 읽고 답장드립니다.

택배조회API 레퍼런스 - 실시간 배송추적

언제든 취소 가능한 실시간 배송추적 API. CJ대한통운, 한진택배, 롯데택배 등 전 세계 택배사 조회. 단건/다건 조회, 코드 예제 제공.

플레이그라운드에서 테스트 빠른 시작 가이드 → 시작하기 →

EndpointPOST/v2/track
택배 조회 (과금 대상)

개요

최대 5건까지 한 번에 조회. CJ대한통운, 한진택배 등 39개 이상의 택배사 지원.

일부 택배사는 요청당 1건 제한:

아래 택배사는 조회 시간이 크게 길어, 동기 요청 하나에 이 목록 전체를 통틀어 최대 1건만 담을 수 있습니다. 두 개를 섞어 보내는 것도 거부됩니다. 다른 택배사와 함께 보내는 것은 가능합니다 — 이 목록 1건 + 그 외 택배사 4건 = 총 5건.

us.usps, us.fedex, us.ups, intl.dhl

이 목록은 변경될 수 있습니다. 초과하면 INVALID_REQUEST로 거부되며, 오류 메시지에 해당 택배사 코드가 표시됩니다. 이 택배사들을 여러 건 추적하려면 /v2/webhooks/register(최대 100건, 비동기)를 사용하세요.

시각이 없는 이벤트: 일부 택배사는 특정 이벤트에 날짜만 주고 스캔 시각을 주지 않습니다(예: USPS 의 "In Transit to Next Facility", "Pre-Shipment"). 이때 timestamp 는 ISO 8601 을 유지하려고 그날 정오로 채워지고 해당 이벤트에 timeUnknown: true 가 붙습니다. 이 필드가 없으면 시각까지 택배사가 준 실제 값입니다.

이 엔드포인트의 용도: /v2/track은 단발성 조회에 사용하세요. 예: 쇼핑몰에서 고객이 주문 상태를 확인할 때.

지속적인 모니터링은 웹훅을 사용하세요. DB 업데이트, 알림 발송 등 배송 상태를 지속적으로 추적해야 한다면 /v2/webhooks/register에서 recurring: true로 구독을 등록하세요. 폴링 대신 상태가 변경될 때만 푸시 알림을 받으므로 훨씬 효율적입니다.

요청 한도: 플랜별로 분당/월간 요청 한도가 적용됩니다. 한도 초과 시 HTTP 429를 반환합니다. 응답 헤더 X-RateLimit-Limit-Minute·X-RateLimit-Remaining-Minute·X-RateLimit-Reset-Minute (및 -Day·-Month 변형)에서 현재 사용량을 확인하세요.

플랜 분당 요청 월간 요청
Starter 30 10,000
Pro 60 30,000
Business 200 300,000

요청 예제

// npm install whereparcel
import { WhereParcel } from 'whereparcel';

const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');

const { data, summary } = await wp.track([
  {
    "carrier": "kr.cj",
    "trackingNumber": "123456789012"
  },
  {
    "carrier": "de.gls",
    "trackingNumber": "48117308687"
  }
]);

console.log(summary);
for (const result of data) {
  if (result.status === 'success') {
    console.log(result.carrier, result.data.deliveryStatus);
  }
}
curl -X POST https://api.whereparcel.com/v2/track \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
  -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 YOUR_API_KEY:YOUR_SECRET_KEY",
    "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 YOUR_API_KEY:YOUR_SECRET_KEY',
  'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$data = [
  'trackingItems' => [
    [
      'carrier' => "kr.cj",
      'trackingNumber' => "123456789012"
    ],
    [
      '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

url = 'https://api.whereparcel.com/v2/track'

headers = {
    'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
}

data = {
    'trackingItems': [
        {
            'carrier': "kr.cj",
            'trackingNumber': "123456789012"
        },
        {
            'carrier': "de.gls",
            'trackingNumber': "48117308687",
            'postalCode': "04179"
        }
    ]
}

response = requests.post(url, headers=headers, json=data)

result = response.json()
print(result)
package main

import (
	"bytes"
	"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 YOUR_API_KEY:YOUR_SECRET_KEY")
	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 키로 교체하세요.

요청 본문

trackingItems array · required
trackingItems[].carrier string · required 택배사 코드 (예: 'kr.cj', 'us.fedex', 'de.gls')
trackingItems[].trackingNumber string · required 송장번호
trackingItems[].clientId string 클라이언트 추적 ID (응답에 그대로 반환)
trackingItems[].postalCode string 우편번호 (일부 택배사 필수/선택, 예: GLS Germany)
trackingItems[].phoneNumber string 전화번호 (일부 택배사 필수/선택)

응답

성공 응답 (200)

200OK — 성공적인 조회 응답
{
  "success": true,
  "data": [
    {
      "carrier": "kr.cj",
      "trackingNumber": "123456789012",
      "clientId": "order-123",
      "status": "success",
      "billable": true,
      "cached": false,
      "data": {
        "deliveryStatus": "delivered",
        "events": [
          {
            "timestamp": "2026-02-04T18:00:00+09:00",
            "status": "in_transit",
            "location": "서울 송파구 센터",
            "description": "집하"
          },
          {
            "timestamp": "2026-02-05T09:15:00+09:00",
            "status": "out_for_delivery",
            "location": "서울 강남구 센터",
            "description": "배달 출발"
          },
          {
            "timestamp": "2026-02-05T14:30:00+09:00",
            "status": "delivered",
            "location": "서울 강남구",
            "description": "고객님께 배달이 완료되었습니다"
          }
        ],
        "from": {
          "name": "홍**"
        },
        "to": {
          "name": "김**"
        },
        "lastUpdated": "2026-02-05T14:30:00+09:00"
      }
    },
    {
      "carrier": "kr.hanjin",
      "trackingNumber": "987654321098",
      "status": "success",
      "billable": true,
      "cached": false,
      "data": {
        "deliveryStatus": "in_transit",
        "events": [
          {
            "timestamp": "2026-02-05T12:00:00+09:00",
            "status": "in_transit",
            "location": "경기 성남시",
            "description": "간선상차"
          }
        ],
        "lastUpdated": "2026-02-05T12:00:00+09:00"
      }
    }
  ],
  "summary": {
    "total": 2,
    "success": 2,
    "failed": 0,
    "usageIncremented": 2
  },
  "requestLimit": {
    "second": "1/10"
  },
  "trackingQuota": {
    "minute": "2/30",
    "day": "2/10000",
    "month": "152/10000"
  }
}

오류 응답 (400)

400Bad Request — 잘못된 요청 — 검증 실패(REQUEST_VALIDATION_FAILED, invalidItems 포함), 1건 제한 택배사 초과(INVALID_REQUEST), 데모 키 항목 수 초과(DEMO_KEY_ITEM_LIMIT_EXCEEDED)
{
  "success": false,
  "error": {
    "code": "REQUEST_VALIDATION_FAILED",
    "message": "1 invalid item(s) found"
  }
}

오류 응답 (401)

401Unauthorized — 인증 실패 - API 키가 없거나 잘못됨
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}

오류 응답 (403)

403Forbidden — 거부 — 공개 데모 키는 WhereParcel 플레이그라운드에서만 동작합니다(DEMO_KEY_BROWSER_ONLY). 또는 트라이얼 한도 도달(TRIAL_LIMIT_REACHED)
{
  "success": false,
  "error": {
    "code": "DEMO_KEY_BROWSER_ONLY",
    "message": "This test key only works from the WhereParcel Playground (https://whereparcel.com/playground)."
  }
}

오류 응답 (429)

429Too Many Requests — 요청 한도 · 사용량 초과(RATE_LIMIT_EXCEEDED, MINUTE_QUOTA_EXCEEDED, MONTHLY_QUOTA_EXCEEDED, DEMO_KEY_IP_LIMIT_EXCEEDED)
{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please try again later."
  }
}
EndpointPOST/v2/detect
송장번호로 택배사 감지 (무료)

개요

입력한 송장번호의 형식에 맞는 택배사를 가장 구체적인 것부터(specificityScore) 돌려줍니다. 형식 대조만 하며 택배사 조회도, 사용량 차감도 없습니다.

specificityScore 가 가장 높은 후보의 코드로 /v2/track 을 호출하세요. confirmed 는 정확히 한 택배사만 맞을 때만 있습니다.

요청 예제

// npm install whereparcel
import { WhereParcel } from 'whereparcel';

const wp = new WhereParcel('YOUR_API_KEY', 'YOUR_SECRET_KEY');

const detected = await wp.detect('1Z999AA10123456784');

if (detected.confirmed) {
  console.log('carrier:', detected.confirmed);
} else if (!detected.noMatch) {
  console.log('candidates:', detected.candidates.map((c) => c.code));
}
curl -X POST https://api.whereparcel.com/v2/detect \
  -H "Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "trackingNumber": "1Z999AA10123456784"
  }'
const response = await fetch('https://api.whereparcel.com/v2/detect', {
  method: 'POST',
  headers: {
    "Authorization": "Bearer YOUR_API_KEY:YOUR_SECRET_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
      "trackingNumber": "1Z999AA10123456784"
    })
});

const data = await response.json();
console.log(data);
<?php

$ch = curl_init();

curl_setopt($ch, CURLOPT_URL, 'https://api.whereparcel.com/v2/detect');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'POST');

$headers = [
  'Authorization: Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
  'Content-Type: application/json'
];
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);

$data = [
  'trackingNumber' => "1Z999AA10123456784"
];
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

url = 'https://api.whereparcel.com/v2/detect'

headers = {
    'Authorization': 'Bearer YOUR_API_KEY:YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
}

data = {
    'trackingNumber': "1Z999AA10123456784"
}

response = requests.post(url, headers=headers, json=data)

result = response.json()
print(result)
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://api.whereparcel.com/v2/detect"

	payload := []byte(`{"trackingNumber":"1Z999AA10123456784"}`)
	req, _ := http.NewRequest("POST", url, bytes.NewBuffer(payload))

	req.Header.Add("Authorization", "Bearer YOUR_API_KEY:YOUR_SECRET_KEY")
	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 키로 교체하세요.

요청 본문

trackingNumber string · required 확인할 송장번호(최대 100자, 공백 · 하이픈 · 점은 무시)

응답

성공 응답 (200)

200OK — 택배사 후보
{
  "success": true,
  "data": {
    "input": "1Z999AA10123456784",
    "normalized": "1Z999AA10123456784",
    "candidates": [
      {
        "code": "us.ups",
        "name": "UPS (United Parcel Service)",
        "country": "US",
        "pattern": {
          "regex": "^(1Z[A-Z0-9]{16}|T[0-9]{10}|[0-9]{9,34})$",
          "description": "1Z + 16 alphanumeric characters (incl. check digit), T + 10 digits, or 9-34 digits (Mail Innovations/SurePost)",
          "examples": [
            "1ZW4420K0310663099",
            "9216490395160105988026"
          ]
        },
        "specificityScore": 67,
        "formatName": "UPS",
        "serviceTypes": [
          "UPS United States Next Day Air (Red)"
        ]
      },
      {
        "code": "intl.dhl",
        "name": "DHL Express",
        "country": "INTL",
        "pattern": {
          "regex": "^([0-9]{10,39}|[A-Z]{2}[0-9]{9}[A-Z]{2}|JD[0-9]{18,22})$",
          "description": "10-39 digits, international postal format (2 letters + 9 digits + 2 letters), or JD + digits",
          "examples": [
            "1234567890",
            "AB123456789CD"
          ]
        },
        "specificityScore": 20,
        "formatName": "DHL Express",
        "serviceTypes": []
      },
      {
        "code": "ca.loomis",
        "name": "Loomis Express",
        "country": "CA",
        "pattern": {
          "regex": "^[A-Z0-9]{10,30}$",
          "description": "Alphanumeric 10-30 characters (e.g., LSHP46411066, LQJ0Z3N0AALSHP46411066)",
          "examples": [
            "LSHP46411066",
            "LQJ0Z3N0AALSHP46411066"
          ]
        },
        "specificityScore": 2
      },
      {
        "code": "ca.ics",
        "name": "ICS Courier",
        "country": "CA",
        "pattern": {
          "regex": "^[A-Z0-9]{15,25}$",
          "description": "Alphanumeric 15-25 characters (e.g., ND6C2BV3HBB0BEJ9Z1E2)",
          "examples": [
            "ND6C2BV3HBB0BEJ9Z1E2"
          ]
        },
        "specificityScore": 2
      },
      {
        "code": "intl.cainiao",
        "name": "Cainiao",
        "country": "INTL",
        "pattern": {
          "regex": "^(LP[A-Z0-9]{14,20}|[A-Z]{2}[0-9]{9}[A-Z]{2}|CAINIAO[A-Z0-9]+|[A-Z0-9]{10,30})$",
          "description": "LP + 14-20 characters, international postal format, CAINIAO prefix, or 10-30 alphanumeric characters",
          "examples": [
            "LP00123456789012345",
            "AB123456789CD"
          ]
        },
        "specificityScore": 2
      }
    ],
    "format": "1Z + 16 alphanumeric characters (incl. check digit), T + 10 digits, or 9-34 digits (Mail Innovations/SurePost)",
    "noMatch": false
  }
}

오류 응답 (400)

400Bad Request — trackingNumber 가 없거나 비었거나 100자를 넘음(INVALID_REQUEST)
{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Field \"trackingNumber\" (string) is required in request body."
  }
}

오류 응답 (401)

401Unauthorized — 인증 실패 - API 키가 없거나 잘못됨
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or missing API key"
  }
}