# 创建 SCAN Form

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

Endpoint: POST /api/scan_form/create_scan_form
Version: v2
Security: BearerAuth

## Request fields (application/json):

  - `address_data` (object, required)
    打印在 SCAN Form 上的发货（寄件）地址。company_name 与 first_name + last_name 两者中至少要提供一项。

  - `address_data.company_name` (string)
    公司/商户名称。若未提供 first_name/last_name，则此项必填。
    Example: "ShipSaving"

  - `address_data.first_name` (string)
    联系人名字。若未提供 company_name，则此项与 last_name 一起必填。
    Example: "Alice"

  - `address_data.last_name` (string)
    联系人姓氏。若未提供 company_name，则此项与 first_name 一起必填。
    Example: "Green"

  - `address_data.phone` (string)
    联系电话。可选，但建议提供，以便承运商在需要时联系。
    Example: "1234567890"

  - `address_data.email` (string)
    联系邮箱。可选。
    Example: "it@shipsaving.com"

  - `address_data.street` (string, required)
    建筑物门牌号及其所在的道路或街道名称。
    Example: "xxxx Olive Street"

  - `address_data.street2` (string)
    地址的次级单元标识，例如公寓号（APT）或套房号（STE），用于明确建筑物内的具体位置。
    Example: "STE XXX"

  - `address_data.city` (string, required)
    地址所属的城市名称。
    Example: "Los Angeles"

  - `address_data.state` (string, required)
    - 对于美国地址，该字段必须为有效的两位州代码（例如“CA”表示加利福尼亚州，“NY”表示纽约州）。
- 对于非美国地址，该字段的取值不作限制。
    Example: "CA"

  - `address_data.zip_code` (string, required)
    地址对应的邮政编码。
    Example: "021XX"

  - `address_data.country` (string, required)
    国家两位字母代码。该字段的值应为[ISO 3166-1 two-digit code](https://en.wikipedia.org/wiki/ISO_3166-1)两位国家代码。
    Example: "US"

  - `tracking_nos` (array, required)
    要加入 SCAN Form 的已购买运单的 tracking number。每个运单都必须属于 USPS， 且处于已购买、尚未发货的状态；同一运单只能出现在一个 SCAN Form 中。
    Example: ["9234690381085700XXXXX"]

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

## Response 200 fields (application/json):

  - `code` (string)
    结果码。ok 表示成功；其他任何值表示业务错误，此时 data 为 null。
    Example: "ok"

  - `msg` (string)
    可读的结果信息。
    Example: "ok"

  - `data` (object)
    响应负载；当 code 不为 ok 时为 null。

  - `data.scan_form_image` (string)
    生成的 SCAN Form PDF 的 URL。
    Example: "https://xxxxx/forms/2026-07-16/92XXXXXXXXX00000010794.pdf"