Skip to content

目录

ShaQ Express 公共 API 文档

欢迎使用 ShaQ Express 公共 API。本文档为合作伙伴和开发者提供所需的接口端点，以便无缝管理包裹、货运并接收追踪更新。

信息 值
版本 1.0
开发基础 URL https://test-partner.shaqexpress.com/api/v1

标准请求头

向 API 发出的所有请求都应包含以下标准 HTTP 请求头：

请求头 类型 描述
Content-Type application/json 请求体须为 JSON 格式
Accept application/json 期望响应体为 JSON 格式

（注意：受保护的端点还需要 Authorization: Bearer <token> 请求头，该令牌通过登录获取）。

包裹状态

我们的系统使用多种状态来追踪包裹的生命周期。以下是您可能收到的完整状态列表：

📦 待处理 & 收取

  • pending ：包裹尚未从合作伙伴处收取
  • received ：包裹已从合作伙伴处收取
  • warehouse_received ：包裹已在区域仓库签收
  • collected ：ShaQ Express 已从合作伙伴处取走包裹
  • ready_for_pickup ：包裹已准备好供客户自取

🚚 运输 & 派发

  • shipped ：包裹已由合作伙伴发出
  • assigned ：包裹已分配给骑手
  • in_transit ：包裹正在运往最近仓库途中
  • dispatched ：包裹正在派送途中

✅ 配送结果

  • confirmed ：已联系客户并确认配送
  • delivered ：包裹已成功送达客户

⚠️ 问题 & 异常

  • not_delivered ：尝试配送但未能完成
  • rescheduled ：包裹配送已重新安排新的配送时间
  • customer_hold ：应客户要求，配送暂停
  • customer_unreachable ：因无法联系客户，配送暂停
  • suspected_scam ：因疑似欺诈，配送暂停

🔙 退回

  • return_picked ：包裹已从客户处取回，准备退回合作伙伴
  • return_in_progress ：包裹正在准备退回合作伙伴
  • returned_to_sender ：包裹已退回合作伙伴
  • return_to_central ：经多次配送失败后，包裹正被退回 ShaQ Express 中央仓库，以准备退回合作伙伴

API 端点

登录

POST /auth/login

获取后续请求所需的身份验证令牌。 出于安全考虑，令牌有效期为 7 天，到期后需通过 /auth/login 路由重新生成。

请求参数

参数 类型 描述
identifier string 必填。
secret string 必填。

响应

200

{
  "message": "Request successful",
  "data": {
    "token": "UtXdU9HODhjdmtTNkRtUWNsVlM4OWI1d2Z2TXVIanlkRk"
  }
}

获取包裹列表

GET /packages?page=1&limit=1

获取所有包裹

请求头

参数 类型 描述
Authorization bearer 必填。

响应

200

{
  "message": "Request successful",
  "data": {
    "list": [
      {
        "partnerRef": "FGVHKJ567",
        "trackingNumber": "20250410X51DIQ",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceCountry": "Ghana",
        "sourceAddressLine1": "Accra Spintex",
        "sourceAddressLine2": null,
        "destinationCountry": "Ghana",
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "units": 1,
        "type": "box",
        "value": "300.00",
        "amountToCollect": "300.00",
        "paymentCollector": "shaq",
        "handling": "normal",
        "specialInstructions": null,
        "status": "delivered",
        "statusDescription": "Package was successfully delivered to customer",
        "latitude": null,
        "longitude": null,
        "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "dateCreated": "2025-04-10 11:15",
        "eta": "2026-04-20 - 2026-04-22",
        "items": [
          {
            "name": "iPhone 6",
            "quantity": 1
          },
          {
            "name": "iPhone 14 Pro",
            "quantity": 2
          }
        ]
      },
      {
        "partnerRef": "FGVHKJ567",
        "trackingNumber": "20250410X51DIQ",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceCountry": "Ghana",
        "sourceAddressLine1": "Accra Spintex",
        "sourceAddressLine2": null,
        "destinationCountry": "Ghana",
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
        "units": 1,
        "type": "box",
        "value": "300.00",
        "amountToCollect": "300.00",
        "paymentCollector": "shaq",
        "handling": "normal",
        "specialInstructions": null,
        "status": "pending",
        "statusDescription": "Package is yet to be received from Partner.",
        "latitude": null,
        "longitude": null,
        "proofPhotoUrl": null,
        "dateCreated": "2025-04-10 11:15",
        "eta": "2026-04-20 - 2026-04-22",
        "items": [
          {
            "name": "iPhone 6",
            "quantity": 1
          }
        ]
      }
    ],
    "meta": {
      "total": 2,
      "perPage": 15,
      "currentPage": 1,
      "lastPage": 1
    }
  }
}

