身份验证
API 密钥身份验证与速率限制
身份验证
所有发往 Umbrella API 的请求都需要身份验证。根据端点的不同，共有两种验证方式。
Shopify 请求头身份验证
面向公开的端点（小组件数据、索赔、保单查询）使用 Shopify 店铺域名请求头进行身份验证：
X-Shopify-Shop-Domain: your-store.myshopify.com
X-Shopify-Customer-Id: 1234567890安装 Umbrella Shopify 应用时，您的店铺域名会自动完成注册。店面端点无需任何手动设置。
内部 API 密钥身份验证
服务器端端点（适用条件评估、商品同步）通过请求体中的 API 密钥进行身份验证：
{
"internalApiKey": "your-internal-api-key",
"orgId": "your-org-id"
}
注意 内部 API 密钥仅用于服务器之间的通信。切勿在客户端代码中暴露它们。
要生成或轮换内部 API 密钥：
- 前往 仪表板 > 设置 > 集成
- 找到“API 密钥”部分
- 点击 生成新密钥 或 轮换密钥
轮换密钥会立即使旧密钥失效。请在轮换之前更新所有集成。
测试环境与正式环境
| 环境 | 店铺域名 | 行为 |
|---|---|---|
| 测试 | *.test、demo.myshopify.com、test.myshopify.com | 返回模拟数据，不产生真实交易 |
| 正式 | 您实际的 *.myshopify.com 域名 | 真实数据，真实交易 |
测试模式的请求会在响应中返回 "testingMode": true，并使用示例保修数据。
错误处理
所有端点通用的常见错误状态码：
| 状态码 | 含义 |
|---|---|
400 | 缺少参数或参数无效 |
401 | 未提供身份验证凭据 |
403 | 来源未经授权或 API 密钥无效 |
404 | 未找到资源 |
408 | 请求超时（25 秒限制） |
429 | 超出速率限制 — 请等待后重试 |
500 | 服务器内部错误 |
收到 429 响应时，请等待重试间隔结束后再发送更多请求。在高流量场景中，请实现指数退避。
相关内容
- 端点概览 — 可用端点的完整列表
- 保修 API — 保修计划管理端点
- Webhook 参考 — 事件驱动的集成
