上传 PDF 文件

通过本接口上传 PDF 文件，获取访问 URL，用于回填预报单的物流面单、装箱清单等 PDF 字段。

直邮贴标场景下，提交预报单需要附带物流面单（shipping_label）、装箱清单（shipping_note）两类 PDF。这些字段存的是可访问的 URL，因此需要先通过本接口把 PDF 上传到平台，再用返回的 URL 回填到提交预报单接口。产品标签（marketplace_label）由平台侧生成维护，无需上传推送。

接口说明

项	值
方法	`POST`
路径	`/open/v1/files/pdf`
Content-Type	`multipart/form-data`
鉴权	ApiKey 鉴权

请求

请求头

请求头	必填	说明
`X-Api-Key`	是	ApiKey，详见鉴权说明

表单字段

字段	类型	必填	说明
`file`	file	是	PDF 文件，单文件 ≤ 10MB，扩展名 `.pdf`

限制

文件类型：仅支持 PDF（按扩展名 + 文件内容魔数双重校验，改扩展名的非 PDF 文件会被拒绝，返回 42205）。
文件大小：单文件 ≤ 10MB，超限返回 42206。
去重：同一租户内内容相同的文件（MD5 一致）自动去重，直接返回已存记录（deduplicated=true），不会重复落盘。

请求示例

curl -X POST 'https://open.test.huixingguoji.com/open/v1/files/pdf' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -F 'file=@shipping_label.pdf'

响应

成功（HTTP 200）

{
  "code": "0",
  "message": "success",
  "data": {
    "url": "https://open.huixingguoji.com/storage/20260813/pdf_11_1786626240486_9387.pdf",
    "attachment_id": 362,
    "origin_name": "shipping_label.pdf",
    "size_byte": 209,
    "size_info": "209 B",
    "deduplicated": false
  }
}

字段	类型	说明
`url`	string	文件访问 URL，回填到预报单的 PDF 字段
`attachment_id`	integer	平台附件记录 ID
`origin_name`	string	上传时的原始文件名
`size_byte`	integer	文件大小（字节）
`size_info`	string	文件大小（人类可读，如 `1.50 MB`）
`deduplicated`	boolean	`true` 表示命中租户内去重，返回的是已存记录（未重复落盘）

url 由平台静态服务提供，可直接在浏览器打开，也可作为预报单 PDF 字段值提交。

失败

常见错误码（完整列表见错误码）：

错误码	含义	触发场景
`42204`	未上传文件	未携带 `file` 字段或 multipart 格式错误
`42205`	文件类型不允许	非 `.pdf` 扩展名，或文件内容非有效 PDF
`42206`	文件超出大小限制	单文件超过 10MB
`42207`	文件保存失败	服务端落盘异常，重试即可

使用流程

调用本接口上传 PDF，获取响应中的 data.url。
将 url 回填到提交预报单接口的 shipping_label / shipping_note 字段。
提交预报单。

# 1. 上传 PDF
curl -X POST '.../open/v1/files/pdf' -H 'X-Api-Key: YOUR_API_KEY' -F 'file=@label.pdf'
# → 拿到 data.url

# 2. 回填并提交预报单
curl -X POST '.../open/v1/forecasts' \
  -H 'Content-Type: application/json' \
  -H 'X-Api-Key: YOUR_API_KEY' \
  -d '{ "po_number": "180401699", "forecast_type": 2, "shipping_label": "<上一步的 url>", "items": [...] }'

上传 PDF 文件

On this page