获取单个包裹

GET /packages/{partnerRef}

获取包裹详情

请求头

参数 类型 描述
Authorization bearer 必填。

响应

200

{
  "message": "Request successful",
  "data": {
    "partnerRef": "FGVHKJ567",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "sourceCountry": "Ghana",
    "sourceAddressLine1": "Accra Spintex",
    "sourceAddressLine2": null,
    "destinationCountry": "Ghana",
    "destinationRegion": "Greater Accra",
    "destinationCity": "Accra",
    "destinationAddressLine1": "UPSA Hall, Room 3",
    "destinationAddressLine2": null,
    "destinationPostalCode": null,
    "length": 0,
    "height": 5,
    "weight": 1.2,
    "description": "iPhone 16 pro max black edge silver back casing",
    "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "units": 1,
    "type": "box",
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "handling": "normal",
    "specialInstructions": null,
    "status": "not_delivered",
    "statusDescription": "Attempted delivery but couldn't complete it.",
    "latitude": null,
    "longitude": null,
    "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "dateCreated": "2025-04-10 11:15",
    "eta": "2026-04-20 - 2026-04-22",
    "items": [
      {
        "name": "iPhone 6",
        "quantity": 1
      },
      {
        "name": "iPhone 14 Pro",
        "quantity": 2
      }
    ],
    "trackingHistory": [
      {
        "name": "not_delivered",
        "description": "Attempted delivery but couldn't complete it.",
        "date": "2025-07-16 09:00",
        "comment": "Customer was unreachable upon arrival. Package rescheduled for 2nd delivery attempt."
      },
      {
        "name": "dispatched",
        "description": "Package is en-route to deliver.",
        "date": "2025-07-15 15:45",
        "comment": null
      },
      {
        "name": "confirmed",
        "description": "Customer has been called and delivery confirmed.",
        "date": "2025-07-15 15:45",
        "comment": null
      },
      {
        "name": "received",
        "description": "Package has been received from Partner.",
        "date": "2025-07-15 15:38",
        "comment": null
      },
      {
        "name": "pending",
        "description": "Package is yet to be received by Partner.",
        "date": "2025-07-14 10:38",
        "comment": null
      }
    ]
  }
}

删除待处理包裹

DELETE /packages/{partnerRef}

删除一个包裹。只有待处理状态的包裹可以被删除。

请求头

参数 类型 描述
Authorization bearer 必填。

响应

200

{
  "message": "Package deleted",
  "data": null
}

取消订单

POST /packages/{partnerRef}/cancel

取消一个履约订单。

请求头

参数 类型 描述
Authorization bearer 必填。

响应

200

{
  "message": "Order cancelled successfully",
  "data": null
}

400

{
  "message": "Order cannot be cancelled. Order cancellation failed",
  "data": null
}

404

{
  "message": "Order not found",
  "data": null
}

创建单个包裹

POST /packages

创建单个包裹

请求头

参数 类型 描述
Authorization bearer 必填。

请求参数

参数 类型 描述
tracking_number string 可选。
partner_ref string 必填。必须唯一。
customer_name string 必填。
customer_phone_1 string 必填。
customer_phone_2 string 可选。
source_country_iso2 string 必填。
source_address_line_1 string 必填。
source_address_line_2 string 可选。
destination_region string 当 region_id 为空时必填。
destination_city string 必填。
destination_address_line_1 string 必填。
destination_address_line_2 string 可选。
destination_postal_code string 可选。
length decimal 可选。
height decimal 可选。
weight decimal 可选。
description string 必填。
units string 必填。
type string 必填，可选值：parcel、box
handling string 必填，可选值：normal、fragile
special_instructions string 可选。
latitude decimal 可选。
longitude decimal 可选。
value decimal 必填。
amount_to_collect decimal 可选。默认等于包裹的 value。
payment_collector string 可选，可选值：shaq、partner（此参数仅在 ShaQ Express 为收款方时可发送。用于指定由谁负责向客户收取包裹款项，适用于合作伙伴负责收款的特殊情况。若未提供，将使用默认的收款方配置。）
items array 必填。{name, quantity}
region_id integer 当 destination_region 为空时必填。

