배송현황조회 API 개발문서

패키지 여행

API는 주문 번호를 기준으로 패키지가 어느 단계에 있는지 자동으로 결정하고 현재 상태, 전체 타임라인 및 (대만 세관에 들어간 경우) GC329 5단계 통관 진행 상황을 반환합니다.

Base URL

인증 헤더(하나 선택)

Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx
// 或
X-API-Key: lk_live_xxxxxxxxxxxxxxxxxxxxxxxx

서버 측에서 호출하고 프런트엔드 JavaScript에 키를 넣지 마세요. 속도 제한은 키 단위이며 응답 헤더 X-RateLimit-Remaining은 남은 제한을 보고합니다. 제한을 초과하면 HTTP 429가 반환됩니다.

GETPOST /api/v1/shipment/track

추적 번호를 기준으로 단일 패키지의 배송 상태를 확인하세요. GET(쿼리 문자열) 및 POST(JSON/양식)가 모두 허용됩니다.

요청 매개변수

매개변수	유형	필수	설명
tracking_number	string	필수	패키지 추적 번호(4~64자, 영숫자 및 - _). 중국 특급 추적 번호/고객 추적 번호/배송 추적 번호가 모두 허용됩니다.

요청 예시(GET)

curl "https://0523.tw/api/v1/shipment/track?tracking_number=SF1234567890123" \
  -H "Authorization: Bearer lk_live_xxxxxxxxxxxxxxxxxxxxxxxx"

응답 200(예: 이미 창고/운송 중)

{
  "success": true,
  "cached": false,
  "tracking_number": "SF1234567890123",
  "data": {
    "tracking_number": "SF1234567890123",
    "customer_order_no": "LK260601001",
    "carrier_tracking_no": "SF1234567890123",
    "logistics": "順豐速運",
    "status_code": 2,
    "status": "已入倉",
    "description": "包裹已進入深圳集運倉,等待集運打包",
    "is_delivered": false,
    "is_final": false,
    "last_event_time": "2026-06-01 12:30:00",
    "updated_at": "2026-06-01 12:31:05",
    "timeline": [
      { "name": "已攬收", "completed": true,  "time": "2026-05-30 09:00:00" },
      { "name": "已入倉 (深圳集運倉)", "completed": true,  "time": "2026-06-01 12:30:00" },
      { "name": "集運打包/台灣運送", "completed": false, "time": null },
      { "name": "已簽收", "completed": false, "time": null }
    ],
    "customs_stages": null,
    "events": null
  }
}

응답 404(주문 번호를 찾을 수 없음)

{
  "success": false,
  "error": "not_found",
  "message": "查無此單號。請確認單號正確,或包裹尚未進入集運系統。",
  "tracking_number": "SF1234567890123"
}

필드	유형	설명
status	string	현재 상태(사람이 읽을 수 있음)(예: 예상/창고 중/운송 중/대만으로 배송 중/수령 서명됨) 이 문자열을 직접 표시하는 것이 좋습니다.
status_code	number	상태 코드(소스에 따라 다름, 다음 섹션 참조) UI를 구동하려면 status, is_delivered, is_final을 사용하는 것이 좋습니다.
is_delivered	bool	서명되었나요?
is_final	bool	최종인지 여부(서명됨/반품됨/취소됨/배송 불가) 폴링을 중지하려면 True입니다.
logistics	string	물류 제공업체(China Express 또는 대만 터미널 배송)
description	string	최신 이벤트 설명.
last_event_time	datetime	최신 물류 이벤트 시간.
timeline	array	스테이지 타임라인, 각 항목에는 이름 / 완료 / 시간 / 설명이 포함됩니다.
customs_stages	object|null	대만관세 GC329 통관 진행상황 (아직 통관이 완료되지 않은 경우 null) 다음 섹션을 참조하세요.
events	array|null	물류이력 원본(단말기 배송추적 시 제공)

배송대행의 주요 단계(타임라인)

무대	의미
예측됨(창고에 입력되지 않음)	고객이 주문 번호를 예상했지만 패키지가 아직 Shenzhen Consolidation Warehouse에 도착하지 않았습니다.
이미 창고에 보관됨(심천 컨테이너 창고)	심천 배송대행 창고가 패키지를 받았습니다.
묶음포장/대만배송	포장 및 배송, 해상/항공을 통해 대만으로 배송됩니다.
대만으로 운송/배송 중	대만 도착 후 통관 및 최종 배송을 진행합니다.
서명 대상	수신자가 배송에 서명했습니다(is_delivered = true).

통관 단계(customs_stages,GC329)

패키지가 대만 세관에 들어간 후 customs_stages에 5단계 진행 상황과 전체 비율이 표시됩니다.

{
  "hbl": "691MK539819",
  "trans_type_name": "海運",
  "current_stage_name": "海關放行",
  "progress_percent": 80,
  "is_completed": false,
  "stages": [
    { "code": "XX", "name": "船(機)抵達",   "done": true },
    { "code": "E1", "name": "連線收單建檔", "done": true },
    { "code": "D1", "name": "計稅",        "done": true },
    { "code": "RL", "name": "海關放行",     "done": true },
    { "code": "OW", "name": "出倉",        "done": false }
  ],
  "source": "關港貿單一窗口 GC329"
}

HTTP	error	설명
401	missing_api_key / invalid_api_key	API 키가 없거나 유효하지 않습니다.
403	insufficient_scope	키에 shipment:read 권한이 없습니다.
404	not_found	이 추적 번호를 찾을 수 없거나 패키지가 아직 배송대행 시스템에 들어가지 않았습니다.
422	validation_failed	추적 번호가 누락되었거나 형식과 일치하지 않습니다.
429	rate_limit_exceeded	분당 요청 제한을 초과하는 경우 Retry-After를 참조하세요.

• 폴링 빈도: 15~30분마다 동일한 주문 번호를 확인하는 것이 좋습니다. 결과는 이 서버에 5분 동안 캐시됩니다(cached: true는 적중을 의미함).
• 폴링 중지: is_final = true(서명됨/반환됨/취소됨)일 때 폴링을 중지합니다.
• 상태 기반: status 문자열로 표시하고 status_code 하드 코딩을 방지하기 위해 is_delivered / is_final로 프로세스를 판단합니다(소스 코드마다 정의가 다름).
• 주문 번호를 찾을 수 없음: 404는 패키지가 아직 배송 시스템에 입력되지 않았음을 의미할 가능성이 높으며(고객이 방금 주문했지만 아직 배송하지 않음) 나중에 다시 시도할 수 있습니다.

기술 지원: howyunqisoftware@gmail.com

API 버전: v1(안정적).

변경 내역: 2026-06-01 — 배송상태 조회 API v1이 온라인 상태입니다.