Skip to main content
Fluz 在每个环境中仅暴露一个 GraphQL 端点。没有按能力划分的基础 URL——你向 /api/v1/graphql 发送查询或变更,请求使用的令牌将决定你在操作哪个账户。

端点

访问令牌通过在相同端点使用 generateUserAccessToken 变更生成,并使用你的 API Key 授权——参见 Authentication

请求结构

  • query — GraphQL 文档。使用命名操作(query GetWallet)以获得更好的日志。
  • variables — 带类型的输入,将数值从查询字符串中分离。
  • operationName — 可选,当一个文档定义多个操作时很有用。

查询与变更

  • 查询(Queries) 是只读的(viewerwallettransactions)。
  • 变更(Mutations) 会改变状态(createVirtualCardpurchaseGiftCarddepositCashBalancecreateTransfer)。
涉及资金流动的变更使用请求去重——参见 Idempotency

响应格式

GraphQL 始终以 HTTP 200 返回,并包含 data / errors 封装:
在失败时,data 可能为 null,而 errors 将描述出错原因——其中包括可供分支判断的机器可读 code。参见 Errors

自省与模式

在 staging 中启用了自省,因此你可以将 Apollo Studio 或 GraphiQL 等工具指向该端点。在 live 中,自省被禁用;请改用发布于 API reference 的模式。

后续步骤

Authentication

Authorization 头中的令牌如何生成——用于你的账户或客户的账户。

Errors

errors 数组包含什么以及如何基于错误码进行分支。