Open API

开放接口 API 文档

将外部系统订单与面单写入 GlobalPod。订单同步与表格导入/平台拉单一致，面单导入与后台「导入面单」一致。调用前请先在会员中心申请 API Key。

1. 获取与使用 API Key

登录商户后台，进入 会员中心 → 开放接口。
选择订单默认归属的店铺，点击「申请 API Key」。
复制并妥善保存密钥。重置后旧密钥立即失效。

仅主账号可申请、重置或禁用。子账号请联系主账号开通。

请求约定

项	说明
Base URL	`https://seller.globalpod.cn`
Content-Type	订单接口用 `application/json`；导入面单用 `multipart/form-data`
认证 Header	`Token: {API_KEY}` 或 `X-Access-Token: {API_KEY}`
请求体	原始 JSON，不要使用 form-data

2. 同步订单

将一笔外部订单写入系统，处理逻辑与「导入订单」表格、平台订单同步一致：按产品 ID + SKU 自动关联成品。关联成功进入「待下单」，未关联进入「待设计」。

项	说明
Method / Path	`POST /user/order/OrderImport/syncOrder`
成功后状态	SKU 已关联：待下单（status = 2）；未关联：待设计（status = 1）

请求示例

curl -X POST 'https://seller.globalpod.cn/user/order/OrderImport/syncOrder' \
  -H 'Content-Type: application/json' \
  -H 'Token: gp_your_api_key' \
  -d '{
  "order_no": "EXT-20260308-0001",
  "plat_id": 1,
  "shop_id": 1001,
  "plat_time": "2026-03-08 10:00:00",
  "plat_pay_time": "2026-03-08 10:05:00",
  "receive_country_code": "US",
  "receive_country_zh": "美国",
  "receive_name": "John Smith",
  "receive_mobile": "13800000000",
  "receive_province": "California",
  "receive_city": "Los Angeles",
  "receive_county": "",
  "receive_zipcode": "90001",
  "receive_address": "123 Main St",
  "user_note": "请尽快生产",
  "express_number": "",
  "express_company_id": 1,
  "orderDetail": [
    {
      "goods_id": "10001",
      "sku": "TS-BLK-L",
      "title": "定制T恤",
      "colour": "黑色",
      "model": "L",
      "buy_number": 2,
      "unit_price": "19.99",
      "image": "https://example.com/product.jpg"
    }
  ]
}'

成功响应

{
  "code": 200,
  "msg": "订单导入成功",
  "data": {
    "order_id": "1234567890",
    "order_no": "EXT-20260308-0001"
  }
}

3. 查询订单

按平台订单号查询当前 API Key 所属主账号下的订单。

项	说明
Method / Path	`POST /user/order/OrderImport/queryOrder`

请求示例

curl -X POST 'https://seller.globalpod.cn/user/order/OrderImport/queryOrder' \
  -H 'Content-Type: application/json' \
  -H 'Token: gp_your_api_key' \
  -d '{
  "order_no": "EXT-20260308-0001"
}'

成功响应

{
  "code": 200,
  "msg": "订单查询成功",
  "data": {
    "id": "1234567890",
    "order_no": "EXT-20260308-0001",
    "master_id": 100001,
    "user_id": 100001,
    "status": 2,
    "pay_status": 0,
    "createtime": 1772935200,
    "paytime": 0,
    "init_goods_total_price": "0.00",
    "goods_price": "39.98"
  }
}

3. 导入面单

与后台「导入面单」确认写入一致：上传 PDF 后写入订单运单号，并在仓库表保存面单文件。一次导入一笔订单。

项	说明
Method / Path	`POST /user/order/OrderImport/syncLabel`
Content-Type	`multipart/form-data`
写入结果	订单 `express_number`、`express_status=2`（获取完成）；仓库新增面单 PDF

参数

字段	类型	必填	说明
order_no	string	是	系统中已存在的订单号
file	file	二选一	面单文件，支持 PDF / JPG / PNG，与后台上传相同
pdf_url	string	二选一	可公网访问的面单地址，服务端下载后按同样逻辑处理
express_number	string	否	运单号。不传时：先从文件名 `订单号--运单号.pdf` 解析，再尝试识别 PDF 文本/OCR

订单必须属于当前 API Key 主账号，且不能是已发货状态。运单号识别规则与后台导入面单相同。

请求示例（上传文件）

