指南
快速开始
读取一个客户，并幂等创建销售订单草稿。
本指南展示 Viseq Public API 的最小业务接入路径。所有 ID、公司名称和金额均为合成示例。
准备 API Key
在真实 Sandbox 上线后，从开发者控制台创建只包含以下 scope 的 Key：
crm.customers:readerp.sales-orders:write
把 Key 放入服务端 Secret Manager。示例只使用 shell 环境变量，不要把它提交到仓库：
export VISEQ_PUBLIC_API_KEY="replace-with-a-sandbox-key"读取客户
curl 'https://sandbox-api.viseq.example/v1/crm/customers?limit=20' \
-H "Authorization: Bearer $VISEQ_PUBLIC_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.viseq.example/v1/erp/sales-orders \
-H "Authorization: Bearer $VISEQ_PUBLIC_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，对幂等请求做有限重试 |
下一步阅读身份验证，把示例凭证处理方式升级为可上线方案。