跳转到主要内容
AIsa Connect 让你的终端用户(例如你服务的商家)把自己的 Shopify、WooCommerce、GitHub、Google 等应用账号连接到 AIsa。之后你只用一个 AIsa API Key,就能浏览应用目录,并代表这些用户执行应用动作:查订单、改商品、列仓库等。终端用户的令牌和密钥由 AIsa 的应用集成保管,你的系统不用存,也读不到。 所有 AIsa 账户都可以直接使用 AIsa Connect,用的就是你现有的 API Key 和余额,不需要单独开通。

适用场景

  • 你的产品要在你的用户自己的应用账号里做事,又不想为每个应用分别开发 OAuth 应用、维护凭证库。
  • 你想要一份统一的应用和动作目录,每个动作都带输入的 JSON Schema,而不是每个应用接一套 SDK。
  • 你只想为执行成功的动作付费,并且和模型、数据 API 共用一个余额。
如果只是读取不需要用户账号的公开数据(例如电商平台商品),请用数据 API。要用一种请求格式覆盖多个社媒和广告平台,见 Unified API。

核心概念

接入流程

1

选定应用和动作

在目录里搜索应用,查看它的 authTypes 和 credentialFields,再查看动作的 inputSchema。浏览目录免费。见浏览应用和动作。
2

连接终端用户的账号

api_key 和 custom_credential 类应用:在你的界面里收集字段,转交给 AIsa。oauth2 类应用:把用户带到 AIsa 托管授权页,再轮询会话。见用凭证连接和托管授权连接。
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 用户的连接。
GET /connections/{connectionId} 和 DELETE /connections/{connectionId} 只校验连接属于你的 AIsa 账户,不校验终端用户。请在你的后端保存“连接属于哪个终端用户”的对应关系,不要让终端用户自己传入任意连接 ID。

浏览应用和动作

浏览目录免费。
动作的字段有 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": "..." 即可。
连接成功后返回新建的连接:

凭证如何校验

  1. AIsa 先按应用的 credentialFields 检查字段。 缺少必填字段、或者传了应用不接受的字段,返回 400 invalid_request。param 指出问题字段(apiKey 或 credentials),message 列出这个应用接受的全部字段,例如 credential shopDomain is required; the app takes apiKey, shopDomain (required)。这一步不会发给应用,也不会创建任何东西。
  2. 字段齐全后,应用校验凭证本身。 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,联系我们时请附上。
谨慎对待 write 和 destructive 动作。执行前先看 operationType,会修改终端用户数据的动作要先和用户确认。写操作遇到 app_error 或 outcome_unknown 时,改动可能已经生效:先到应用里确认结果,再决定要不要重试,避免重复写入。

计费

  • 只有执行成功的动作收费,每次 USD 0.0003(300 micro-USD)。所有套餐同一价格,不叠加套餐倍率。
  • 失败一律不收费,包括校验失败、没有连接、需要重新连接、被限流、应用报错和结果未知。
  • 浏览目录、发起连接、查看和删除连接都免费。
  • 每次执行的实际扣费在响应头 X-AISA-Customer-Cost-Micros-USD 里,单位是 micro-USD(1 USD = 1,000,000 micro-USD)。
  • 执行发出前,AIsa 会预留一次执行的费用。余额不足时返回 402,动作不会发出。
402 的响应体和其他错误不同:
如果 API Key 设置了消费限额并且已经用完,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。