Waybill API

Electronic waybill/label management endpoints.

Endpoints Overview

Endpoint	Method	Description
/api/v1/label/create	POST	Create electronic waybill
/api/v1/label/page	POST	Get waybill list
/api/v1/label/reorder	POST	Re-purchase waybill
/api/v1/label/renotify	POST	Manual notification
/api/v1/label/resync	POST	Re-sync label
/api/v1/label/update	POST	Update waybill info
/api/v1/label/price/estimate	POST	Price estimation
/api/v1/label/service/available	POST	Available services

---

Create Waybill

Create a new electronic waybill/label.

Request

Endpoint: POST /api/v1/label/create

Headers:

• Content-Type: application/json
• Authorization: appToken token}

Request Body:

{
  "request_id": "string",
  "sender": {
    "postal_code": "string",
    "country_code": "string",
    "province": "string",
    "city": "string",
    "suburb": "string",
    "address_1": "string",
    "address_2": "string"
  },
  "recipient": {
    "postal_code": "string",
    "country_code": "string",
    "province": "string",
    "city": "string",
    "suburb": "string",
    "address_1": "string",
    "address_2": "string"
  },
  "shipperId": "string",
  "weight_unit": "g",
  "size_unit": "cm",
  "pkg_weight": 1000,
  "pkg_volume": {
    "length": 30,
    "width": 20,
    "height": 10
  },
  "declare": [
    {
      "name": "Product Name",
      "quantity": 2,
      "unit_code": "pcs",
      "weight": 500,
      "price": {
        "amount": 25.00,
        "currency": "USD"
      },
      "hs_code": "123456",
      "origin_country_code": "CN"
    }
  ],
  "parcels": [
    {
      "parcel_number": 1,
      "weight": 1000,
      "width": 20,
      "height": 10,
      "length": 30
    }
  ],
  "additional_service": [
    {
      "service_code": "INSURANCE",
      "service_value": {
        "amount": 100.00,
        "currency": "USD"
      }
    }
  ]
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "ok": true,
    "errors": [],
    "dato": {
      "id": "waybill_id",
      "tracking_number": "123456789",
      "label": "https://...",
      "process": "preOrder"
    }
  }
}

---

Waybill List

Get paginated list of waybills.

Request

Endpoint: POST /api/v1/label/page

Request Body:

{
  "pageNumber": 1,
  "pageSize": 20,
  "process": "processing"
}

Response

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 100,
    "currPage": 1,
    "data": [...]
  }
}

---

Re-purchase Waybill

Re-purchase a failed waybill.

Request

Endpoint: POST /api/v1/label/reorder

{
  "id": "waybill_id"
}

---

Update Waybill

Update waybill information.

Request

Endpoint: POST /api/v1/label/update

{
  "id": "waybill_id",
  "label": "new_label_url",
  "tracking_number": "new_tracking_number",
  "weight": 1500,
  "width": 25,
  "height": 15,
  "length": 35
}

Available Update Fields:

• label
• tracking_number
• exchange_tracking_number
• confirm
• service_code
• exchange_label
• lifts
• tail_lift
• weight
• width
• height
• length
• tax_id
• delivery_datetime
• pickup_datetime

---

Manual Notification

Re-trigger webhook notification.

Request

Endpoint: POST /api/v1/label/renotify

{
  "id": "waybill_id"
}

---

Re-sync Label

Re-fetch label from carrier.

Request

Endpoint: POST /api/v1/label/resync

{
  "id": "waybill_id"
}

---

Webhook 通知

当面单状态变更时，系统自动推送通知到商户配置的 notifyUrl。

通知格式

{
  "cmd": "purchase",
  "dato": { ... }
}

通知类型

cmd	说明
purchase	面单采购完成
getLabel	面单获取完成
Update	订单字段更新
Errors	订单错误
exchangeHistory	交换历史新增
exchangeHistoryUpdate	交换历史面单更新

重触发通知

调用 POST /api/v1/label/renotify 可手动重新推送当前面单的通知。