Dokumen Pembangunan API Pertanyaan Status Penghantaran

perjalanan pakej

API secara automatik akan menentukan peringkat mana pakej berada berdasarkan nombor pesanan, dan mengembalikan status semasa, garis masa yang lengkap, dan (jika ia telah memasuki Kastam Taiwan) kemajuan pelepasan kastam lima peringkat GC329.

Base URL

Pengepala pengesahan (pilih satu)

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

Sila hubunginya dari bahagian pelayan dan jangan letakkan kunci dalam JavaScript bahagian hadapan. Had kadar adalah dalam unit utama dan pengepala respons X-RateLimit-Remaining akan melaporkan baki had; jika melebihi had, HTTP 429 akan dikembalikan.

GETPOST /api/v1/shipment/track

Semak status penghantaran satu pakej berdasarkan nombor penjejakan. Kedua-dua GET (rentetan pertanyaan) dan POST (JSON / borang) boleh diterima.

Permintaan parameter

parameter	taip	Diperlukan	menggambarkan
tracking_number	string	Diperlukan	Nombor penjejakan pakej (4–64 aksara, abjad angka dan - _). Nombor Penjejakan China Express / Nombor Penjejakan Pelanggan / Nombor Penjejakan Penghantaran semuanya boleh diterima.

Contoh permintaan (GET)

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

Respons 200 (Contoh sudah berada di gudang/dalam transit)

{
  "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
  }
}

Respons 404 (tiada nombor pesanan ditemui)

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

padang	taip	menggambarkan
status	string	Status semasa (boleh dibaca manusia) , seperti diramalkan / disimpan / dalam transit / dihantar ke Taiwan / ditandatangani untuk penerimaan. Adalah disyorkan untuk memaparkan rentetan ini secara langsung.
status_code	number	Kod status (bergantung pada sumber, lihat bahagian seterusnya). Adalah disyorkan untuk menggunakan status, is_delivered, is_final untuk memacu UI.
is_delivered	bool	Adakah ia telah ditandatangani untuk?
is_final	bool	Sama ada ia muktamad (ditandatangani/dipulangkan/dibatalkan/tidak boleh dihantar). Benar untuk menghentikan pengundian.
logistics	string	Pembekal logistik (penghantaran terminal China Express atau Taiwan).
description	string	Penerangan acara terkini.
last_event_time	datetime	Masa acara logistik terkini.
timeline	array	Garis masa peringkat, setiap item mengandungi name / completed / time / deskripsi.
customs_stages	object|null	Kastam Taiwan GC329 Kemajuan pelepasan kastam (batal jika pelepasan kastam belum selesai). Lihat bahagian seterusnya.
events	array|null	Sejarah peristiwa logistik asal (disediakan semasa penjejakan penghantaran terminal).

Peringkat utama penyatuan (garis masa)

pentas	kepentingan
Ramalan (tidak dimasukkan ke dalam gudang)	Pelanggan telah meramalkan nombor pesanan, tetapi bungkusan itu belum tiba di Gudang Penggabungan Shenzhen.
Telah disimpan di gudang (Gudang Kontena Shenzhen)	Gudang Penggabungan Shenzhen telah menerima pakej tersebut.
Penggabungan dan pembungkusan/penghantaran Taiwan	Dibungkus dan dihantar, dihantar melalui laut/udara ke Taiwan.
Dalam transit/menghantar ke Taiwan	Pelepasan kastam dan penghantaran akhir selepas tiba di Taiwan.
Ditandatangani untuk	Penerima telah menandatangani untuk penghantaran (is_delivered = true).

Peringkat pelepasan kastam (customs_stages,GC329)

Selepas pakej memasuki Kastam Taiwan, customs_stages akan memaparkan kemajuan lima peringkat dan peratusan keseluruhan:

{
  "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	menggambarkan
401	missing_api_key / invalid_api_key	Tiada/Kunci API tidak sah.
403	insufficient_scope	Kunci belum diberikan kebenaran shipment:read.
404	not_found	Nombor penjejakan ini tidak ditemui, atau pakej masih belum memasuki sistem penyatuan.
422	validation_failed	tracking_number tiada atau tidak sepadan dengan format.
429	rate_limit_exceeded	Melebihi had permintaan seminit, lihat Cuba Semula Selepas.

• Kekerapan mengundi : Adalah disyorkan untuk menyemak nombor pesanan yang sama setiap 15-30 minit; hasilnya dicache pada pelayan ini selama 5 minit (cached: true bermaksud hit).
• menghentikan pengundian : Hentikan pengundian apabila is_final = true (ditandatangani/dipulangkan/dibatalkan).
• Pemacu status : Paparkan dengan rentetan status, gunakan is_delivered / is_final untuk mengekod proses untuk mengelak proses yang sukar status_code (takrifan kod sumber yang berbeza adalah berbeza).
• Tiada nombor pesanan :404 Berkemungkinan besar bermaksud pakej tersebut belum lagi memasuki sistem penyatuan (pelanggan baru sahaja membuat pesanan tetapi belum menghantarnya), dan anda boleh mencuba lagi kemudian.

sokongan teknikal: howyunqisoftware@gmail.com

Versi API: v1 (stabil).

Sejarah perubahan: 2026-06-01 — API pertanyaan status penghantaran v1 adalah dalam talian.