Symax VMS 商城开放 API v1

概览

所有开放接口使用 /api/v1/*。旧 open_* 路由不再提供兼容。

基础地址

将 https://shop.example.com 替换成商城绑定域名。例如：https://shop.example.com/api/v1/goods

响应格式

{
  "code": 0,
  "goods": { "id": 1001, "status": 0 }
}

code = 0 表示成功；失败时 code = 1，并返回 msg。认证、权限、参数和资源错误同时使用相应 HTTP 状态码。

认证签名

每个请求必须带以下 HTTP Header：

待签名字符串必须严格使用以下五段内容和换行符：

UPPERCASE_METHOD + "\n" +
PATH_WITH_RAW_QUERY + "\n" +
TIMESTAMP + "\n" +
NONCE + "\n" +
RAW_REQUEST_BODY

PHP 签名示例

$method = 'GET';
$path = '/api/v1/orders?updated_since=1780000000&limit=20';
$timestamp = (string) time();
$nonce = bin2hex(random_bytes(16));
$body = '';
$secret = '在后台保存的 Secret';

$string = strtoupper($method) . "\n" . $path . "\n" . $timestamp . "\n" . $nonce . "\n" . $body;
$signature = hash_hmac('sha256', $string, $secret);

$headers = [
    'X-Shop-Key: ' . $apiKey,
    'X-Shop-Timestamp: ' . $timestamp,
    'X-Shop-Nonce: ' . $nonce,
    'X-Shop-Signature: ' . $signature,
];

权限范围

接口目录

调用示例

创建商品草稿

POST /api/v1/goods
{
  "goods_no": "ERP-10001",
  "channel_id": 3,
  "cate_id": 12,
  "name": "示例商品",
  "currency": "USD",
  "price": 19.90,
  "market_price": 29.90,
  "stock": 100,
  "thumb": "/webdata/shop/images/example.jpg",
  "images": ["/webdata/shop/images/example.jpg"],
  "sku": { "specs": [], "rows": [], "single": { "sn": "ERP-10001" } },
  "goods_type": 1,
  "shipping_template": "default"
}

创建后返回的 status 为 0。完成资料校验后，再以独立权限调用上架接口。

上架商品

POST /api/v1/goods/1001/publish
{}

更新 SKU 库存

PUT /api/v1/inventory
{
  "goods_id": 1001,
  "sku_key": "Red|M",
  "stock": 36
}

回传物流

POST /api/v1/orders/ORD202608090001/ship
{
  "track_company": "DHL",
  "track_no": "JD014600006281234567"
}

远程图片导入

商品接口不会同步下载外部图片。先创建导入任务，等待任务完成后再把返回的媒体 ID 写入商品；这样商品不会因下载超时而写入半成品。

1. 创建导入任务

POST /api/v1/media
{
  "url": "https://cdn.example.com/products/10001/main.jpg",
  "channel_id": 3
}

需要 media.write 权限。一次最多提交 20 个 URL，也可以使用 urls 数组批量提交。

2. 查询任务

GET /api/v1/media/mi_xxxxxxxxxxxxxxxxxxxxxxxx

任务状态为 completed 时，响应中的 media_id 和 local_url 才可使用。pending、processing、retrying 时应继续轮询；failed 时检查 error_code 后修正 URL。

3. 引用本地媒体

PATCH /api/v1/goods/1001
{
  "thumb_media_id": "med_...",
  "image_media_ids": ["med_...", "med_..."]
}

媒体必须处于完成状态且属于同一频道。系统会将媒体 ID 转为本地地址后保存到商品，不会在商品中保留远程 URL。

Webhook

在商城后台为全局或频道配置 Webhook 地址和订阅事件。投递为 JSON POST，Header 包含 X-Shop-Event、X-Shop-Event-Id、X-Shop-Timestamp 和 X-Shop-Signature。

签名字符串为 timestamp + "\n" + raw_body，使用 Webhook Secret 计算 HMAC-SHA256。接收方应使用 event_id 去重。

排错说明