响应

200

{
  "message": "Package created successfully",
  "data": {
    "partnerRef": "UNIQUE-REF-001",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "altPhone": null,
    "destinationCountry": "Ghana",
    "destinationRegion": "Greater Accra",
    "destinationCity": "Accra",
    "destinationAddressLine1": "UPSA Hall, Room 3",
    "destinationAddressLine2": null,
    "destinationPostalCode": null,
    "length": 0,
    "height": 5,
    "weight": 1.2,
    "description": "iPhone 16 pro max black edge silver back casing",
    "units": 1,
    "type": "box",
    "handling": "normal",
    "specialInstructions": null,
    "status": "pending",
    "statusDescription": "Package is yet to be received by Partner",
    "landmark": null,
    "proofPhotoUrl": null,
    "partner": "Demo Partner",
    "scheduleDate": null,
    "deliveryFee": null,
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "paymentStatus": null,
    "date": "2025-04-10 11:15",
    "deliveredAt": null,
    "eta": "2026-04-20 - 2026-04-22",
    "deliveryAttempts": 0,
    "items": [
      { "name": "iPhone 6", "quantity": 1 },
      { "name": "iPhone 14 Pro", "quantity": 2 }
    ]
  }
}

404

{
  "message": "No Region with name {destination_region} found",
  "data": null
}

批量创建多个包裹

POST /packages/bulk

批量创建多个包裹

请求头

参数 类型 描述
Authorization bearer 必填。

请求参数

参数 类型 描述
packages array 必填。
packages.*.tracking_number string 可选。
packages.*.partner_ref string 必填。
packages.*.customer_name string 必填。
packages.*.customer_phone_1 string 必填。
packages.*.customer_phone_2 string 可选。
packages.*.source_country_iso2 string 必填。
packages.*.source_address_line_1 string 必填。
packages.*.source_address_line_2 string 可选。
packages.*.destination_region string 当 region_id 为空时必填。
packages.*.destination_city string 必填。
packages.*.destination_address_line_1 string 必填。
packages.*.destination_address_line_2 string 可选。
packages.*.destination_postal_code string 可选。
packages.*.length decimal 可选。
packages.*.height decimal 可选。
packages.*.weight decimal 可选。
packages.*.description string 必填。
packages.*.units string 必填。
packages.*.type string 必填，可选值：parcel、box
packages.*.handling string 必填，可选值：normal、fragile
packages.*.special_instructions string 可选。
packages.*.latitude decimal 可选。
packages.*.longitude decimal 可选。
packages.*.value decimal 必填。
packages.*.amount_to_collect decimal 可选。默认等于包裹的 value。
packages.*.payment_collector string 可选，可选值：shaq、partner（此参数仅在 ShaQ Express 为收款方时可发送。用于指定由谁负责向客户收取包裹款项，适用于合作伙伴负责收款的特殊情况。若未提供，将使用默认的收款方配置。）
packages.*.items array 必填。{name, quantity}
packages.*.region_id integer 当 destination_region 为空时必填。

响应

200

{
  "message": "Packages created successfully",
  "data": null
}

创建货运单

POST /shipments

创建一个货运单，代表将发送给 ShaQ Express 的实物包裹批次。

请求头

参数 类型 描述
Authorization bearer 必填。

请求参数

