企业官网建设流程全解析

delivery-tracker API完全指南：开发者必看的物流追踪集成手册

【免费下载链接】delivery-tracker🚚 Delivery and Shipping Tracking Service项目地址: https://gitcode.com/gh_mirrors/de/delivery-tracker

delivery-tracker是一个功能强大的物流追踪服务API，它允许开发者轻松集成全球多家物流公司的包裹追踪功能到自己的应用中。通过统一的接口设计，开发者可以避免对接不同物流公司API的繁琐工作，快速实现专业的物流追踪体验。

为什么选择delivery-tracker API？

物流追踪系统开发面临诸多挑战：不同物流公司API接口差异大、数据格式不统一、国际物流追踪存在语言障碍等。delivery-tracker通过以下特性解决这些问题：

• 统一接口：无论对接哪家物流公司，都使用相同的GraphQL查询语法
• 多 carrier 支持：已集成超过20家国际物流公司，包括DHL、FedEx、UPS等
• 标准化数据：自动将不同物流商的追踪数据转换为统一格式
• 详细事件信息：提供包裹状态、时间、位置等完整追踪事件数据

快速开始：3步集成物流追踪功能

1. 准备工作

首先克隆项目仓库到本地：

git clone https://gitcode.com/gh_mirrors/de/delivery-tracker cd delivery-tracker

项目使用pnpm进行包管理，安装依赖：

pnpm install

2. 启动服务

启动API服务非常简单，执行以下命令：

pnpm run start:server

服务默认会在 http://127.0.0.1:4000/graphql 启动GraphQL接口。

3. 发送追踪请求

使用GraphQL查询获取物流信息，以下是一个基本示例：

query Track($carrierId: ID!, $trackingNumber: String!) { track(carrierId: $carrierId, trackingNumber: $trackingNumber) { trackingNumber lastEvent { time status { code name } description } events(last: 5) { edges { node { time status { code } description location { name } } } } } }

变量示例：

{ "carrierId": "kr.cjlogistics", "trackingNumber": "1234567890" }

API核心功能详解

查询物流信息（Track）

Track API是delivery-tracker的核心功能，通过packages/api/src/schema/schema.graphql定义，用于获取指定运单的详细追踪信息。

参数说明：

• carrierId: 物流公司唯一标识符（必填）
• trackingNumber: 运单号（必填）

返回数据：

• trackingNumber: 运单号
• lastEvent: 最新追踪事件
• events: 追踪事件列表（支持分页）
• sender: 发件人信息
• recipient: 收件人信息

获取物流公司列表（Carriers）

通过carriers查询可以获取系统支持的所有物流公司信息，支持分页查询：

query Carriers($first: Int, $after: String) { carriers(first: $first, after: $after) { edges { node { id } cursor } pageInfo { hasNextPage endCursor } } }

获取单个物流公司信息（Carrier）

通过carrier查询获取指定物流公司的详细信息：

query Carrier($id: ID!) { carrier(id: $id) { id } }

支持的物流状态码

delivery-tracker定义了统一的物流状态码，使不同物流公司的状态信息标准化：

enum TrackEventStatusCode { UNKNOWN # 未知状态 INFORMATION_RECEIVED # 已收到信息 AT_PICKUP # 待取件 IN_TRANSIT # 在途 OUT_FOR_DELIVERY # 派送中 ATTEMPT_FAIL # 派送失败 DELIVERED # 已送达 AVAILABLE_FOR_PICKUP # 待自取 EXCEPTION # 异常 }

完整的状态码定义可以在packages/api/src/schema/schema.graphql文件中查看。

实际应用示例

前端集成示例

以下是一个简单的JavaScript示例，展示如何在前端应用中使用delivery-tracker API：

async function trackShipment(carrierId, trackingNumber) { const response = await fetch('http://127.0.0.1:4000/graphql', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ query: ` query Track($carrierId: ID!, $trackingNumber: String!) { track(carrierId: $carrierId, trackingNumber: $trackingNumber) { trackingNumber lastEvent { time status { code name } description } } } `, variables: { carrierId, trackingNumber } }) }); const result = await response.json(); return result.data.track; } // 使用示例 trackShipment('kr.cjlogistics', '1234567890') .then(trackingInfo => console.log(trackingInfo)) .catch(error => console.error(error));

批量查询示例

对于需要同时查询多个运单的场景，可以使用GraphQL的批量查询功能：

query BatchTrack { track1: track(carrierId: "kr.cjlogistics", trackingNumber: "1234567890") { trackingNumber lastEvent { status { code } } } track2: track(carrierId: "de.dhl", trackingNumber: "9876543210") { trackingNumber lastEvent { status { code } } } }

错误处理最佳实践

delivery-tracker API定义了清晰的错误码体系，帮助开发者处理各种异常情况：

enum ErrorCode { INTERNAL # 服务器内部错误 BAD_REQUEST # 请求格式错误 NOT_FOUND # 资源未找到 }

在实际应用中，建议添加完善的错误处理逻辑：

try { const trackingInfo = await trackShipment(carrierId, trackingNumber); if (!trackingInfo) { showError('未找到追踪信息'); return; } // 处理正常情况 } catch (error) { if (error.code === 'NOT_FOUND') { showError('运单号不存在或尚未录入系统'); } else if (error.code === 'BAD_REQUEST') { showError('请检查运单号格式是否正确'); } else { showError('查询失败，请稍后重试'); } }

高级功能与性能优化

事件分页查询

对于物流记录较多的包裹，可以使用分页功能获取指定范围的事件：

query TrackEvents($carrierId: ID!, $trackingNumber: String!) { track(carrierId: $carrierId, trackingNumber: $trackingNumber) { events(first: 10, after: "cursor_value") { edges { node { time description } cursor } pageInfo { hasNextPage endCursor } } } }

缓存策略

为提高性能并减少API调用次数，建议实现合理的缓存策略：

• 对已完成的运单（状态为DELIVERED）可长期缓存
• 对活跃运单可设置短期缓存（如15-30分钟）
• 使用carrierId+trackingNumber作为缓存键

总结

delivery-tracker API为开发者提供了一个简单而强大的物流追踪解决方案。通过统一的GraphQL接口，开发者可以轻松集成多家物流公司的追踪功能，大大降低了开发复杂度。无论是电商平台、配送管理系统还是企业ERP，delivery-tracker都能提供可靠的物流追踪支持。

想要了解更多细节，可以查看项目中的examples/examples.http文件，里面包含了更多API使用示例。

【免费下载链接】delivery-tracker🚚 Delivery and Shipping Tracking Service项目地址: https://gitcode.com/gh_mirrors/de/delivery-tracker