Skip to main content
Fluz 在每个环境中都只暴露一个 GraphQL 端点。不存在按功能划分的基础 URL:你将查询或修改操作发送到 /api/v1/graphql,由令牌决定你正在操作的是谁的账户。

端点

访问令牌通过 generateUserAccessToken 修改操作在同一端点生成,并使用你的 API 密钥进行授权,参见身份验证。

请求剖析

  • query:GraphQL 文档本身。使用具名操作(query GetSpendAccount)可以获得更清晰的日志。
  • variables:类型化的输入参数,让取值不必写进查询字符串中。
  • operationName:可选字段,在一份文档定义了多个操作时很有用。

查询与修改操作

  • 查询 为只读操作(viewer、wallet、transactions)。
  • 修改操作 会更改状态(createVirtualCard、purchaseGiftCard、depositCashBalance、createTransfer)。
涉及资金变动的修改操作会使用请求去重机制,参见幂等性。

响应格式

成功执行的查询会返回 HTTP 200,并带有 data / errors 结构,即使发生应用层错误时也是如此:
失败时,data 可能为 null,errors 会描述具体出错原因,其中包含可供分支判断的机器可读 code 字段。参见错误。 如果变量的值与其声明的类型不匹配,同样会返回 200,并带有 BAD_USER_INPUT。而在执行前就被拒绝的请求会返回不同的状态码,例如限流器返回的 429,或查询超出查询成本限制时返回的 400。

内省与 Schema

预发布环境中启用了内省功能,因此你可以将 Apollo Studio、GraphiQL 等工具指向该端点。生产环境中内省功能已禁用,请改用API 参考中发布的 Schema。

后续步骤

身份验证

Authorization 请求头中的令牌是如何生成的,无论是你自己账户的令牌,还是客户账户的令牌。

错误

errors 数组中包含哪些内容,以及如何根据错误代码进行分支处理。