开发者文档开始使用
认证
API 密钥、权限范围和 IP 白名单。
在每个 /v1 请求中，以 Bearer 令牌的形式发送 API 密钥。
curl https://runner.cargoduo.com/v1/balance \
-H "Authorization: Bearer $CARGODUO_API_KEY"API 密钥
| 项目 | 说明 |
|---|---|
| 格式 | cd_live_ + 40 个字符 |
| 创建者 | 组织所有者，在开发者控制台中创建 |
| 显示 | 仅在创建时显示一次。系统只保存其哈希值 |
| 每个组织 | 最多 20 个有效密钥 |
| 可选设置 | 过期日期、IP 白名单（IP 或 CIDR 网段） |
| 重置 | 生成新密钥，保留原有设置。旧密钥立即失效 |
请将密钥保存在服务器上，切勿放入浏览器端或移动应用中。
权限范围
| 权限范围 | 接口 |
|---|---|
pack:write | POST /v1/pack, POST /v1/estimate, DELETE /v1/jobs/{id}, POST /v1/projects/{id}/pack |
jobs:read | GET /v1/jobs, GET /v1/jobs/{id}, GET /v1/jobs/{id}/result |
account:read | GET /v1/limits, GET /v1/balance, GET /v1/usage |
resources:read | GET /v1/projects, GET /v1/projects/{id}, GET /v1/vehicles, GET /v1/vehicles/{id}, GET /v1/templates, GET /v1/templates/{id} |
resources:write | POST /v1/projects, PATCH /v1/projects/{id}, DELETE /v1/projects/{id}, POST /v1/projects/{id}/pack, POST /v1/vehicles, PATCH /v1/vehicles/{id}, DELETE /v1/vehicles/{id}, POST /v1/templates, PATCH /v1/templates/{id}, DELETE /v1/templates/{id} |
新密钥默认拥有全部权限范围。POST /v1/projects/{id}/pack 同时需要 pack:write 和 resources:write。
错误
| 状态码 | 错误码 | 含义 |
|---|---|---|
| 401 | unauthorized | API 密钥缺失、格式错误或无法识别。 |
| 401 | key_revoked | 密钥已被撤销。 |
| 401 | key_expired | 密钥已过期。 |
| 403 | ip_not_allowed | 调用方 IP 不在该密钥的 IP 白名单中。 |
| 403 | subscription_inactive | 组织没有包含 API 的有效订阅。 |
| 403 | account_inactive | 组织已被暂停使用，或其所有者的账户均未处于有效状态。 |
| 403 | scope_missing | 密钥缺少此接口所需的权限范围。 |
| 429 | rate_limited | 当前分钟、小时或天内的请求过多（按密钥或按组织计），或您的 IP 地址每分钟认证失败超过 60 次。 |