Dokumen Pengembangan API Kueri Status Pengiriman

perjalanan paket

API akan secara otomatis menentukan tahap mana paket tersebut berada berdasarkan nomor pesanan, dan mengembalikan status saat ini, garis waktu lengkap, dan (jika telah memasuki Bea Cukai Taiwan) kemajuan izin bea cukai lima tahap GC329.

Base URL

Header otentikasi (pilih salah satu)

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

Silakan panggil dari sisi server dan jangan letakkan kunci di JavaScript front-end. Batas tarif ada dalam satuan utama, dan header respons X-RateLimit-Remaining akan melaporkan batas yang tersisa; jika batas terlampaui, HTTP 429 akan dikembalikan.

GETPOST /api/v1/shipment/track

Periksa status pengiriman satu paket berdasarkan nomor pelacakan. Baik GET (string kueri) dan POST (JSON/formulir) dapat diterima.

Parameter permintaan

parameter	Jenis	Diperlukan	menjelaskan
tracking_number	string	Diperlukan	Nomor pelacakan paket (4–64 karakter, alfanumerik dan - _). Nomor Pelacakan China Express / Nomor Pelacakan Pelanggan / Nomor Pelacakan Pengiriman semuanya dapat diterima.

Contoh permintaan (GET)

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

Respon 200 (Contoh sudah di gudang/dalam perjalanan)

{
  "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 (tidak ditemukan nomor pesanan)

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

bidang	Jenis	menjelaskan
status	string	Status saat ini (dapat dibaca manusia) , seperti diperkirakan / disimpan / dalam perjalanan / dikirim ke Taiwan / ditandatangani untuk diterima. Disarankan untuk menampilkan string ini secara langsung.
status_code	number	Kode status (tergantung sumber, lihat bagian selanjutnya). Disarankan untuk menggunakan status, is_delivered, is_final untuk menggerakkan UI.
is_delivered	bool	Apakah sudah ditandatangani?
is_final	bool	Apakah sudah final (ditandatangani/dikembalikan/dibatalkan/tidak dapat dikirim). Benar untuk menghentikan pemungutan suara.
logistics	string	Penyedia logistik (pengiriman terminal China Express atau Taiwan).
description	string	Deskripsi acara terbaru.
last_event_time	datetime	Waktu acara logistik terbaru.
timeline	array	Garis waktu tahap, setiap item berisi nama / selesai / time / deskripsi.
customs_stages	object|null	Kemajuan perizinan Bea Cukai GC329 Bea Cukai Taiwan (batal jika perizinan bea cukai belum diselesaikan). Lihat bagian selanjutnya.
events	array|null	Riwayat peristiwa logistik asli (disediakan selama pelacakan pengiriman terminal).

Tahap utama konsolidasi (timeline)

panggung	makna
Perkiraan (tidak masuk ke gudang)	Pelanggan telah memperkirakan nomor pesanan, tetapi paket belum sampai di Gudang Konsolidasi Shenzhen.
Sudah disimpan (Gudang Kontainer Shenzhen)	Gudang Konsolidasi Shenzhen telah menerima paketnya.
Konsolidasi dan pengemasan/pengiriman Taiwan	Dikemas dan dikirim, dikirim melalui laut/udara ke Taiwan.
Sedang transit/pengiriman ke Taiwan	Izin bea cukai dan pengiriman akhir setelah tiba di Taiwan.
Ditandatangani untuk	Penerima telah menandatangani untuk pengiriman (is_delivered = true).

Tahapan bea cukai (customs_stages,GC329)

Setelah paket memasuki Bea Cukai Taiwan, customs_stages akan menampilkan kemajuan lima tahap dan persentase 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	menjelaskan
401	missing_api_key / invalid_api_key	Tidak ada/Kunci API tidak valid.
403	insufficient_scope	Kuncinya belum diberikan izin shipment:read.
404	not_found	Nomor pelacakan ini tidak ditemukan, atau paket belum masuk ke sistem konsolidasi.
422	validation_failed	nomor_pelacakan hilang atau tidak cocok dengan formatnya.
429	rate_limit_exceeded	Melebihi batas permintaan per menit, lihat Coba Lagi Setelahnya.

• Frekuensi polling : Disarankan untuk memeriksa nomor pesanan yang sama setiap 15-30 menit; hasilnya di-cache di server ini selama 5 menit (cached: true artinya kena).
• menghentikan pemungutan suara : Hentikan pemungutan suara ketika is_final = true (ditandatangani/dikembalikan/dibatalkan).
• Driver status : Ditampilkan dengan string status, gunakan is_delivered / is_final untuk menilai proses menghindari hard coding status_code (definisi kode sumber berbeda).
• Tidak ada nomor pesanan :404 Kemungkinan besar paket belum masuk sistem konsolidasi (pelanggan baru saja melakukan pemesanan tetapi belum mengirimkannya), dan Anda dapat mencoba lagi nanti.

dukungan teknis: howyunqisoftware@gmail.com

Versi API: v1 (stabil).

Ubah riwayat: 01-06-2026 — API kueri status pengiriman v1 sedang online.