curl -X POST 'https://seller.globalpod.cn/user/order/OrderImport/syncLabel' \
  -H 'Token: gp_your_api_key' \
  -F 'order_no=EXT-20260308-0001' \
  -F 'express_number=9214490407314870844148' \
  -F 'file=@/path/to/label.pdf'

请求示例（远程 PDF）

curl -X POST 'https://seller.globalpod.cn/user/order/OrderImport/syncLabel' \
  -H 'Token: gp_your_api_key' \
  -F 'order_no=EXT-20260308-0001' \
  -F 'pdf_url=https://example.com/label.pdf'

成功响应

{
  "code": 200,
  "msg": "面单导入成功",
  "data": {
    "order_id": "1234567890",
    "order_no": "EXT-20260308-0001",
    "express_number": "9214490407314870844148",
    "pdf_url": "/uploads/express/20260308/xxxx.pdf"
  }
}

4. 参数说明

字段与订单表格导入、平台订单同步一致，无需传设计配置。

4.1 订单主信息（syncOrder）

字段	类型	必填	说明
order_no	string	是	外部订单号，系统内不可重复
orderDetail	array	是	订单明细，至少 1 条
shop_id	int	否	覆盖 API Key 绑定店铺，须属于同一主账号
plat_id	int	否	销售平台，缺省为 1（系统订单）。常见值见下表
plat_time	string	否	平台下单时间，如 `2026-03-08 10:00:00`
plat_pay_time	string	否	平台支付时间
receive_country_code	string	否	收件国家简码，如 US
receive_country_zh	string	否	收件国家中文名
receive_name	string	否	收货人姓名
receive_mobile	string	否	联系电话
receive_province	string	否	省 / 州
receive_city	string	否	市
receive_county	string	否	区 / 县
receive_zipcode	string/int	否	邮政编码
receive_address	string	否	详细地址
user_note	string	否	订单备注
express_number	string	否	运单号
express_company	string	否	物流名称，对应表格导入的「物流名称」
express_company_id	int	否	物流公司 ID，缺省为 1
receive_country	string	否	国家中文名 / 英文名 / 简码，用于匹配国家库

4.2 订单明细 orderDetail[]

与表格导入列对应：产品ID、产品SKU、产品名称、颜色、尺码、数量、图片链接、单价。

字段	类型	必填	对应表格列	说明
goods_id	string/int	是	产品ID	平台/外部产品 ID，用于 SKU 关联
sku	string	是	产品SKU	平台/外部 SKU
title	string	是	产品名称	产品名称
colour	string	是	颜色	颜色；也可传 plat_colour
model	string	是	尺码	尺码；也可传 plat_model
buy_number	int	否	数量	数量，缺省 1
image	string	否	图片链接	产品图 URL，也可传 product_img_url
unit_price	string/number	否	单价	平台单价
skc	string	否	—	SKC
plat_colour	string	否	颜色	平台侧颜色，未传 colour 时必填
plat_model	string	否	尺码	平台侧尺码，未传 model 时必填

系统会用 goods_id + sku 匹配已关联成品。匹配成功则自动带出颜色、尺码、价格；未匹配则订单进入待设计，可在后台手工关联。

4.3 查询参数（queryOrder）

字段	类型	必填	说明
order_no	string	是	同步时使用的外部订单号

4.4 平台 plat_id

ID	平台	ID	平台
1	系统订单	13	Joom
2	Etsy	14	Shein 全托管
3	亚马逊	15	Shein 半托管
5	速卖通	16	Shopee 托管
6	速卖通托管	17	TikTok
7	Temu	18	TikTok 全托管
8	Shopify	19	乐天
9	Wish	20	美客多
10	Shopee	21	Ozon
12	1688	22	店匠

4.5 图片说明

image 为可访问的图片 URL 即可，系统按原地址保存，与表格导入「图片链接」相同。
不需要传生产稿、设计配置或图库 ID。

5. 错误码与注意事项

code	含义
200	成功
400	参数错误、订单已存在、订单不存在、已发货、未识别运单号等
401	缺少 Token、Token 无效、API Key 已禁用或未绑定店铺
500	保存失败等系统错误

常见失败原因

order_no 已存在，不可重复导入。
明细缺少产品 ID、SKU、名称、颜色或尺码。
SKU 未预先关联时订单仍会写入，状态为待设计，需在后台完成关联后再下单。
导入面单时订单不存在、已发货，或未提供/未识别运单号。

同步成功后请到「全部订单」确认明细与地址。已关联的可直接下单，未关联的请先完成成品关联。