示例
您的系统和客服的常见任务——每个一两条命令。地址和令牌放在变量里,与“调用”页面相同。
创建客户
一个月、三台设备,外部 ID 用订单号。重试键用订单号:重复的请求会得到同样的响应,而不会多出一位客户。
在您的服务器上curl -s "$VELI/clients" \ -H "Authorization: Bearer $VELI_TOKEN" \ -H "content-type: application/json" \ -H "Idempotency-Key: order-88123:new" \ -d '{"name": "order-88123", "days": 30, "change": {"devices": 3, "external": "88123", "tags": ["month"], "meta": {"order": "88123"}}}'续期一个月
期限加到结束时间之后,已过期的从现在算起。带上重试键,重复的请求不会续期两次。
在您的服务器上curl -s "$VELI/clients/order-88123" \ -H "Authorization: Bearer $VELI_TOKEN" \ -H "content-type: application/json" \ -H "Idempotency-Key: order-88123:extend" \ -d '{"change": {"days": 30}}'链接、二维码和应用按钮
链接在 link 中,带按钮的页面在 page 中,现成的“添加到 …”链接在 apps 中,剩余量在 left 中。用于聊天或邮件的二维码用 PNG。
在您的服务器上curl -s "$VELI/clients/order-88123" \ -H "Authorization: Bearer $VELI_TOKEN" | jq -r .link curl -s "$VELI/clients/order-88123/qr?format=png&size=512" \ -H "Authorization: Bearer $VELI_TOKEN" -o qr.png curl -s "$VELI/clients/order-88123" \ -H "Authorization: Bearer $VELI_TOKEN" | jq '{page, apps, left}'按外部 ID 查找客户
一个人可能有多份订阅——响应总是列表。
在您的服务器上curl -s "$VELI/clients?external=88123" \ -H "Authorization: Bearer $VELI_TOKEN" | jq -r '.clients[] | "\(.name) \(.status) \(.left.days)"'
重复也无副作用
外部系统会重复发送通知,用户会点两次,服务器会在请求和响应之间崩溃。POST 上的 Idempotency-Key 请求头让重复变得安全。
- 同一个键、同一个请求——同样的响应,不会执行第二次,并带有 Idempotent-Replayed: true 请求头。
- 同一个键、不同的请求——409 idempotency:这个键已经用在别的请求上了。
- 面板记住键一天,每个令牌的键相互独立。键最多 128 个可见字符;方便的做法是订单号加操作:order-88123:extend。
- 一个键只对应一个操作:续期和创建使用不同的键,否则第二个请求会得到第一个请求的响应。
用同一个键重试
HTTP/1.1 200 OK
idempotent-replayed: true
{"done": 1}