API 串接文件

歡迎使用 773511.com RESTful API。本文件說明如何從您的 ERP、電商後台或企業系統串接本平台。

基本資訊

| 項目 | 值 |
|---|---|
| Base URL | `https://773511.com/api` |
| 通訊協定 | HTTPS |
| 資料格式 | JSON (UTF-8) |
| 認證方式 | API Key（請洽業務取得） |
| 時間格式 | ISO 8601 (`YYYY-MM-DDTHH:mm:ssZ`) |

認證

所有 API 請求需帶上 API Key：

```http Authorization: Bearer YOUR_API_KEY Content-Type: application/json ```

端點列表

訂單相關

| 方法 | 端點 | 說明 |
|---|---|---|
| POST | `/orders/estimate` | 估價（不落庫） |
| POST | `/orders/create` | 建立訂單 |
| GET | `/orders/list` | 訂單列表 |
| GET | `/orders/detail?id={id}` | 訂單詳情 |
| POST | `/orders/cancel` | 取消訂單 |
| POST | `/orders/rate` | 評價司機 |

司機相關

| 方法 | 端點 | 說明 |
|---|---|---|
| GET | `/driver/available` | 搶單池 |
| POST | `/driver/accept` | 搶單 |
| POST | `/driver/status` | 更新訂單狀態 |
| POST | `/driver/location` | 上報位置 |
| POST | `/driver/online` | 上/下線 |

範例：建立訂單

Request

```http POST /api/orders/create Authorization: Bearer YOUR_API_KEY Content-Type: application/json

{ "vehicle_type": "small", "pickup_address": "台北市中正區重慶南路一段 122 號", "pickup_lat": 25.0478, "pickup_lng": 121.5170, "dropoff_address": "台北市信義區松仁路 100 號", "dropoff_lat": 25.0335, "dropoff_lng": 121.5645, "km": 3.8, "cargo_desc": "3 箱辦公文件", "pickup_time": "2026-09-12T15:00:00+08:00", "payment_method": "monthly", "external_order_id": "ERP-202609-001" } ```

Response

```json { "ok": true, "order_id": 12345, "order_no": "ORD202609121500001234", "estimated_price": 345, "message": "訂單已建立" } ```

Webhook

當訂單狀態變更時，本平台會主動推送 POST 請求到您註冊的 Webhook URL：

```json { "order_no": "ORD202609121500001234", "status": "in_transit", "driver_id": 123, "driver_name": "林大哥", "driver_phone": "0912-*-888", "updated_at": "2026-09-12T15:30:00+08:00" } ```

請使用 HMAC-SHA256 驗證簽章（Header: `X-773511-Signature`）。

錯誤碼

| HTTP | 說明 |
|---|---|
| 200 | 成功 |
| 400 | 參數錯誤 |
| 401 | 未登入 / API Key 無效 |
| 403 | 權限不足 |
| 404 | 資源不存在 |
| 409 | 衝突（如訂單已被搶） |
| 429 | 超過 rate limit |
| 500 | 伺服器錯誤 |

Rate Limit

| 層級 | 限制 |
|---|---|
| 讀取 | 600 次 / 分鐘 |
| 寫入 | 60 次 / 分鐘 |
| 批次 | 1 次 / 分鐘（最多 500 筆） |

申請 API Key

請聯絡業務取得 API Key：

- 業務信箱：[[email protected]](mailto:[email protected]) - 業務電話：0906-044-601

技術支援

- API 問題：[[email protected]](mailto:[email protected]) - 問題回報：[GitHub Issues](https://github.com/773511/api)（公開後）