快速开始｜Orion

本指南展示 Orion Public API 的最小业务接入路径。所有 ID、公司名称和金额均为合成示例。

准备 API Key

在真实 Sandbox 上线后，从开发者控制台创建只包含以下 scope 的 Key：

crm.customers:read
erp.sales-orders:write

把 Key 放入服务端 Secret Manager。示例只使用 shell 环境变量，不要把它提交到仓库：

export ORION_API_KEY="replace-with-a-sandbox-key"

读取客户

curl 'https://sandbox-api.orion.example/v1/crm/customers?limit=20' \
  -H "Authorization: Bearer $ORION_API_KEY"

响应只包含当前凭证有权访问的数据范围：

{
  "items": [
    {
      "id": "cus_01JQ6A8MZ3Y1",
      "code": "C-2026-0088",
      "name": "上海晨星贸易有限公司",
      "status": "active",
      "owner_id": "usr_01JQ6A5T82N4",
      "updated_at": "2026-08-01T08:30:00Z"
    }
  ],
  "next_cursor": null,
  "request_id": "req_01JQ6AB45MY9"
}

创建销售订单草稿

创建请求必须带 Idempotency-Key。网络重试时复用同一个值，避免重复创建单据。

curl -X POST https://sandbox-api.orion.example/v1/erp/sales-orders \
  -H "Authorization: Bearer $ORION_API_KEY" \
  -H "Idempotency-Key: 8b4e42c1-c36f-47cf-9686-83a9cfb6c546" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id":"cus_01JQ6A8MZ3Y1",
    "warehouse_id":"wh_01JQ6AKT0R22",
    "currency":"CNY",
    "lines":[{"sku":"SKU-ALPHA-01","quantity":"12","unit_price":"199.00"}]
  }'

金额与数量使用十进制字符串。不要用 JavaScript 浮点数重新计算财务或订单合计。

处理失败

HTTP	稳定 code	建议动作
`400` / `422`	`validation_failed`	修正请求，不自动重试
`401`	`authentication_failed`	检查 Key 是否缺失、失效或被撤销
`403`	`permission_denied`	核对模块、scope 与资源数据范围
`409`	`idempotency_conflict`	核对幂等键是否被不同请求复用
`429`	`rate_limited`	尊重 `Retry-After`，做有上限的退避
`5xx`	`internal_error`	记录 `request_id`，对幂等请求做有限重试

下一步阅读身份验证，把示例凭证处理方式升级为可上线方案。

快速开始

准备 API Key

读取客户

创建销售订单草稿

处理失败

On this page