参数 类型 描述
packages array 必填。
packages.*.tracking_number string 可选。
packages.*.partner_ref string 必填。
packages.*.customer_name string 必填。
packages.*.customer_phone_1 string 必填。
packages.*.customer_phone_2 string 可选。
packages.*.source_country_iso2 string 必填。
packages.*.source_address_line_1 string 必填。
packages.*.source_address_line_2 string 可选。
packages.*.destination_region string 当 region_id 为空时必填。
packages.*.destination_city string 必填。
packages.*.destination_address_line_1 string 必填。
packages.*.destination_address_line_2 string 可选。
packages.*.destination_postal_code string 可选。
packages.*.length decimal 可选。
packages.*.height decimal 可选。
packages.*.weight decimal 可选。
packages.*.description string 必填。
packages.*.units string 必填。
packages.*.type string 必填，可选值：parcel、box
packages.*.handling string 必填，可选值：normal、fragile
packages.*.special_instructions string 可选。
packages.*.latitude decimal 可选。
packages.*.longitude decimal 可选。
packages.*.value decimal 必填。
packages.*.amount_to_collect decimal 可选。默认等于包裹的 value。
packages.*.payment_collector string 可选，可选值：shaq、partner（此参数仅在 ShaQ Express 为收款方时可发送。用于指定由谁负责向客户收取包裹款项，适用于合作伙伴负责收款的特殊情况。若未提供，将使用默认的收款方配置。）
packages.*.items array 必填。{name, quantity}
packages.*.region_id integer 当 destination_region 为空时必填。

响应

200

{
  "message": "Shipment created successfully",
  "data": {
    "reference": "PAR-20260322053800"
  }
}

获取单个货运单

GET /shipments/{reference}

获取货运单详情

请求头

参数 类型 描述
Authorization bearer 必填。

响应

200

{
  "message": "Request successful",
  "data": {
    "reference": "SAAM-20260322053800",
    "date": "2026-03-22 05:38",
    "packages": [
      {
        "partnerRef": "qwertyui1a1aaqweqqaqx",
        "trackingNumber": "C561819A",
        "customerName": "Kwaku Ananse",
        "customerPhone1": "+233244100200",
        "customerPhone2": null,
        "sourceAddressLine1": "Accra spintex basket junction",
        "sourceAddressLine2": null,
        "destinationRegion": "Greater Accra",
        "destinationCity": "Accra",
        "destinationAddressLine1": "UPSA Hall, Room 3",
        "destinationAddressLine2": null,
        "destinationPostalCode": null,
        "length": 0,
        "height": 5,
        "weight": 1.2,
        "description": "iPhone 16 pro max black edge silver back casing",
        "units": 1,
        "type": "box",
        "handling": "normal",
        "specialInstructions": null,
        "status": "pending",
        "statusDescription": "Package is yet to be received by Partner",
        "latitude": null,
        "longitude": null,
        "value": "1468.00",
        "amountToCollect": "1468.00",
        "paymentCollector": "shaq",
        "date": "2026-03-22 05:38",
        "eta": "2026-04-20 - 2026-04-22",
        "trackingUrl": "https://dev.tracking-website.pages.dev/packages/C561819A",
        "items": [
          {
            "name": "14cm Alya Glass Cookie Holder - Transparent",
            "quantity": 4
          },
          {
            "name": "10.6 Color Splicing Cotton Rope Storage Basket Toys Clothes Sundries Storage Basket AB-026 - Beige Yellow+White",
            "quantity": 1
          },
          {
            "name": "6 Pieces Nossa 21cm Cake Plate Set",
            "quantity": 1
          }
        ]
      }
    ]
  }
}

更新包裹

PATCH /packages/{partnerRef}

更新特定包裹

请求头

参数 类型 描述
Authorization bearer 必填。

请求参数

参数 类型 描述
tracking_number string 可选。
customer_name string 可选。
customer_phone_1 string 可选。
customer_phone_2 string 可选。
source_country_iso2 string 可选。
source_address_line_1 string 可选。
source_address_line_2 string 可选。
destination_region string 可选。
destination_city string 可选。
destination_address_line_1 string 可选。
destination_address_line_2 string 可选。
destination_postal_code string 可选。
length decimal 可选。
height decimal 可选。
weight decimal 可选。
description string 可选。
units string 可选。
type string 可选，可选值：parcel、box
handling string 可选，可选值：normal、fragile
special_instructions string 可选。
latitude decimal 可选。
longitude decimal 可选。
value decimal 可选。
amount_to_collect decimal 可选。
items array 可选。{name, quantity}

响应

200

