第一次有准备的请求

1. 确认操作已启用

打开 API 页面，查看该操作的当前可用状态与价格。只有已启用的操作可以调用。

2. 创建最小权限密钥

在「控制台 → API 密钥」中创建密钥，本例仅选择 currency:latest。将只显示一次的密钥保存在服务端密钥管理器中。网关无法再次展示明文。

网关方法与输入位置

调用公共网关时使用 POST 与 JSON 对象。导入的 OpenAPI 操作使用 { path?, query?, headers?, body? }，仅包含文档规定的位置。其中 headers 是经过校验的输入数据，不是浏览器请求头，也不应用于填写凭证。货币接口保留原有平铺 JSON 输入，不要将其字段包裹在 body 中。

3. 将请求标识与业务意图绑定

为一个不变的请求使用同一个 Idempotency-Key。发送前，将它和输入指纹一起保存在应用中。不要仅因连接超时就重新生成标识。

# Server-side only. Set ATLAS_API_KEY in your secret manager.
# Set ATLAS_API_ORIGIN to your configured deployment origin.
# Every gateway operation is called with POST.
# Only operations shown as enabled on the API page can be called.
# Generate once per intent; retain the same value on status checks.
REQUEST_ID="$(uuidgen)"

curl --request POST 'https://apigate.vercel.app/api/v1/currency/latest' \
  --header "Content-Type: application/json" \
  --header "x-api-key: $ATLAS_API_KEY" \
  --header "Idempotency-Key: $REQUEST_ID" \
  --data '{"base":"EUR","symbols":"USD,GBP"}'

4. 阅读响应封装，而非只看 HTTP 状态

使用 data 之前检查 ok。成功的真实响应包含 meta.requestId、以十进制字符串表示的 meta.chargedCreditUnits 以及来源署名。保留请求 ID 用于支持，不要记录密钥。积分是以十进制字符串表示的整数积分单位，最多显示两位小数，不是货币兑换汇率。

{
  "ok": false,
  "error": {
    "code": "OPERATION_DISABLED",
    "message": "This operation is not currently enabled."
  },
  "requestId": "<request-id>"
}

了解错误及不确定的结果