Documento de desarrollo de API de consulta de estado de envío

viaje combinado

La API determinará automáticamente en qué etapa se encuentra el paquete según el número de pedido y devolverá el estado actual, el cronograma completo y (si ha ingresado a la Aduana de Taiwán) el progreso del despacho de aduana de cinco etapas GC329.

Base URL

Encabezado de autenticación (elija uno)

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

Llámelo desde el lado del servidor y no coloque la clave en el JavaScript del front-end. El límite de tasa está en unidades clave y el encabezado de respuesta X-RateLimit-Remaining informará el límite restante; si se excede el límite, se devolverá HTTP 429.

GETPOST /api/v1/shipment/track

Verifique el estado del envío de un solo paquete según el número de seguimiento. Tanto GET (cadena de consulta) como POST (JSON/formulario) son aceptables.

Solicitar parámetros

parámetro	Tipo	Requerido	ilustrar
tracking_number	string	Requerido	Número de seguimiento del paquete (de 4 a 64 caracteres, alfanuméricos y - _). Se aceptan el número de seguimiento de China Express, el número de seguimiento del cliente y el número de seguimiento del envío.

Ejemplo de solicitud (OBTENER)

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

Respuesta 200 (Ejemplo ya en almacén/en tránsito)

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

Respuesta 404 (no se encontró ningún número de pedido)

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

campo	Tipo	ilustrar
status	string	Estado actual (legible por humanos) , como previsto/almacenado/en tránsito/enviado a Taiwán/firmado para recepción. Se recomienda mostrar esta cadena directamente.
status_code	number	Código de estado (depende de la fuente, consulte la siguiente sección). Se recomienda utilizar status, is_delivered, is_final para controlar la interfaz de usuario.
is_delivered	bool	¿Ha sido firmado?
is_final	bool	Si es definitivo (firmado/devuelto/cancelado/no entregable). Cierto para dejar de sondear.
logistics	string	Proveedor de logística (entrega en terminal China Express o Taiwán).
description	string	Descripción del último evento.
last_event_time	datetime	La hora del último evento logístico.
timeline	array	Línea de tiempo de la etapa, cada elemento contiene name / completed / time / description.
customs_stages	object|null	Aduana de Taiwán GC329 Progreso del despacho de aduana (nulo si el despacho de aduana aún no se ha completado). Consulte la siguiente sección.
events	array|null	Historial de eventos logísticos original (proporcionado durante el seguimiento de entrega en la terminal).

Principal etapa de consolidación (cronograma)

escenario	significado
Pronosticado (no ingresado en el almacén)	El cliente predijo el número de pedido, pero el paquete aún no ha llegado al almacén de consolidación de Shenzhen.
Ya almacenado (Shenzhen Container Warehouse)	Shenzhen Consolidation Warehouse ha recibido el paquete.
Consolidación y embalaje/entrega en Taiwán	Embalado y enviado, enviado por mar/aire a Taiwán.
En tránsito/entrega a Taiwán	Despacho de aduana y entrega final después de la llegada a Taiwán.
Firmado por	El destinatario ha firmado para la entrega (is_delivered = true).

Etapas de despacho de aduanas (customs_stages,GC329)

Después de que el paquete ingrese a la Aduana de Taiwán, customs_stages mostrará el progreso de cinco etapas y el porcentaje general:

{
  "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	ilustrar
401	missing_api_key / invalid_api_key	Clave API nula o no válida.
403	insufficient_scope	A la clave no se le ha otorgado el permiso shipment:read.
404	not_found	Este número de seguimiento no se encuentra o el paquete aún no ha entrado al sistema de consolidación.
422	validation_failed	Falta el número de seguimiento o no coincide con el formato.
429	rate_limit_exceeded	Exceder el límite de solicitudes por minuto, consulte Reintentar después.

• Frecuencia de sondeo : Se recomienda verificar el mismo número de pedido cada 15-30 minutos; el resultado se almacena en caché en este servidor durante 5 minutos (cached: true significa hit).
• deja de sondear : Detiene el sondeo cuando is_final = true (firmado/devuelto/cancelado).
• Controlador de estado : muestra con la cadena status, use is_delivered / is_final para juzgar el proceso y evitar la codificación rígida status_code (las diferentes definiciones de código fuente son diferentes).
• Sin número de pedido :404 Lo más probable es que signifique que el paquete aún no ha ingresado al sistema de consolidación (el cliente acaba de realizar un pedido pero no lo ha enviado), y puede volver a intentarlo más tarde.

apoyo técnico: howyunqisoftware@gmail.com

Versión API: v1 (estable).

Historial de cambios: 2026-06-01: La API v1 de consulta de estado del envío está en línea.