{
  "message": "Request successful",
  "data": {
    "partnerRef": "FGVHKJ567",
    "trackingNumber": "20250410X51DIQ",
    "customerName": "Kwaku Ananse",
    "customerPhone1": "+233244100200",
    "customerPhone2": null,
    "sourceCountry": "Ghana",
    "sourceAddressLine1": "Accra Spintex",
    "sourceAddressLine2": null,
    "destinationCountry": "Ghana",
    "destinationRegion": "Greater Accra",
    "destinationCity": "Accra",
    "destinationAddressLine1": "UPSA Hall, Room 3",
    "destinationAddressLine2": null,
    "destinationPostalCode": null,
    "length": 0,
    "height": 5,
    "weight": 1.2,
    "description": "iPhone 16 pro max black edge silver back casing",
    "labelUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "units": 1,
    "type": "box",
    "value": "300.00",
    "amountToCollect": "300.00",
    "paymentCollector": "shaq",
    "handling": "normal",
    "specialInstructions": null,
    "status": "not_delivered",
    "statusDescription": "Attempted delivery but couldn't complete it.",
    "latitude": null,
    "longitude": null,
    "proofPhotoUrl": "https://debtufr1vwh35.cloudfront.net/labels_test/label/8B73CE6D.png",
    "dateCreated": "2025-04-10 11:15",
    "eta": "2026-04-20 - 2026-04-22",
    "items": [
      {
        "name": "iPhone 6",
        "quantity": 1
      },
      {
        "name": "iPhone 14 Pro",
        "quantity": 2
      }
    ],
    "trackingHistory": [
      {
        "name": "not_delivered",
        "description": "Attempted delivery but couldn't complete it.",
        "date": "2025-07-16 09:00",
        "comment": "Customer was unreachable upon arrival. Package rescheduled for 2nd delivery attempt."
      },
      {
        "name": "dispatched",
        "description": "Package is en-route to deliver.",
        "date": "2025-07-15 15:45",
        "comment": null
      }
    ]
  }
}

追踪包裹

GET /tracking/{trackingNumber}

获取特定包裹的追踪状态

请求头

参数 类型 描述
Authorization bearer 必填。

响应

200

{
  "message": "Package tracking",
  "data": {
    "partnerRef": "FGVHKJ567",
    "trackingNumber": "20250410X51DIQ",
    "description": "Kitchen cabinet",
    "status": "shipped",
    "statusDescription": "Package has been shipped by Partner.",
    "eta": "2026-04-20 - 2026-04-22",
    "items": [
      {
        "name": "iPhone 6",
        "quantity": 1
      },
      {
        "name": "iPhone 14 Pro",
        "quantity": 2
      }
    ],
    "tracking": [
      {
        "status": "shipped",
        "description": "Package has been shipped by Partner.",
        "date": "2025-04-10 15:17"
      },
      {
        "status": "pending",
        "description": "Package is yet to be shipped by Partner.",
        "date": "2025-04-10 15:16"
      },
      {
        "status": "shipped",
        "description": "Package has been shipped by Partner.",
        "date": "2025-04-10 15:15"
      },
      {
        "status": "shipped",
        "description": "Package has been shipped by Partner.",
        "date": "2025-04-10 15:15"
      },
      {
        "status": "pending",
        "description": "Package is yet to be shipped by Partner.",
        "date": "2025-04-10 15:14"
      }
    ]
  }
}

获取地区列表

GET /setup/regions

获取所有可用地区

请求头

参数 类型 描述
Authorization bearer 必填。

响应

200

{
  "message": "Request successful",
  "data": [
    {
      "id": 16,
      "name": "Western North"
    },
    {
      "id": 15,
      "name": "Ashanti"
    }
  ]
}

通过 Webhook 接收包裹更新

POST /YOUR_WEBHOOK_URL

每当包裹发生追踪事件时，我们将向您的 Webhook URL 发送 POST 请求。

信封结构

每个 Webhook 载荷共享相同的顶层信封：

字段 类型 描述
event string 事件类型。参见下方 Webhook 事件。
event_id string 每次投递的唯一 UUID，用于幂等性/去重处理。
api_version string 载荷版本，例如 v1
occurred_at string 事件发生时的 ISO 8601 UTC 时间戳
data object 事件特定载荷，结构因 event 类型而异。

Webhook 事件

package.status_updated

每当包裹状态变更时触发。

