公共 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 请求头:等待相应秒数后再重试。