跳到正文

公共 API:认证、错误和限流

如何发送密钥、如何读取错误,以及每个密钥每分钟允许多少次请求。

地址和文档

所有路径都以 /api/v1/public/v1/ 开头,地址和你的 ERP 相同。完整文档(OpenAPI,含示例)在 /api/v1/public/docs,文件在 /api/v1/public/openapi.json。在 API 与开发者 页面有 API 文档 按钮。

认证

每次请求都用请求头 Authorization: Bearer bzk_你的密钥 发送密钥。店铺由密钥决定,不需要另外指定。用 GET /api/v1/public/v1/me 测试密钥,它返回店铺、密钥的权限和限流。

错误

错误以 JSON 返回,含 statusCode、errorCode 和 message。请始终按 errorCode 判断(文字是西班牙语,可能会变):

  • API_KEY_INVALID、API_KEY_REVOKED、API_KEY_EXPIRED(401):密钥无效。
  • API_KEY_IP_NOT_ALLOWED(403):请求来自不在密钥允许列表里的 IP。
  • API_SCOPE_MISSING(403):密钥缺少该路径需要的权限。
  • API_PERMISSION_MISSING(403)或 API_KEY_OWNER_UNAVAILABLE(401):创建密钥的人已没有该权限,或已无法进入本店。
  • MODULE_SUBSCRIPTION_REQUIRED 或 MODULE_DISABLED(403):API 服务或该资源的模块在本店未开通。
  • API_NOT_FOUND(404):本店中不存在。

限流

每个密钥每分钟 120 次请求。所有响应都带 X-RateLimit-Limit、X-RateLimit-Remaining 和 X-RateLimit-Reset(距这一分钟结束的秒数)。超过限制会收到 429 API_RATE_LIMITED,并带 Retry-After 请求头:等待相应秒数后再重试。

返回帮助中心