创建 SCAN Form

API参考

/SCAN Form/

创建 SCAN Form

请求

为一组已购买的运单创建 USPS SCAN Form（PS Form 5630），并返回生成的清单 PDF 的 URL。SCAN Form 是一张把多个运单合并到一起的清单条码，承运商在揽收时扫描这一张即可一次性接收整批运单。

安全

BearerAuth

正文application/json必需

address_dataobject(ScanFormAddress)必需

打印在 SCAN Form 上的发货（寄件）地址。company_name 与 first_name + last_name 两者中至少要提供一项。

tracking_nosArray of strings, non-empty必需

要加入 SCAN Form 的已购买运单的 tracking number。每个运单都必须属于 USPS，且处于已购买、尚未发货的状态；同一运单只能出现在一个 SCAN Form 中。

ship_datestring, (date)

邮寄日期——即关联 SCAN Form 中的包裹被交到收寄点（entry facility）的日期。采用 ISO 8601 full-date 格式的日历日期（YYYY-MM-DD），不含时间与时区。可选；不传时默认为当天。

示例:"2026-07-21"

POST

/api/scan_form/create_scan_form

curl -i -X POST \
  https://x-api.shipsaving.com/api/scan_form/create_scan_form \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "address_data": {
      "company_name": "ShipSaving",
      "first_name": "Alice",
      "last_name": "Green",
      "phone": "1234567890",
      "email": "it@shipsaving.com",
      "street": "xxxx Olive Street",
      "street2": "STE XXX",
      "city": "Los Angeles",
      "state": "CA",
      "zip_code": "021XX",
      "country": "US"
    },
    "tracking_nos": [
      "9234690381085700XXXXX"
    ],
    "ship_date": "2026-07-21"
  }'

响应

成功

正文application/json

codestring

结果码。ok 表示成功；其他任何值表示业务错误，此时 data 为 null。

示例:"ok"

msgstring

可读的结果信息。

示例:"ok"

dataobject(ScanFormCreateResponse)

响应负载；当 code 不为 ok 时为 null。

Response

{
  "code": "ok",
  "msg": "ok",
  "data": {
    "scan_form_image": "https://xxxxx/forms/2026-07-16/92XXXXXXXXX00000010794.pdf"
  }
}