适用场景
- 你的产品要在你的用户自己的应用账号里做事,又不想为每个应用分别开发 OAuth 应用、维护凭证库。
- 你想要一份统一的应用和动作目录,每个动作都带输入的 JSON Schema,而不是每个应用接一套 SDK。
- 你只想为执行成功的动作付费,并且和模型、数据 API 共用一个余额。
核心概念
接入流程
1
选定应用和动作
在目录里搜索应用,查看它的
authTypes 和 credentialFields,再查看动作的 inputSchema。浏览目录免费。见浏览应用和动作。2
3
执行动作
调用
POST /actions/run,带上动作 key、externalUserId 和符合 schema 的 input。见执行动作。准备
- 鉴权。 每个请求带
Authorization: Bearer $AISA_API_KEY,也可以用x-api-key: $AISA_API_KEY。AIsa Connect 只接受 API Key:MCP 或 CLI 登录得到的 OAuth access token 会被拒绝,返回401。创建、限额和轮换 key 见身份验证。 - 只在服务端调用。 从你的后端调用 AIsa Connect,不要把 API Key 放进浏览器或移动端应用。
- 可用性。 如果 AIsa Connect 的所有路径都返回
404和{"error":"api endpoint not found"},说明 AIsa Connect 在这个环境暂时不可用,请联系 developer@aisa.one。
终端用户ID
externalUserId 是终端用户在你的系统里的 ID,AIsa 用它区分你的不同终端用户。
- 格式: 1–250 个可打印 ASCII 字符,首尾不能有空格。建议用稳定、不含个人信息的 ID,例如
store_8812,不要用邮箱。 - 何时必填: 发起连接和执行动作时必填。查询连接列表时可选,用来过滤。
- 隔离: 连接归属于你的 AIsa 账户和某一个
externalUserId。A 用户执行动作时,AIsa 不会用 B 用户的连接。
浏览应用和动作
浏览目录免费。key、app、name、description、operationType(read、write 或 destructive)、requiredScopes、inputSchema 和 outputSchema。
应用的 authTypes 决定连接方式:
credentialFields 按连接方式列出凭证字段。每个字段有 key(请求里用的字段名)、label(可以直接作为表单标签)、required、secret(是否按密码输入框处理)。api_key 的第一个字段永远是 apiKey。某种连接方式不在 credentialFields 里,说明 AIsa 不掌握它的字段,提交后由应用自己校验。只支持 OAuth 的应用是 credentialFields: {}。
用凭证连接
Shopify、WooCommerce 等大多数电商应用用凭证连接。按应用credentialFields 里列出的字段,在你的界面里让终端用户填写,再放进 credentials 转交给 AIsa。apiKey 也可以单独写在顶层,等同于 credentials.apiKey。
- Shopify:
apiKey是店铺的 Admin API access token(shpat_…),shopDomain是店铺的 myshopify.com 域名,例如acme.myshopify.com;也接受同一店铺的 Shopify 后台 URL。 - WooCommerce:
storeUrl(https 店铺地址)、consumerKey、consumerSecret必填;wordpressUsername、wordpressApplicationPassword可选,部分 WordPress 接口需要。 - 只要一个 key 的应用(例如 OpenAI)只传
"apiKey": "..."即可。
凭证如何校验
- AIsa 先按应用的
credentialFields检查字段。 缺少必填字段、或者传了应用不接受的字段,返回400 invalid_request。param指出问题字段(apiKey或credentials),message列出这个应用接受的全部字段,例如credential shopDomain is required; the app takes apiKey, shopDomain (required)。这一步不会发给应用,也不会创建任何东西。 - 字段齐全后,应用校验凭证本身。 token 不对、店铺域名不是 myshopify.com 域名、WooCommerce 地址不是 https 等,返回
400 connect_failed。请让用户核对填写的内容。
apiKey只能传一次:放在顶层或credentials里,不能两处都有。完全不传凭证也是400 invalid_request。- 请求体里有多余字段,返回
400 invalid_request。 - 应用不在目录里返回
404 not_found。应用只支持 OAuth 时返回400 invalid_request,param是app,请改用托管授权连接。 - AIsa 不存储、不记录、也不回传你提交的凭证,错误信息里也不会出现凭证的值。
托管授权连接
oauth2 类应用的授权页由 AIsa 托管。为终端用户发起一次连接会话:
1
打开完整的 connectUrl
在终端用户的浏览器里打开完整的
connectUrl。# 后面是这次会话的密钥,不能截掉,也不要写进日志。会话 30 分钟后过期。2
用户在应用里授权
流程结束后,浏览器跳到
redirectUrl,并带上 ?connectSessionId=cs_...&connectionId=con_...;失败时再带 &error=<code>。redirectUrl 必须是 https,并且在你账户的跳转白名单里。要把 URL 前缀加进白名单,发给 developer@aisa.one 即可。不传 redirectUrl 时,用户会停在 AIsa 的结果页。3
在服务端轮询会话
以会话状态为准。每 2–3 秒查一次,直到 失败的会话多一个
state 是 completed、failed 或 expired:"error": {"code": "connect_denied", "message": "...", "isUserFixable": true}。state 有 created、authorizing、completed、failed 和 expired。
AIsa 会先向应用核实授权确实完成,再创建连接。跳转带回的参数不会被直接采信,所以你不需要把它们转发给 AIsa。如果用户回到托管页时应用还没记录授权完成,托管页会自动重查约 10 秒;如果用户没完成授权就返回,托管页会把他重新带回应用的授权页。
重新授权。 连接需要重新连接时,加上
connectionId=con_... 再发起一次会话,会在原连接上原地更新。
管理连接
查看和删除连接免费。"status": "disconnected";之后再查询返回 404 not_found。
一个 AIsa 账户默认最多有 100 个有效连接,这是你所有终端用户合计的数量。超出后发起连接返回
403 user_quota_exceeded。请删除不用的连接,或联系我们提高上限。
执行动作
- 用哪个连接。
connectionId可选。不传时,AIsa 使用该终端用户在这个应用下最新的active连接,响应会告诉你用的是哪个连接。 - 输入校验。
input会先按动作的inputSchema校验,再发给应用。不合格返回422 validation_failed,error.details.errors里逐条列出path和message。schema 里没有声明的字段一律拒绝。 - 不自动重试。 每次执行只发给应用一次,AIsa 不会替你重试。
- 执行 ID。 执行发出之后才出现的错误,
error.details.runId里带本次执行的 ID,联系我们时请附上。
计费
- 只有执行成功的动作收费,每次 USD 0.0003(300 micro-USD)。所有套餐同一价格,不叠加套餐倍率。
- 失败一律不收费,包括校验失败、没有连接、需要重新连接、被限流、应用报错和结果未知。
- 浏览目录、发起连接、查看和删除连接都免费。
- 每次执行的实际扣费在响应头
X-AISA-Customer-Cost-Micros-USD里,单位是 micro-USD(1 USD = 1,000,000 micro-USD)。 - 执行发出前,AIsa 会预留一次执行的费用。余额不足时返回
402,动作不会发出。
402 的响应体和其他错误不同:
code 是 insufficient_api_key_balance。充值或调整 key 的限额见计费与额度。
限流
按 API Key 限流:
超限时 AIsa 返回
429 rate_limited,并带 Retry-After 响应头。应用自己也可能限流,这时错误的 attribution 是 "upstream";应用给了等待时间时,会原样放在 Retry-After 和 error.details.retryAfterSeconds 里。被限流的请求不收费。
错误码
除了服务不可用时的404 和上面的 402,所有错误都是这个格式:
attribution 表示问题出在哪一方:user 是请求或终端用户的连接,upstream 是应用本身,aisa 是 AIsa。请按 code 处理,不要按 message 文案判断。
联系 developer@aisa.one 时,请附上大致的 UTC 时间、请求方法和路径、HTTP 状态、错误
code,有 runId 时一并附上。不要附带 API Key、终端用户的凭证或 connectUrl 里的密钥。
API 参考
路径都相对于https://api.aisa.one/apis/v1/connector。
相关文档
计费与额度
余额、充值和 key 消费限额如何运作。
身份验证
创建、限额、保存和轮换 API Key。