QannasAPI
← Todas as receitasreceita 02

Leia os cabeçalhos de créditos: audite cada cobrança pela resposta

O que você vai construir: um wrapper enxuto de cliente que registra quanto cada chamada custou e quanto sobrou, para que seus próprios logs virem a trilha de auditoria de cobrança.

SeçãoFundamentos da API
Ações usadasPOST /v1/data/contacts/verify-email
Créditos1 (pior caso)
Funciona com chave de testeSim — roda em qk_test_ por zero créditos
Tempo estimado~5 min
Pré-requisitosUma chave e qualquer cliente HTTP que permita ler cabeçalhos de resposta.

Três cabeçalhos em toda chamada de dados

X-Credits-Charged é quanto esta chamada custou. X-Credits-Balance é o que resta depois dela. X-Price-Book identifica a tabela de preços com a qual a cobrança foi calculada, de modo que cotação e cobrança sempre remetem às mesmas regras.

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

Registre a cobrança, não a estimativa

Envolva seu cliente HTTP uma vez e grave os três cabeçalhos ao lado do request_id. Isso dá atribuição de custo por chamada sem consultar um endpoint de uso, e o request_id é o que o suporte vai pedir se alguma cobrança parecer errada.

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;
}

Observe o saldo, não o relógio

Como o saldo volta em toda chamada, você pode limitar a taxa ou alertar a partir da resposta que já tem. Não há endpoint de cota separado para consultar nem defasagem entre gastar e saber.

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}`);
}

Resumo

PadrãoComo
Quanto esta chamada custouX-Credits-Charged
Quanto restaX-Credits-Balance
Quais regras se aplicaramX-Price-Book
Rastrear uma cobrançarequest_id no corpo da resposta
Limitar a taxaAlerte pelo X-Credits-Balance da chamada que você acabou de fazer

Checklist de produção

  • Registre X-Credits-Charged, X-Credits-Balance e request_id em toda chamada.
  • Alerte pelo cabeçalho de saldo em vez de consultar um endpoint de uso.
  • Guarde o request_id — é por ele que uma cobrança específica é rastreada.
  • Espere X-Credits-Charged: 0 quando não houver resultado e não trate isso como falha.

Próximos passos

receita 01

Estime antes de chamar

Cote de graça o custo exato em créditos de qualquer ação antes de executá-la.

receita 03

Lide com resultados vazios e retentativas

Diferencie um resultado vazio de uma falha e só repita o que é seguro repetir.

Rode a estimativa primeiro. Ela não custa nada e aplica exatamente a mesma aritmética que o medidor.

Pegue sua chave de APILeia a referência da API