跳到主要内容

API 参考

Socolode REST API 让你通过编程方式管理商品、订单、客户和店铺设置。

认证​

所有 API 请求需要访问令牌。在设置 > API 中生成。

Authorization: Bearer sk_your_access_token

请妥善保管令牌，切勿暴露在客户端代码或公开仓库中。

基础地址​

https://api.socolode.com/v1

频率限制​

每个店铺每个访问令牌限 每分钟 100 次请求。每个响应包含频率限制头：

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1721692800

超限时返回 429 Too Many Requests。

商品​

获取商品列表​

GET /v1/products?page=1&limit=50

响应：

{
  "data": [
    {
      "id": "prd_abc123",
      "title": "Classic Sneakers",
      "price": 59.99,
      "currency": "USD",
      "status": "active",
      "inventory": 120,
      "created_at": "2026-01-15T08:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 320,
    "total_pages": 7
  }
}

创建商品​

POST /v1/products
Content-Type: application/json

{
  "title": "Classic Sneakers",
  "price": 59.99,
  "currency": "USD",
  "sku": "SNK-001",
  "inventory": 100,
  "category": "footwear",
  "tags": ["new", "summer"]
}

更新商品​

PATCH /v1/products/prd_abc123
Content-Type: application/json

{
  "price": 49.99,
  "inventory": 80
}

删除商品​

DELETE /v1/products/prd_abc123

订单​

获取订单列表​

GET /v1/orders?status=paid&page=1&limit=50

获取单个订单​

GET /v1/orders/ord_xyz789

发货​

POST /v1/orders/ord_xyz789/fulfillments
Content-Type: application/json

{
  "tracking_number": "1Z999AA10123456784",
  "carrier": "ups",
  "notify_customer": true
}

Webhook​

在设置 > API > Webhook 中注册回调地址，接收实时事件通知。

事件触发条件
order.created新订单创建
order.paid支付完成
order.fulfilled订单已发货
product.updated商品已修改
inventory.low库存低于阈值

Webhook 以 POST 请求发送 JSON 数据。使用 X-Socolode-Signature 头验证签名，其中包含以你的 Webhook 密钥对请求体计算的 HMAC-SHA256 哈希。

错误响应​

所有错误遵循统一格式：

{
  "error": {
    "code": "not_found",
    "message": "Product not found",
    "request_id": "req_abc123"
  }
}
HTTP 状态码代码说明
400bad_request参数错误
401unauthorized令牌缺失或无效
404not_found资源不存在
422validation_error数据校验失败
429rate_limited超出频率限制
500server_error服务器内部错误