如何通过 API 将自定义商店接入 easySales

什么时候需要这么做

easySales 为常见的商店平台提供现成的连接器。如果你用的是自定义的东西——自研的店铺，或者我们还没有做集成的平台——你可以自己通过 API 把它接进来。

这是一项开发工作。你要写代码把自己的商品目录推送到 easySales 并把订单送过来，而 easySales 会在有变化时回调你的店铺。这里的任何一步都不需要安装插件。

连接是怎么运作的

这里涉及两个凭据，把它们弄混是第一次集成返回 403 最常见的原因。

每一次写入都需要两个。访问令牌证明是谁在调用；网站令牌说明数据属于哪家店铺。

第 1 步 — 添加网站

进入整合方式 → 网站，点击连结网站，填写表单，然后选择 API 图块以及它下面的 API V2 版本。

第 2 步 — 复制网站令牌

向导的配置步骤会显示一个 60 个字符的令牌。旧文章从未提到过它，而每一次写入调用都需要它。

用按钮复制，不要手动重打，并把它作为机密保存在你的应用里。点击保存创建网站。

店铺现在会出现在整合方式 → 网站下，卡片上带着同一个令牌——以后就到那里再找它。

第 3 步 — 创建 OAuth 客户端

进入设定值 → API设置。OAuth 凭据就在这里。

点击创建新客户，按将要发起调用的系统给它命名，并把授权类型设为 Website Grant。

Website Grant 正是为这件事而设计的：它用你的网站令牌换取访问令牌，不需要浏览器跳转，也不需要用户操作。保存后复制出现的客户 ID 和密钥。

第 4 步 — 获取访问令牌

POST https://easy-sales.com/oauth/token
Content-Type: application/json

{
  "grant_type":    "website",
  "client_id":     "your-client-id",
  "client_secret": "your-client-secret",
  "website_token": "your-60-character-website-token",
  "scope":         "add-products update-products update-stock add-orders update-orders read-orders"
}

返回的是标准的 OAuth 响应体：

{
  "token_type":    "Bearer",
  "expires_in":    31536000,
  "access_token":  "eyJ0eXAiOiJKV1Qi...",
  "refresh_token": "def50200a1b2c3..."
}

在之后的每一次调用中，把它作为 Authorization: Bearer <access_token> 发送。

第 5 步 — 推送你的商品目录

下面所有请求的基础地址是 https://easy-sales.com/api/v2。

顺序很重要。 类别和特性必须先存在，产品才能引用它们，否则产品调用会被拒绝。

1. POST /categories/save — 你的类别
2. POST /characteristics/save — 你的属性
3. POST /products/save — 你的产品

POST https://easy-sales.com/api/v2/products/save
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "website_token": "your-60-character-website-token",
  "product": {
    "product_website_id": "10231",
    "sku": "TS-BLK-M",
    "name": "Black T-shirt, size M",
    "sale_price": 79.99,
    "full_price": 99.99,
    "stock": 24,
    "type": "simple",
    "tax_rate": 21,
    "url": "https://my-shop.example.com/p/ts-blk-m",
    "images": ["https://my-shop.example.com/img/ts-blk-m.jpg"],
    "categories": ["cat-778"],
    "characteristics": [{ "id": "char-12", "value": "Black" }]
  }
}

第 6 步 — 保持库存同步

库存是必须保持最新的那一项，而且它是最适合频繁调用的低成本接口。每次最多发送 100 行：

PATCH https://easy-sales.com/api/v2/stocks/bulk
Authorization: Bearer <access_token>

{
  "website_token": "your-60-character-website-token",
  "data": [
    { "sku": "TS-BLK-M", "stock": 24 },
    { "sku": "TS-BLK-L", "stock": 0 }
  ]
}

每个 SKU 都必须已经存在于这个网站上；未知的会被拒绝，而不会被创建。

第 7 步 — 把订单送进来

POST https://easy-sales.com/api/v2/orders/save
Authorization: Bearer <access_token>

{
  "website_token": "your-60-character-website-token",
  "order": {
    "order_id": "SO-100244",
    "order_date": "2026-09-09 14:31:00",
    "order_total": 179.98,
    "status": "new",
    "payment_mode": "card",
    "shipment_tax": 21,
    "billing_address":  { "country": "RO", "city": "Cluj-Napoca", "street": "Str. Memorandumului 4" },
    "shipping_address": { "country": "RO", "city": "Cluj-Napoca", "street": "Str. Memorandumului 4" },
    "order_products": [
      { "product_website_id": "10231", "sku": "TS-BLK-M", "name": "Black T-shirt, size M",
        "quantity": 2, "price": 79.99, "total": 159.98 }
    ]
  }
}

再次提交相同的 order_id，订单会被更新而不是重复创建，这让重试是安全的。

第 8 步 — 把变化取回去

你的店铺需要知道订单何时开了发票、生成了运单或改变了状态。订阅一个 webhook，而不是轮询：

GET https://easy-sales.com/api/v2/webhooks
Authorization: Bearer <access_token>

POST https://easy-sales.com/api/v2/webhooks/order-updated
Authorization: Bearer <access_token>

{
  "url":    "https://my-shop.example.com/hooks/easysales",
  "secret": "a-shared-secret-of-at-least-24-characters"
}

每次只能订阅一个事件，因此需要对 order-created、order-updated、awb-created、invoice-created 和 delivery-status-updated 分别调用一次。

每一次推送都有签名，所以在信任内容之前先校验签名。要快速响应——请求会在几秒后超时，并且只会重试有限的次数，所以先确认接收，再去处理。

限制

出错的时候

在我们这边失败的内容也会进入产品 → 网上商店 → 网站错误，附带请求内容和一个重试操作，这通常比重新复现调用更快。

参考文档

完整的接口参考，包含每个字段和每种响应，发布在 https://api.easy-sales.com。