Documento de desenvolvimento da API de consulta de status de remessa

viagem de pacote

A API determinará automaticamente em qual estágio o pacote se encontra com base no número do pedido e retornará o status atual, o cronograma completo e (se tiver entrado na alfândega de Taiwan) o progresso do desembaraço aduaneiro de cinco estágios do GC329.

Base URL

Cabeçalho de autenticação (escolha um)

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

Chame-o do lado do servidor e não coloque a chave no JavaScript front-end. O limite de taxa está em unidades principais e o cabeçalho de resposta X-RateLimit-Remaining reportará o limite restante; se o limite for excedido, HTTP 429 será retornado.

GETPOST /api/v1/shipment/track

Verifique o status da remessa de um único pacote com base no número de rastreamento. Tanto GET (query string) quanto POST (JSON/formulário) são aceitáveis.

Parâmetros de solicitação

parâmetro	Tipo	Obrigatório	ilustrar
tracking_number	string	Obrigatório	Número de rastreamento do pacote (4–64 caracteres, alfanumérico e - _). O número de rastreamento da China Express / número de rastreamento do cliente / número de rastreamento de remessa são todos aceitáveis.

Exemplo de solicitação (GET)

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

Resposta 200 (Exemplo já em armazém/em 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
  }
}

Resposta 404 (nenhum número de pedido encontrado)

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

campo	Tipo	ilustrar
status	string	Status atual (legível por humanos) , como previsto/armazenado/em trânsito/enviado para Taiwan/assinado para recebimento. Recomenda-se exibir esta string diretamente.
status_code	number	Código de status (depende da fonte, veja a próxima seção). Recomenda-se usar status, is_delivered, is_final para conduzir a UI.
is_delivered	bool	Foi assinado?
is_final	bool	Se é final (assinado/devolvido/cancelado/não entregue). É verdade para parar de votar.
logistics	string	Provedor de logística (entrega no terminal China Express ou Taiwan).
description	string	Descrição do último evento.
last_event_time	datetime	A hora do último evento de logística.
timeline	array	Linha do tempo do estágio, cada item contém nome / concluído / time / descrição.
customs_stages	object|null	Alfândega de Taiwan GC329 Progresso do desembaraço aduaneiro (nulo se o desembaraço aduaneiro ainda não tiver sido concluído). Veja a próxima seção.
events	array|null	Histórico original de eventos logísticos (fornecido durante o rastreamento de entrega no terminal).

Estágio principal de consolidação (linha do tempo)

estágio	significado
Previsto (não inserido no armazém)	O cliente previu o número do pedido, mas o pacote ainda não chegou ao Armazém de Consolidação de Shenzhen.
Já armazenado (Armazém de Contêineres de Shenzhen)	O Armazém de Consolidação de Shenzhen recebeu o pacote.
Consolidação e embalagem/entrega em Taiwan	Embalado e enviado, enviado por via marítima/aérea para Taiwan.
Em trânsito/entrega para Taiwan	Desembaraço aduaneiro e entrega final após chegada em Taiwan.
Assinado por	O destinatário assinou a entrega (is_delivered = true).

Etapas de desembaraço aduaneiro (customs_stages,GC329)

Depois que o pacote entrar na alfândega de Taiwan, customs_stages trará o progresso em cinco estágios e a porcentagem geral:

{
  "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	Nenhuma chave de API/inválida.
403	insufficient_scope	A chave não recebeu a permissão shipment:read.
404	not_found	Este número de rastreamento não foi encontrado ou o pacote ainda não entrou no sistema de consolidação.
422	validation_failed	número_de_rastreamento está faltando ou não corresponde ao formato.
429	rate_limit_exceeded	Excedendo o limite de solicitações por minuto, consulte Tentar novamente após.

• Frequência de polling : Recomenda-se verificar o mesmo número de pedido a cada 15-30 minutos; o resultado é armazenado em cache neste servidor por 5 minutos (cached: true significa acerto).
• interrompe a sondagem : Interrompe a sondagem quando is_final = true (assinado/retornado/cancelado).
• Driver de status : Exiba com a string status, use is_delivered / is_final para julgar o processo e evitar codificação rígida status_code (diferentes definições de código-fonte são diferentes).
• Nenhum número de pedido :404 Provavelmente significa que o pacote ainda não entrou no sistema de consolidação (o cliente acabou de fazer um pedido, mas não o enviou) e você pode tentar novamente mais tarde.

suporte técnico: howyunqisoftware@gmail.com

Versão da API: v1 (estável).

Histórico de alterações: 01/06/2026 — API de consulta de status de remessa v1 está online.