字段 类型 描述
tracking_number string ShaQ Express 追踪号
partner_ref string 您的包裹参考编号
status string 新状态，参见 包裹状态 获取可用值
description string 状态的可读描述
comment string 附加说明或备注，可能为 null
meta object 额外数据，当 status 为 delivered 时包含 proof_url 
{
  "event": "package.status_updated",
  "event_id": "018e2b3c-7f4a-7c2d-9e1b-4a8f3d2c6b5a",
  "api_version": "v1",
  "occurred_at": "2025-05-29T10:30:00Z",
  "data": {
    "tracking_number": "20250410X51DIQ",
    "partner_ref": "FGVHKJ567",
    "status": "delivered",
    "description": "Package was successfully delivered to customer",
    "comment": null,
    "meta": {
      "proof_url": "https://example.com/proof.jpg"
    }
  }
}
package.amount_to_collect_updated

当包裹的应收金额被修改时触发，该修改始终由客户提出并获批。

字段 类型 描述
tracking_number string ShaQ Express 追踪号
partner_ref string 您的包裹参考编号
status string 修改时的包裹状态，参见 包裹状态 获取可用值
meta.old_amount_to_collect number 原应收金额
meta.new_amount_to_collect number 修改后的应收金额
meta.currency string 货币代码，例如 GHS
meta.reason string 修改原因 
{
  "event": "package.amount_to_collect_updated",
  "event_id": "039g4d5e-9h6c-9e4f-1g3d-6c0h5f4e8d7c",
  "api_version": "v1",
  "occurred_at": "2025-05-29T09:00:00Z",
  "data": {
    "tracking_number": "20250410X51DIQ",
    "partner_ref": "FGVHKJ567",
    "status": "received",
    "meta": {
      "old_amount_to_collect": 25.0,
      "new_amount_to_collect": 35.0,
      "currency": "GHS",
      "reason": "Items changed"
    }
  }
}

预期响应

您的端点必须返回 2xx 响应以确认收到 Webhook。任何非 2xx 响应将最多重试 3 次。

{
  "message": "",
  "data": {
    "status": "OK"
  }
}

Webhook 要求

为确保可靠投递并防止 Webhook 超时，请遵守以下准则：

*   **响应超时：** 您的服务器必须在收到载荷后 **10 秒内** 返回 `2xx` 状态码。
*   **异步处理：** 立即确认收到 Webhook，然后异步处理数据库操作、业务逻辑或外部通知（例如使用后台队列/工作进程）。
*   **去重与幂等性：** 使用载荷信封中提供的 `event_id` 确保幂等性。保存已处理事件 ID 的日志，若 ID 已处理则跳过。
*   **预防重复处理：** 您的端点必须能妥善处理重复投递，以应对网络重试或短暂连接问题。

创建包裹替换

POST /packages/replacement

说明： 创建一个或两个包裹以替换现有包裹。rule 字段决定需要几个包裹以及每个包裹须执行的 action。

请求头

参数 类型 描述
Authorization bearer 必填。

规则

规则 所需包裹数 所需操作
deliver 1 action = deliver
return 1 action = return
return_deliver 2 一个 return，一个 deliver

请求参数

参数 类型 描述
rule string 必填。 可选值之一：deliver、return、return_deliver
packages array 必填。 1–2 个包裹对象，须满足 rule 的约束条件

包裹对象

packages 数组中的每个元素须符合以下结构：

参数 类型 描述
action string 必填。 可选值之一：deliver、return，须与 rule 对应
partner_ref string 必填。 须唯一
customer_name string 必填
customer_phone_1 string 必填。 有效的手机号码
customer_phone_2 string 可选
source_country_iso2 string 必填。 有效的 ISO2 国家代码
source_address_line_1 string 必填
source_address_line_2 string 可选
destination_country_iso2 string 必填。 有效的 ISO2 国家代码
destination_region string 当 region_id 缺失时必填
destination_city string 必填
destination_address_line_1 string 必填
destination_address_line_2 string 可选
destination_postal_code string 可选
landmark string 可选
region_id integer 当 destination_region 缺失时必填
length decimal 可选
height decimal 可选
weight decimal 可选
description string 必填
units number 必填
type string 必填。 可选值之一：parcel、box
value decimal 必填。 最小值 0
amount_to_collect decimal 可选。 最小值 0
handling string 必填。 可选值之一：normal、fragile
payment_collector string 可选，可选值：shaq、partner（此参数仅在 ShaQ Express 为收款方时可发送。用于指定由谁负责向客户收取包裹款项，适用于合作伙伴负责收款的特殊情况。若未提供，将使用默认的收款方配置。）
items array 必填。 { name: string, quantity: number } 数组，可为空
special_instructions string 可选
latitude decimal 可选
longitude decimal 可选

