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)。

准入与鉴权

  1. 开放接口默认关闭。代理商在后台「开放接口」页点「申请开通」,管理员审核后开启;划拨能力需管理员单独放行。
  2. 开通后在同一页签发密钥:前缀 aawp_,勾选权限范围(scope),可选 IP 白名单与有效期。 明文在创建时显示,之后可在「开放接口」页点「查看」再次显示(每次查看记入审计)。我们用哈希做鉴权,另存一份加密副本,数据库里看不到原文。
  3. 每个请求带 Authorization: Bearer aawp_…。 密钥代表代理商本人:能看到名下全部客户(下级代理的客户只读、邮箱脱敏),写操作只对直属客户。
  4. 密钥可随时吊销 / 轮换(轮换时可给旧钥最多 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 为美元数值。

错误码

codeHTTP含义 / 处理
validation_error400参数不合法;message 说明哪个字段
idempotency_key_required400划拨缺 Idempotency-Key 头
unauthorized401密钥无效、已吊销或已过期
insufficient_balance402划拨时你的余额不足
transfer_in_flight409该客户已有入账中的划拨;请 POST /transfers/{id}/retry,勿再发新单
open_api_disabled403平台总闸关闭 / 你的账号未开通 / 划拨接口临时关闭
forbidden_scope403密钥没有这个权限范围,或划拨未被管理员放行
forbidden_ip403来源 IP 不在密钥白名单
direct_only403写操作只允许对直属客户进行(下级代理的客户只读)
funds_cap_exceeded403此密钥今日划拨累计已到上限;响应带 capUsd / usedUsd / remainingUsd
not_found404客户 / 密钥 / 记录不存在,或不在你的名下(不区分,防枚举)
email_taken409邮箱已注册;若在你名下会带 existingId
external_id_taken409externalId 已映射到你的另一位客户
idempotency_conflict409同一 Idempotency-Key 用于了不同的请求内容
provision_pending409影子账户尚未开通完成(建号后数秒内),稍后重试
rate_limited429超过密钥限流;看 Retry-After 与 X-RateLimit-* 头
engine_unavailable503计费引擎暂不可达;读接口可稍后重试,写接口不会半做
internal_error500我们的问题;带上 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(标准价);不传档时响应带 hintcustomers: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:revealkeys: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 会 403keys: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 再发新单会得 409 transfer_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。

首次接入建议顺序

  1. 后台「开放接口」页点申请开通;开通后先签一把只读钥(customers:read / keys:read / usage:read / billing:read),调 GET /me 自检:返回你的邮箱、余额、客户数与本钥权限即接通。
  2. 用自家系统已有客户跑通只读:GET /customers → 详情 → 用量 / 余额;把你系统的客户号写进 externalId(PATCH),之后全部接口可用 ext:<客户号> 代替数字 id。
  3. 需要写能力时另签一把带 customers:write / keys:write 的钥(建议配 IP 白名单与有效期),先建 1 个试点客户:拿到 initialPassword 交给客户登录网页验证,再代建 sk- 密钥交付。
  4. 划拨需管理员单独放行后才能签 funds:transfer 钥;建钥时把 dailyTransferCapUsd 设成你每日真实需要的额度,Idempotency-Key 用自家订单号,超时就原样重发。
  5. 上线后在「开放接口」页看调用统计(成功 / 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。

客户端接入(模型调用)见 接入文档;模型名与价格见 模型与价格。