API 文档

wallmarkets API 可让您以编程方式管理送货、退货、产品和超市账户。所有端点都返回 JSON 格式，需要通过 API 密钥进行验证。

基本 URL

https://www.wallmarkets.store/api/v1

回复格式

每个响应都包含一个状态字段和一个数据有效载荷（或在失败时包含一个错误对象）。

{
  "status": "success",
  "data": { ... }
}

在授权标头中加入 API 密钥作为承载器令牌，对每个请求进行验证。

生成应用程序接口密钥

在账户设置 > API 密钥中创建密钥。每个密钥支持

• 瞄准镜: 限制对每个资源的访问（例如，交货：读取、退货：写入、产品：读取）
• 到期日: 可选择过期日期--过期密钥将被自动拒绝
• 旋转: 在不更改密钥 ID 的情况下，旋转密钥以获取新密码

验证标头

Authorization: Bearer YOUR_API_KEY

申请示例

curl -X GET \
  https://www.wallmarkets.store/api/v1/deliveries \
  -H 'Authorization: Bearer wm_live_abc123...'

费率限制可保护服务的稳定性。限额因计划而异：

各计划的限额

速率限制标头

每个响应都包括这些标头：

• X-RateLimit-Limit: 每小时最大请求数
• X-RateLimit-Remaining: 当前窗口中剩余的请求
• X-RateLimit-Reset: 窗口重置时的 UTC 时区秒数

所需范围： deliveries:read / deliveries:write

送货清单

返回已验证用户的分页交付列表。

# Query Parameters
?page=1&per_page=20&status=pending&date_from=2024-01-01&supermarket_id=5

获取快递

{
  "id": 123,
  "supermarket_name": "E-mart",
  "subchain_name": "Sukhbaatar Branch",
  "products": [
    {"product_id": 8, "name": "Product A", "quantity": 10, "unit_price": 5000},
    {"product_id": 15, "name": "Product B", "quantity": 5, "unit_price": 12000}
  ],
  "total_value": 110000,
  "delivery_date": "2024-10-15",
  "status": "completed",
  "created_at": "2024-10-01T10:30:00Z"
}

创建交付

{
  "supermarket_id": 5,
  "subchain_id": 12,
  "products": [
    {"product_id": 8, "quantity": 10},
    {"product_id": 15, "quantity": 5}
  ],
  "delivery_date": "2024-10-20",
  "notes": "Urgent delivery"
}

更新交付状态

{
  "status": "completed"
}

有效转换：待处理 → 正在处理 → 已完成，或待处理 → 已取消。

所需范围： returns:read / returns:write

列表返回

返回分页列表。按配送、超市、原因或日期范围进行筛选。

# Query Parameters
?page=1&per_page=20&reason=damaged&delivery_id=123

创建返回

{
  "delivery_id": 123,
  "product_id": 8,
  "quantity": 3,
  "reason": "damaged",
  "return_date": "2024-10-18",
  "description": "Products arrived damaged during transit"
}

获取回报

{
  "id": 42,
  "delivery_id": 123,
  "product_id": 8,
  "product_name": "Product A",
  "quantity": 3,
  "reason": "damaged",
  "description": "Products arrived damaged during transit",
  "return_date": "2024-10-18",
  "credit_amount": 15000,
  "created_at": "2024-10-18T09:15:00Z"
}

所需范围： products:read / products:write

产品列表

返回已验证用户的所有产品。按类别筛选或按名称搜索。

# Query Parameters
?page=1&per_page=50&category=Dairy&search=milk

获取产品

{
  "id": 8,
  "sequential_id": "P-0008",
  "name": "Whole Milk 1L",
  "weight": 1.05,
  "price": 5000,
  "category": "Dairy",
  "created_at": "2024-08-01T12:00:00Z"
}

创建产品

{
  "name": "Whole Milk 1L",
  "weight": 1.05,
  "price": 5000,
  "category": "Dairy"
}

会自动分配一个唯一的序列 ID。

更新产品

{
  "price": 5500
}

只有您包含的字段会被更新。历史交货记录不受影响。

所需范围： supermarkets:read / supermarkets:write

超市名单

[
  {
    "id": 5,
    "name": "E-mart",
    "branches": [
      {"id": 12, "name": "Sukhbaatar Branch", "address": "..."},
      {"id": 13, "name": "Bayangol Branch", "address": "..."}
    ]
  }
]

获取超市

返回超市详细信息，包括所有分店、送货窗口和联系信息。

创建超市

{
  "name": "E-mart",
  "contact_email": "buyer@emart.mn",
  "branches": [
    {
      "name": "Sukhbaatar Branch",
      "address": "Peace Avenue 15, UB",
      "delivery_window": "08:00-12:00"
    }
  ]
}

订阅 Webhooks 可在事件发生时接收实时 HTTP 回调。网络钩子会在连续 10 次发送失败后自动停用。

活动类型

Webhook 有效负载示例

{
  "event": "delivery.completed",
  "timestamp": "2024-10-15T14:30:00Z",
  "data": {
    "delivery_id": 123,
    "supermarket_name": "E-mart",
    "subchain_name": "Sukhbaatar Branch",
    "total_value": 110000,
    "completed_at": "2024-10-15T14:30:00Z"
  }
}

重试政策

失败的交付会以指数级延迟（1 分钟、5 分钟、30 分钟）重试。连续 10 次失败后，订阅将自动停用。请在 webhook 设置中重新启用。

HTTP 状态代码

错误响应格式

{
  "status": "error",
  "error": {
    "code": "validation_error",
    "message": "delivery_date must be in the future",
    "field": "delivery_date"
  }
}