PARTNER OPEN API
代理商开放接口:用程序管理你名下的客户
有自己 CRM / 计费系统的代理商,可以不经网页后台,直接用 HTTP 接口给客户建号、代管 sk- 密钥、查用量与账单、划拨额度, 把 AI API Way 嵌进自己的交付流程里。接口基址https://aiapiway.com/api/open/v1, 机器可读描述见 GET /api/open/v1/openapi.json(OpenAPI 3.1,可直接生成 SDK)。
准入与鉴权
- 开放接口默认关闭。代理商在后台「开放接口」页点「申请开通」,管理员审核后开启;划拨能力需管理员单独放行。
- 开通后在同一页签发密钥:前缀
aawp_,勾选权限范围(scope),可选 IP 白名单与有效期。 明文在创建时显示,之后可在「开放接口」页点「查看」再次显示(每次查看记入审计)。我们用哈希做鉴权,另存一份加密副本,数据库里看不到原文。 - 每个请求带
Authorization: Bearer aawp_…。 密钥代表代理商本人:能看到名下全部客户(下级代理的客户只读、邮箱脱敏),写操作只对直属客户。 - 密钥可随时吊销 / 轮换(轮换时可给旧钥最多 60 分钟宽限,便于无缝切换)。每代理最多 10 把有效密钥。
| scope | 能做什么 |
|---|---|
| customers:read | 客户列表 / 详情 / 个人信息 |
| customers:write | 建号、改显示名 / 备注 / 外部编号、换折扣档、自充开关 |
| customers:password高危 | 代直属客户设置登录密码(高危,单列) |
| keys:read | 密钥列表(脱敏)、按密钥统计、可选线路 |
| keys:write | 建 / 改限额 / 启停 / 删密钥(名称创建时定下,之后不能改;创建响应含完整 sk-) |
| keys:reveal高危 | 之后反复取回完整 sk-(每次调用都记审计) |
| usage:read | 用量汇总 / 明细 / 导出 / 代理级汇总 |
| billing:read | 余额 / 流水 / 订单 / 划拨记录 |
| funds:transfer高危 | 给直属客户划拨额度(需管理员为代理单独放行 + 日累计上限) |
约定:信封、客户标识、分页、幂等、限流
- 信封:成功
{ ok: true, data, meta? },失败{ ok: false, code, message }。code是稳定机器码(下表),message是给人看的中文,可能会改。每个响应带X-AAW-Request-Id,排障时报给我们。 - 客户标识
{id}三种写法:数字 id;ext:<externalId>(你在建号 / PATCH 时写入的自家客户号);me(代理自己——自己的密钥 / 用量 / 余额走同一组接口)。 - 分页:列表类用页码
?page=1&pageSize=20(meta 带 total);逐笔明细用游标——首页不传,之后把上一页data.nextCursor原样传回,直到为 null。游标按 (时间, id) 单调,翻页不重复、不漏行。 - 幂等:划拨必须带
Idempotency-Key(1–64 位,建议用你系统的订单号)。同键同体 24 小时内原样重放(响应头X-AAW-Idempotent-Replay: true),同键不同体 409。网络超时后原样重发即可,不会重复扣款。 - 限流(每密钥每分钟,标准档;高配档 ×3,由管理员调整):读本地 600、写 60、问计费引擎 120。 读本地 = 客户列表、折扣档、密钥统计、用量、订单、划拨记录。写 = 建号、改密、划拨、补入账。 问引擎 =
/me、客户详情与修改、密钥的增删改查和回显、可选线路、余额、流水(所以自检/me的上限是 120,不是 600)。 超限 429,看Retry-After与X-RateLimit-Remaining。 余额接口有 10 秒缓存,不要秒级轮询。 - 时间与金额:时间 ISO 8601 UTC;用量按 UTC 日切;金额字段
usd为美元数值。
错误码
| code | HTTP | 含义 / 处理 |
|---|---|---|
| validation_error | 400 | 参数不合法;message 说明哪个字段 |
| idempotency_key_required | 400 | 划拨缺 Idempotency-Key 头 |
| unauthorized | 401 | 密钥无效、已吊销或已过期 |
| insufficient_balance | 402 | 划拨时你的余额不足 |
| transfer_in_flight | 409 | 该客户已有入账中的划拨;请 POST /transfers/{id}/retry,勿再发新单 |
| open_api_disabled | 403 | 平台总闸关闭 / 你的账号未开通 / 划拨接口临时关闭 |
| forbidden_scope | 403 | 密钥没有这个权限范围,或划拨未被管理员放行 |
| forbidden_ip | 403 | 来源 IP 不在密钥白名单 |
| direct_only | 403 | 写操作只允许对直属客户进行(下级代理的客户只读) |
| funds_cap_exceeded | 403 | 此密钥今日划拨累计已到上限;响应带 capUsd / usedUsd / remainingUsd |
| not_found | 404 | 客户 / 密钥 / 记录不存在,或不在你的名下(不区分,防枚举) |
| email_taken | 409 | 邮箱已注册;若在你名下会带 existingId |
| external_id_taken | 409 | externalId 已映射到你的另一位客户 |
| idempotency_conflict | 409 | 同一 Idempotency-Key 用于了不同的请求内容 |
| provision_pending | 409 | 影子账户尚未开通完成(建号后数秒内),稍后重试 |
| rate_limited | 429 | 超过密钥限流;看 Retry-After 与 X-RateLimit-* 头 |
| engine_unavailable | 503 | 计费引擎暂不可达;读接口可稍后重试,写接口不会半做 |
| internal_error | 500 | 我们的问题;带上 X-AAW-Request-Id 联系我们 |
接口总览
字段级定义以 openapi.json 为准。{id} 为客户标识,{keyId} 为客户 sk- 密钥 id。
| 接口 | 作用 | scope |
|---|---|---|
| 自身 | ||
| GET/me | 代理自己的资料、余额、客户数、本密钥权限与限流档 | — |
| 客户 | ||
| GET/discount-profiles | 可给客户选的折扣档。isPurchase=true 的是你的进货档;代充要把进货价传给客户时用它 | customers:read |
| GET/customers | 客户列表。默认只含直属;下级代理的客户要加 ?scope=subtree,那些邮箱会脱敏。?withBalance=1 才附带余额 | customers:read |
| POST/customers | 建号:无需邀请码。password 可选;allowSelfRecharge 缺省 false。discountProfileKey 缺省 default(标准价);不传档时响应带 hint | customers:write |
| GET/customers/{id} | 详情(资料 / 折扣档 / 自充开关 / 开通状态) | customers:read |
| PATCH/customers/{id} | 改显示名 / 备注 / externalId / 折扣档 / 自充开关 | customers:write |
| POST/customers/{id}/password | 代直属客户设置登录密码(客户网页旧登录态即刻失效) | customers:password |
| 客户的 sk- 密钥 | ||
| GET/customers/{id}/key-groups | 该客户可选的线路分组 | keys:read |
| GET/customers/{id}/keys | 密钥列表(脱敏) | keys:read |
| POST/customers/{id}/keys | 建钥。这一次响应里带完整 sk-。之后要再看,走 /secret,且本钥要有 keys:reveal | keys:write |
| GET/customers/{id}/keys/stats | 按密钥的消耗 / 请求统计 | keys:read |
| PATCH/customers/{id}/keys/{keyId} | 改启用、总额度、文件夹、备注。不能改名称 | keys:write |
| DELETE/customers/{id}/keys/{keyId} | 删密钥 | keys:write |
| GET/customers/{id}/keys/{keyId}/secret | 再次取出完整 sk-。可以反复调用,每次记审计。本钥没有 keys:reveal 会 403 | keys:reveal |
| 用量 | ||
| GET/customers/{id}/usage/summary | 逐日 / 按型号 / 今日 / 区间合计 + lifetime 累计总消耗与总请求 | usage:read |
| GET/customers/{id}/usage/events | 逐笔明细,游标分页(≤ 90 日) | usage:read |
| GET/customers/{id}/usage/export.csv | 明细 CSV 导出(≤ 90 日、20,000 行) | usage:read |
| GET/usage/summary | 代理级:区间内有消耗的直属客户逐个消耗 / 请求 + 合计(对账单用);customersTotal 为直属总数,零用量客户不在列表 | usage:read |
| 账务 | ||
| GET/customers/{id}/balance | 余额(10 秒缓存) | billing:read |
| GET/customers/{id}/ledger | 账户流水(60 秒缓存) | billing:read |
| GET/customers/{id}/orders | 订单(Stripe / 线下) | billing:read |
| GET/transfers | 我发起的划拨记录 | billing:read |
| 划拨 | ||
| POST/transfers | 给直属客户划拨额度(Idempotency-Key 必填;201 done / 202 pending) | funds:transfer |
| POST/transfers/{id}/retry | 补第二腿(客户入账);不重复扣款 | funds:transfer |
数据口径
- 用量来自计费引擎日志,每 5 分钟同步一次;响应里
syncedThrough是已同步到的时刻。 接口不合并引擎实时行(为了翻页可重现),网页用量页会多出「近 1 小时实时补洞」,两者在同步到位后一致。 - 逐笔明细保留 90 天;按日汇总长期保留——所以
usage/summary可查一年,usage/events/ CSV 最多 90 天。 lifetime= 该客户全期累计总消耗 / 总请求;range= 查询区间合计。金额按客户实际折扣档计。- 划拨 1:1 入客户账户,先扣你、后加客户。极少数情况下第二步没完成会返回 202
status=pending, 此时只调 retry 补入账,不要重新发起;若该客户已有 pending 再发新单会得 409transfer_in_flight。 引擎侧以兑换码名天然幂等,重复 retry 不会重复入账;平台也会自动补入账。每把密钥有日累计划拨上限(默认 $2,000,可在建钥时调低、管理员可调高)。 - 建号响应里通常已是
provisionState=ok(计费账户同步开通);极少数情况下为 pending,数秒后再调即可,期间调余额 / 密钥接口会得到 409 provision_pending。建号不扣你的费。allowSelfRecharge缺省 false:客户不能在网站自己充值,额度靠你划拨。要让客户自己充值,建号或 PATCH 时把它设为 true。 新客户余额按美元显示为 0。 - 折扣档与代理利润:充值、划拨都是面值 1:1,划拨这一步不产生差价。 客户之后调用模型时,按客户所在折扣档扣余额;客户档高于你进货档的部分,系统按每笔消耗记为价差结算给你 (代充 / 客户自充同一规则,退款冲回;在代理商后台「价差结算」查看)。 建号不传
discountProfileKey= 标准价(有价差);要让客户直接按你的进货价扣,建号或 PATCH 时传GET /discount-profiles里isPurchase: true的那一档(价差为 0,利润放在你的现金售价里)。 - 代理级
/usage/summary:customersTotal是直属客户总数,customers[]只列区间内有消耗的客户(条数 =customersActive);要拿全部客户名单请用GET /customers。
首次接入建议顺序
- 后台「开放接口」页点申请开通;开通后先签一把只读钥(customers:read / keys:read / usage:read / billing:read),调
GET /me自检:返回你的邮箱、余额、客户数与本钥权限即接通。 - 用自家系统已有客户跑通只读:
GET /customers→ 详情 → 用量 / 余额;把你系统的客户号写进externalId(PATCH),之后全部接口可用ext:<客户号>代替数字 id。 - 需要写能力时另签一把带 customers:write / keys:write 的钥(建议配 IP 白名单与有效期),先建 1 个试点客户:拿到
initialPassword交给客户登录网页验证,再代建 sk- 密钥交付。 - 划拨需管理员单独放行后才能签 funds:transfer 钥;建钥时把
dailyTransferCapUsd设成你每日真实需要的额度,Idempotency-Key用自家订单号,超时就原样重发。 - 上线后在「开放接口」页看调用统计(成功 / 4xx / 5xx / 限流)与密钥状态;收到 5xx 时带
X-AAW-Request-Id联系我们。
示例:建号 → 代建密钥 → 查用量 → 划拨
# 1) 建客户账号(无需邀请码;password 省略则系统生成并只在这次响应里返回 initialPassword)
# discountProfileKey: 代充要把进货价传给客户时传 GET /discount-profiles 里 isPurchase=true 的 key;不传 = 标准价
curl -s https://aiapiway.com/api/open/v1/customers \
-H "Authorization: Bearer aawp_xxx" -H "Content-Type: application/json" \
-d '{"email":"[email protected]","externalId":"crm-10086","displayName":"Alice","discountProfileKey":"agent"}'
# 2) 代客户建一把 sk- 密钥(这一次响应里带完整明文)
# 之后要再取: GET /customers/ext:crm-10086/keys/<keyId>/secret
# 前提是这把 aawp_ 勾了 keys:reveal,每次调用都记审计
curl -s https://aiapiway.com/api/open/v1/customers/ext:crm-10086/keys \
-H "Authorization: Bearer aawp_xxx" -H "Content-Type: application/json" \
-d '{"name":"prod","group":"default"}'
# 3) 查该客户用量汇总(缺省近 30 日,可传 from / to,UTC 日)/ 翻逐笔明细(游标分页)
curl -s "https://aiapiway.com/api/open/v1/customers/ext:crm-10086/usage/summary" -H "Authorization: Bearer aawp_xxx"
curl -s "https://aiapiway.com/api/open/v1/customers/ext:crm-10086/usage/events?pageSize=100" -H "Authorization: Bearer aawp_xxx"
# 4) 划拨 $20(Idempotency-Key 必填,用你系统的订单号;重复发送只会扣一次)
curl -s https://aiapiway.com/api/open/v1/transfers \
-H "Authorization: Bearer aawp_xxx" -H "Content-Type: application/json" \
-H "Idempotency-Key: order-2026-000123" \
-d '{"customerId":"ext:crm-10086","usd":20,"note":"首充"}'
本期没有的接口
- 缓存健康:先不做。用量明细里的 cache token 数字仍然有,那是账单的一部分,不是缓存诊断。
- Webhook:我们不会在「开通完成 / 划拨到账 / 客户付款」时主动通知你的服务器。需要的话自己定时查询。
- 代开收银台:不能替客户生成一条付款链接。客户要自己充值,先把
allowSelfRecharge设为 true,让他登录网站充值。 - 停用客户:不能把某个客户的账号关掉、同时把人和账留下。现在也不能删除客户。要让他暂时调不了模型,删掉或停用他的
sk-。 - 近 1 小时实时用量:用量接口读的是已经入库的账,最多大约晚 5 分钟(看
syncedThrough)。 网页用量页会额外补「这一个客户近约 1 小时、还没入库」的记录;接口不补,避免翻页重复或漏行。这里的 1 小时是路径里那一个客户(me就是你自己),不是全站用量。
安全守则
- aawp_ 密钥只能放在你的服务端(环境变量 / 密钥管理服务),不要写进前端、移动端或提交到代码仓库。我们会监控「同一密钥来源 IP 数异常多」并告警,这是前端泄露的典型信号。
- 按最小权限签钥:日常对账只给
*:read;划拨、改密、回显密钥单独签一把、配 IP 白名单与有效期。 - 客户的
sk-有两段:创建那一次响应里给出完整明文,请立刻交给客户或放进你的服务端。 之后如果这把aawp_勾了keys:reveal,可以再调GET /customers/{id}/keys/{keyId}/secret取回同一串明文,每次调用都记入审计。没这个权限就只能看到脱敏预览。 - 代客户改密意味着你能接管其账号:仅限直属客户、单列 scope、全程审计、高频触发会提醒平台管理员。客户随时可在网页「账户设置」自行改回。
- 所有写操作在平台审计日志留痕(含你的密钥 id)。有疑问联系我们时请带上
X-AAW-Request-Id。