响应

200

{
  "message": "Package replacement created successfully",
  "data": [
    {
      "partnerRef": "GH945214",
      "trackingNumber": "9F0FD9D5",
      "customerName": "Derrick Nti",
      "customerPhone1": "+233549632604",
      "customerPhone2": null,
      "sourceCountry": "Ghana",
      "sourceAddressLine1": "21 Abiriw Street",
      "sourceAddressLine2": null,
      "destinationCountry": "Ghana",
      "destinationRegion": "Greater Accra",
      "destinationCity": "Kwashieman",
      "destinationAddressLine1": "23 Abiriw Street",
      "destinationAddressLine2": null,
      "destinationPostalCode": null,
      "length": 30,
      "height": 20,
      "weight": 5.5,
      "description": "Test package",
      "labelUrl": null,
      "units": 1,
      "type": "box",
      "value": 20,
      "amountToCollect": 20,
      "paymentStatus": "unpaid",
      "handling": "normal",
      "specialInstructions": null,
      "status": "pending",
      "statusDescription": "Package is yet to be received by Partner",
      "latitude": null,
      "longitude": null,
      "receivedAt": null,
      "isReplacement": true,
      "action": "deliver",
      "items": [
        {
          "name": "Bluetooth",
          "quantity": 3
        }
      ],
      "rescheduledDate": null,
      "deliveredAt": null,
      "eta": null,
      "maxEta": null,
      "pickedAt": null,
      "packedAt": null,
      "cancelledAt": null,
      "trackingHistory": [
        {
          "name": "pending",
          "description": "Package is yet to be received by Partner",
          "date": "2026-05-04 12:16",
          "comment": null
        }
      ]
    },
    {
      "partnerRef": "GH545728",
      "trackingNumber": "A797CA0A",
      "customerName": "Kwabena Azaglo",
      "customerPhone1": "+233549632604",
      "customerPhone2": null,
      "sourceCountry": "Ghana",
      "sourceAddressLine1": "21 Abiriw Street",
      "sourceAddressLine2": null,
      "destinationCountry": "Ghana",
      "destinationRegion": "Greater Accra",
      "destinationCity": "Kwashieman",
      "destinationAddressLine1": "23 Abiriw Street",
      "destinationAddressLine2": null,
      "destinationPostalCode": null,
      "length": 30,
      "height": 20,
      "weight": 5.5,
      "description": "Test package",
      "labelUrl": null,
      "units": 1,
      "type": "box",
      "value": 20,
      "amountToCollect": 20,
      "paymentStatus": "unpaid",
      "handling": "normal",
      "specialInstructions": null,
      "status": "pending",
      "statusDescription": "Package is yet to be received by Partner",
      "latitude": null,
      "longitude": null,
      "receivedAt": null,
      "isReplacement": true,
      "action": "return",
      "items": [
        {
          "name": "Bluetooth",
          "quantity": 3
        }
      ],
      "rescheduledDate": null,
      "deliveredAt": null,
      "eta": null,
      "maxEta": null,
      "pickedAt": null,
      "packedAt": null,
      "cancelledAt": null,
      "trackingHistory": [
        {
          "name": "pending",
          "description": "Package is yet to be received by Partner",
          "date": "2026-05-04 12:16",
          "comment": null
        }
      ]
    }
  ]
}

获取包裹标签

GET /packages/{partnerRef}/print-label

获取特定包裹的标签

请求头

参数 类型 描述
Authorization bearer 必填。

响应

200

{
  "message": "Label ready",
  "data": {
    "url": "https://d167icvhk5jowg.cloudfront.net/labels/20250410X51DIQ.pdf"
  }
}

202

{
  "message": "Label generation started. Please retry shortly.",
  "data": null
}

404

{
  "message": "Package not found",
  "data": null
}