# Ever API · 客户上手

三步跑通第一条调用。出错了每条响应里都带修复提示，看不懂再翻错误目录。

## 最省事：命令行 (一行安装 · 不用写代码)

把接口包成终端里能敲的命令：装上就能查库存、拉文档；`--json` 给脚本；AI 编程助手也直接用。

```bash
curl -fsSL https://connect.everugg.net.au/cli/install.sh | sh
ever login --sandbox
ever stock changes AU --since 0
```

写操作要加 --confirm，且永远只建草稿。

## 还没拿到凭证？先用沙箱试 (零门槛 · 假数据)

不用等授权，用公开的 sandbox 渠道就能跑通全流程——同样的端点、同样的响应形状，只是数据是演示的（DEMO-* 款），动不了真库存、下单只回假单号：

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/auth/token" -H "content-type: application/json" \
  -d '{"client_id":"sandbox","client_secret":"sandbox"}'
```

拿到 token 后照下面三步调即可。沙箱响应带 X-Sandbox: true 头。测通了，再找对接人要正式凭证打真数据。

## 0. 你手上要有两样东西 (找对接人发放)

渠道号（如 100944）和密钥（形如 ever_xxxxxxxx…）。

密钥只在发放那一刻显示一次，管理员那边也只存了它的哈希、看不到原文——所以务必自己存好。丢了找管理员「重发」（旧的立即失效）。

## 1. 用它们换 token

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/auth/token" -H "content-type: application/json" \
  -d '{"client_id":"<渠道号>","client_secret":"<密钥>"}'
```

返回 {"data":{"token":"eyJ…","token_type":"Bearer","expires_in":3600,"expires_at":"…"}}。token 就是后面调接口的钥匙，expires_in 是剩余秒数，过期了重新换一个即可。

## 2. 带上 token 调接口

放在 Authorization: Bearer 头里（接口不认 ?token= 查询串，口令和令牌都不进 URL）：

```bash
curl "https://connect.everugg.net.au/api/v1/warehouses" -H "Authorization: Bearer <你的token>"

curl "https://connect.everugg.net.au/api/v1/warehouses/AU/stock?sku=OB0021611" -H "Authorization: Bearer <你的token>"
```

能调哪些接口、看哪些仓，取决于管理员给你的授权。想知道自己当前的身份和权限：

```bash
curl "https://connect.everugg.net.au/whoami" -H "Authorization: Bearer <你的token>"
```

想用眼睛看（角色、能用哪些能力、Webhook、套餐）就去我的接入。

## 3. 出错了怎么办

每条错误响应里都有 error.code / message / hint / request_id / doc_url——先看 hint（怎么修），修不了把 request_id 发给对接人。

> 例：漏带 token → error.code=AUTH_MISSING_TOKEN，hint 告诉你先走第 1 步换 token。

## 4. 写接口请带幂等 key (防重复下单)

创建订单这类写请求，请带上 Idempotency-Key 头（每一笔业务一个唯一串，用 UUID 或你自己的订单号都行）：

```bash
curl -X POST "https://connect.everugg.net.au/api/v1/orders" -H "Authorization: Bearer <你的token>"   -H "content-type: application/json"   -H "Idempotency-Key: 8f14e45f-ea0d-4b2a-9c1b-000000000001"   -d '{"warehouse_code":"AU","lines":[{"sku":"OB0021611","quantity":1}]}'
```

超时了、网络抖了、不确定到底成没成——用同一个 key 重试就行，不会重复下单，会原样返回第一次的结果（响应带 Idempotency-Replayed: true）。切记别换 key，换了就真会下两单。

## 5. 别每次拉全量，用增量 (7.3MB → 几 KB)

全仓库存是 7.3MB / 3 万多行 / 8.5 秒。首次先拉一次全量，记下响应头里的 x-stock-version，之后只问「变了什么」：

```bash
curl "https://connect.everugg.net.au/api/v1/warehouses/AU/stock/changes?since=<42>" -H "Authorization: Bearer <你的token>"
```

返回 changes（added/updated/removed）和新的 version，拿新 version 当下次的 since。若返回 full: true，说明你离线太久、变更日志已经滚过去了——请重做一次全量。全量口还支持 ?page=1&pageSize=1000 分页（不传就还是一次性全回）。

## 把这套接口接给你的 AI

文档本身就是给 AI 读的形状：llms.txt 是目录，每一页都有 Markdown；你的 AI 助手（Claude、Cursor 等）用 MCP 直连，或者装 Ever CLI 自己敲命令。权限永远跟着你的 token 走。

## 接着看

- [接口参考（可在线试一下）](https://connect.everugg.net.au/reference.md?lang=zh)
- [错误码目录（怎么修）](https://connect.everugg.net.au/reference/errors.md?lang=zh)
- [命令行工具（CLI）](https://connect.everugg.net.au/cli?lang=zh)
- [llms.txt](https://connect.everugg.net.au/llms.txt?lang=zh)

---
Markdown 源: https://connect.everugg.net.au/start.md?lang=zh · 网页版: https://connect.everugg.net.au/start?lang=zh