Document de développement de l'API de requête sur le statut de l'expédition

voyage à forfait

L'API déterminera automatiquement à quelle étape se trouve le colis en fonction du numéro de commande et renverra l'état actuel, le calendrier complet et (s'il est entré dans les douanes de Taiwan) la progression du dédouanement en cinq étapes du GC329.

Base URL

En-tête d'authentification (choisissez-en un)

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

Veuillez l'appeler depuis le côté serveur et ne pas mettre la clé dans JavaScript frontal. La limite de débit est en unités clés et l'en-tête de réponse X-RateLimit-Remaining indiquera la limite restante ; si la limite est dépassée, HTTP 429 sera renvoyé.

GETPOST /api/v1/shipment/track

Vérifiez l'état d'expédition d'un seul colis en fonction du numéro de suivi. GET (chaîne de requête) et POST (JSON/formulaire) sont tous deux acceptables.

Paramètres de la demande

paramètre	Taper	Requis	illustrer
tracking_number	string	Requis	Numéro de suivi du colis (4 à 64 caractères, alphanumériques et - _). Le numéro de suivi China Express/numéro de suivi client/numéro de suivi d'expédition sont tous acceptables.

Exemple de requête (GET)

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

Réponse 200 (Exemple déjà en entrepôt/en 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
  }
}

Réponse 404 (aucun numéro de commande trouvé)

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

champ	Taper	illustrer
status	string	Statut actuel (lisible par l'homme) , tel que prévu/entreposé/en transit/expédié à Taiwan/signé pour réception. Il est recommandé d'afficher cette chaîne directement.
status_code	number	Code d'état (dépend de la source, voir la section suivante). Il est recommandé d'utiliser status, is_delivered, is_final pour piloter l'interface utilisateur.
is_delivered	bool	Est-ce qu'il a été signé ?
is_final	bool	Qu'il soit définitif (signé/retourné/annulé/non livrable). True pour arrêter le sondage.
logistics	string	Prestataire logistique (livraison terminal China Express ou Taiwan).
description	string	Description du dernier événement.
last_event_time	datetime	L’heure du dernier événement logistique.
timeline	array	Chronologie de l'étape, chaque élément contient name / completed / time / description.
customs_stages	object|null	Douanes de Taiwan GC329 Progression du dédouanement (nul si le dédouanement n'est pas encore terminé). Voir la section suivante.
events	array|null	Historique original des événements logistiques (fourni lors du suivi de livraison au terminal).

Étape principale de consolidation (chronologie)

scène	importance
Prévu (non entré en entrepôt)	Le client a prédit le numéro de commande, mais le colis n'est pas encore arrivé à l'entrepôt de consolidation de Shenzhen.
Déjà entreposé (entrepôt de conteneurs de Shenzhen)	Shenzhen Consolidation Warehouse a reçu le colis.
Consolidation et emballage/livraison à Taiwan	Emballé et expédié, expédié par mer/air vers Taiwan.
En transit/livraison à Taiwan	Dédouanement et livraison finale après arrivée à Taiwan.
Signé pour	Le destinataire a signé pour la livraison (is_delivered = true).

Étapes de dédouanement (customs_stages,GC329)

Une fois le colis entré dans les douanes de Taiwan, customs_stages fera apparaître la progression en cinq étapes et le pourcentage global :

{
  "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	illustrer
401	missing_api_key / invalid_api_key	Clé API non valide/invalide.
403	insufficient_scope	La clé n’a pas reçu l’autorisation shipment:read.
404	not_found	Ce numéro de suivi est introuvable, ou le colis n'est pas encore entré dans le système de consolidation.
422	validation_failed	tracking_number est manquant ou ne correspond pas au format.
429	rate_limit_exceeded	En cas de dépassement de la limite de requêtes par minute, voir Réessayer après.

• Fréquence d'interrogation : Il est recommandé de vérifier le même numéro de commande toutes les 15 à 30 minutes ; le résultat est mis en cache sur ce serveur pendant 5 minutes (cached : true signifie hit).
• arrête l'interrogation : Arrêtez l'interrogation lorsque is_final = true (signé/renvoyé/annulé).
• Pilote d'état  : affichage avec la chaîne status, utilisez is_delivered / is_final pour juger le processus afin d'éviter le codage en dur. status_code (les différentes définitions de code source sont différentes).
• Aucun numéro de commande :404 Cela signifie très probablement que le colis n'est pas encore entré dans le système de consolidation (le client vient de passer une commande mais ne l'a pas envoyée), et vous pourrez réessayer plus tard.

assistance technique : howyunqisoftware@gmail.com

Version API : v1 (stable).

Historique des modifications : 01/06/2026 — L'API de requête sur l'état des envois v1 est en ligne.