QannasAPI

读取积分响应头:从响应中审计每一笔扣费

你将构建: 一层轻薄的客户端包装,记录每次调用的花费与剩余额度,让你自己的日志成为计费审计轨迹。

分类API 基础
使用的操作POST /v1/data/contacts/verify-email
积分1 (最坏情况)
测试密钥可用是 —— 可在 qk_test_ 上运行,零积分
预计耗时~5 分钟
前置条件一把密钥,以及任何能读取响应头的 HTTP 客户端。

每次数据调用都带三个响应头

X-Credits-Charged 是本次调用的花费。X-Credits-Balance 是调用之后的剩余额度。X-Price-Book 标明扣费所依据的价目表,因此报价与扣费始终能追溯到同一套规则。

headers.sh
curl -i -X POST https://api.qannasapi.com/v1/data/contacts/verify-email \
  -H "Authorization: Bearer $QANNAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "jane@acme.example"}'

# < HTTP/1.1 200 OK
# < X-Credits-Charged: 1      # what this call cost
# < X-Credits-Balance: 94     # what is left afterwards
# < X-Price-Book: public    # which rules were applied

记录扣费,而不是预估

把 HTTP 客户端包装一次,将这三个响应头与 request_id 一并记录。这样无需轮询用量端点就能按调用归集成本,而 request_id 正是扣费看起来有问题时客服会索取的东西。

metered_client.ts
export async function call(action: string, body: unknown) {
  const res = await fetch(`${API}/v1/data/${action}`, {
    method: "POST",
    headers: { Authorization: `Bearer ${key}`, "Content-Type": "application/json" },
    body: JSON.stringify(body),
  });

  const json = await res.json();
  // Your logs become the billing audit trail.
  logger.info("qannas.call", {
    action,
    request_id: json.request_id,
    charged: Number(res.headers.get("X-Credits-Charged")),
    balance: Number(res.headers.get("X-Credits-Balance")),
  });

  return json;
}

盯余额,别盯时钟

由于余额随每次调用返回,你可以基于手上已有的响应做限流或告警。既没有单独的配额端点需要轮询,花费与知晓之间也没有延迟。

throttle.ts
// The balance arrives on the call you already made —
// there is no quota endpoint to poll and no lag.
const balance = Number(res.headers.get("X-Credits-Balance"));
if (balance < LOW_WATER_MARK) {
  pauseNonUrgentJobs();
  alertOps(`credits low: ${balance}`);
}

小结

模式做法
本次调用花了多少X-Credits-Charged
还剩多少X-Credits-Balance
套用了哪套规则X-Price-Book
追溯一笔扣费响应体中的 request_id
限流基于刚完成那次调用返回的 X-Credits-Balance 告警

上线检查清单

  • 每次调用都记录 X-Credits-Charged、X-Credits-Balance 与 request_id。
  • 基于余额响应头告警,而不是轮询用量端点。
  • 保留 request_id —— 具体某笔扣费靠它追溯。
  • 无结果时应预期 X-Credits-Charged: 0,不要当成失败。

下一步

先运行预估。它不花任何费用,用的正是计量器将要套用的那套算术。