한진택배 조회 API 연동 가이드

한진택배 소개

한진택배는 B2B 대형 화물 처리 능력과 전국 물류 네트워크를 바탕으로 기업 고객에게 널리 사용됩니다. WMS(창고관리시스템), 3PL(제3자 물류) 연동 시 한진택배 API 조회 기능이 자주 필요합니다.

송장번호 형식

한진택배 송장번호는 10~12자리 숫자로 구성되며, 대부분 12자리입니다.

구분	형식	예시
일반 택배	12자리 숫자	123456789012
구형 송장	10~11자리 숫자	1234567890

API 연동 예시

요청 (curl)

courierCode를 hanjin으로 설정하고, trackingNumber에 송장번호를 입력합니다. 한 번에 여러 송장번호를 items 배열에 담아 조회할 수 있습니다.

curl -X POST https://api.deliveryapi.co.kr/v1/tracking/trace \
  -H "Authorization: Bearer {API_KEY}:{SECRET_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      {
        "courierCode": "hanjin",
        "trackingNumber": "123456789012"
      }
    ]
  }'

응답 예시

{
  "isSuccess": true,
  "data": {
    "results": [
      {
        "success": true,
        "data": {
          "courierCode": "hanjin",
          "courierName": "한진택배",
          "trackingNumber": "123456789012",
          "deliveryStatus": "DELIVERED",
          "deliveryStatusText": "배송완료",
          "isDelivered": true,
          "progresses": [
            {
              "dateTime": "2026-03-11T06:10:00+09:00",
              "status": "간선상차",
              "statusCode": "IN_TRANSIT",
              "location": "한진 대전HUB",
              "description": "간선 상차"
            },
            {
              "dateTime": "2026-03-11T10:45:00+09:00",
              "status": "배송출발",
              "statusCode": "OUT_FOR_DELIVERY",
              "location": "서울 강남구",
              "description": "배송 출발"
            },
            {
              "dateTime": "2026-03-11T14:30:00+09:00",
              "status": "배달완료",
              "statusCode": "DELIVERED",
              "location": "서울 강남구",
              "description": "배송 완료"
            }
          ],
          "dateLastProgress": "2026-03-11T14:30:00+09:00",
          "queriedAt": "2026-03-11T15:00:00+09:00"
        }
      }
    ],
    "summary": { "total": 1, "successful": 1, "failed": 0, "billable": 1 }
  }
}

상태 코드 매핑

택배조회API는 한진택배의 내부 상태를 표준 상태 코드로 변환하여 제공합니다.

표준 상태 코드	한진택배 원본 상태	설명
PENDING	접수	택배 접수가 등록되었으나 아직 집하되지 않은 상태
PICKED_UP	집하 완료	택배 기사가 물건을 수거한 상태
IN_TRANSIT	간선 상차 / HUB 처리	허브(HUB) 또는 간선 차량으로 이동 중인 상태
OUT_FOR_DELIVERY	배송 출발	배송 기사가 수령인에게 배송을 출발한 상태
DELIVERED	배송 완료	수령인에게 배송이 완료된 상태

FAQ