PHPackages                             thank-song/track123 - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. thank-song/track123

ActiveLibrary[API Development](/categories/api)

thank-song/track123
===================

Laravel package for Track123 API.

V1.25.1221(6mo ago)010MITPHPPHP ^8.0

Since Dec 16Pushed 6mo agoCompare

[ Source](https://github.com/AndyMoxq/track-123)[ Packagist](https://packagist.org/packages/thank-song/track123)[ RSS](/packages/thank-song-track123/feed)WikiDiscussions main Synced today

READMEChangelog (4)DependenciesVersions (5)Used By (0)

Track123 OpenAPI Laravel Package
================================

[](#track123-openapi-laravel-package)

`thank-song/track123` 是一个用于接入 **Track123 快递轨迹 OpenAPI** 的 Laravel 工具包，支持物流单号注册、查询、轨迹同步及队列处理，适用于中大型 Laravel 项目。

---

⚙️ 环境要求
-------

[](#️-环境要求)

- PHP >= 8.0
- Laravel >= 9.0
- MySQL >= 8.0

---

📦 安装
----

[](#-安装)

通过 Composer 安装：

```
composer require thank-song/track123
```

---

⚙️ 配置
-----

[](#️-配置)

在项目 `.env` 文件中添加以下配置：

```
TRACK123_API_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxx   # Track123 API Token（必填）
TRACK123_API_URL=https://api.track123.com/gateway/open-api/  # API 地址（可选）
```

> ⚠️ `TRACK123_API_TOKEN` 为必填项，否则接口请求将失败。

---

🗄 数据库迁移
-------

[](#-数据库迁移)

本包内置所需的数据表迁移文件，直接执行：

```
php artisan migrate
```

---

🧠 核心概念
------

[](#-核心概念)

模型说明Courier快递商信息（由 Track123 提供）Tracking物流单号主体TrackingDetail轨迹节点明细TrackingExtraInfo额外轨迹信息LocalLogistic本地物流补充信息---

🚀 使用说明
------

[](#-使用说明)

### 1️⃣ 获取 Courier（快递商）列表

[](#1️⃣-获取-courier快递商列表)

```
php artisan track123:get-couriers
```

该命令将：

- 从 Track123 API 拉取最新快递商
- 同步更新本地 couriers 表
- 刷新缓存（如有）

---

### 2️⃣ 注册物流单号（Tracking）

[](#2️⃣-注册物流单号tracking)

#### 2.1 使用工厂静态方法注册（同步）

[](#21-使用工厂静态方法注册同步)

```
use ThankSong\Track123\Track123;

try {
    $trackings = [
        ['trackNo' => '886000000087', 'courierCode' => 'fedex'],
        ['trackNo' => '886000000007', 'courierCode' => 'fedex'],
        ['trackNo' => '886000000003', 'courierCode' => 'fedex'],
    ];

    $res = Track123::register($trackings);

    var_dump($res->getAccepted());          // 注册成功的单号
    var_dump($res->getRejected());          // 注册失败的单号
    var_dump($res->getRejectedMessages());  // 失败原因
} catch (\Throwable $e) {
    var_dump($e->getMessage());
}
```

---

#### 2.2 使用队列 Job 注册（推荐生产环境）

[](#22-使用队列-job-注册推荐生产环境)

```
use ThankSong\Track123\Jobs\RegisterTrackingJob;

$trackings = [
    ['trackNo' => '886000000087', 'courierCode' => 'fedex'],
    ['trackNo' => '886000000007', 'courierCode' => 'fedex'],
    ['trackNo' => '886000000003', 'courierCode' => 'fedex'],
];

RegisterTrackingJob::dispatch($trackings)->onQueue('default');
```

---

### 3️⃣ 查询物流轨迹

[](#3️⃣-查询物流轨迹)

#### 3.1 使用工厂静态方法查询

[](#31-使用工厂静态方法查询)

```
use ThankSong\Track123\Track123;

try {
    // 单个单号查询
    $res = Track123::query('886000000003');

    // 批量查询示例
    /*
    $trackings = [
        ['trackNo' => '886000000007'],
        ['trackNo' => '886000000087'],
    ];
    $res = Track123::queryTrackings($trackings);
    */

    var_dump($res->getAccepted());          // 查询成功
    var_dump($res->getRejected());          // 查询失败
    var_dump($res->getRejectedMessages());  // 失败原因
} catch (\Throwable $e) {
    var_dump($e->getMessage());
}
```

---

#### 3.2 使用 Artisan 命令查询（并同步模型数据）

[](#32-使用-artisan-命令查询并同步模型数据)

```
php artisan track123:query "886000000003"
```

该命令将：

- 向 Track123 查询最新轨迹
- 同步更新 Tracking / Detail / ExtraInfo 等模型

---

🧰 Artisan 命令汇总
--------------

[](#-artisan-命令汇总)

命令说明`track123:get-couriers`同步快递商列表`track123:query {tracking_no}`查询并更新物流轨迹---

### 4️⃣ 修改快递商信息

[](#4️⃣-修改快递商信息)

```
try {
    $res= Track123::changeCarrier(oldCourierCode: 'mng-kargo',trackNo: '886957347096',newCourierCode: 'fedex');
    var_dump($res->getMessage());          // 响应信息
} catch (\Throwable $e) {
    var_dump($e->getMessage());
}
```

---

设置webhook
---------

[](#设置webhook)

your-domin.com/api/track123/webhook

❓ 常见问题
------

[](#-常见问题)

### Q：数据是 UTC 还是本地时间？

[](#q数据是-utc-还是本地时间)

- Track123 返回时间通常为 **UTC**
- 建议按 UTC 存库
- 展示时可使用 Carbon 转换时区（例如 America/Los\_Angeles）

### Q：是否支持队列？

[](#q是否支持队列)

- 支持
- 注册与查询均可通过 Job 执行，适合高并发 / 批量场景

---

📄 License
---------

[](#-license)

MIT License

###  Health Score

31

—

LowBetter than 66% of packages

Maintenance67

Regular maintenance activity

Popularity5

Limited adoption so far

Community2

Small or concentrated contributor base

Maturity43

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~1 days

Total

4

Last Release

195d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/165084870?v=4)[AndyMoxq](/maintainers/AndyMoxq)[@AndyMoxq](https://github.com/AndyMoxq)

---

Tags

laraveltrack123

### Embed Badge

![Health badge](/badges/thank-song-track123/health.svg)

```
[![Health](https://phpackages.com/badges/thank-song-track123/health.svg)](https://phpackages.com/packages/thank-song-track123)
```

###  Alternatives

[rakibdevs/openweather-laravel-api

Laravel package to connect https://openweathermap.org/ to get customized weather data for any location on the globe immediately

7652.6k](/packages/rakibdevs-openweather-laravel-api)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)