QannasAPI

Lire les en-têtes de crédits : auditer chaque débit depuis la réponse

Ce que vous allez construire : un fin wrapper client qui journalise le coût de chaque appel et ce qu'il vous reste, pour que vos propres logs deviennent la piste d'audit de facturation.

SectionFondamentaux de l'API
Actions utiliséesPOST /v1/data/contacts/verify-email
Crédits1 (pire cas)
Compatible clé de testOui — tourne sur qk_test_ pour zéro crédit
Temps nécessaire~5 min
PrérequisUne clé et n'importe quel client HTTP permettant de lire les en-têtes de réponse.

Trois en-têtes sur chaque appel de données

X-Credits-Charged est ce que cet appel a coûté. X-Credits-Balance est ce qu'il reste ensuite. X-Price-Book identifie le barème selon lequel le débit a été calculé, de sorte qu'un devis et un débit se rattachent toujours aux mêmes règles.

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

Journalisez le débit, pas l'estimation

Enveloppez votre client HTTP une fois et enregistrez les trois en-têtes à côté de request_id. Vous obtenez l'attribution des coûts par appel sans interroger un endpoint d'usage, et request_id est ce que le support demandera si un débit paraît anormal.

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

Surveillez le solde, pas l'horloge

Comme le solde revient à chaque appel, vous pouvez limiter le débit ou alerter à partir de la réponse que vous avez déjà. Aucun endpoint de quota à interroger et aucun décalage entre dépenser et le savoir.

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

Résumé

MotifComment
Ce que cet appel a coûtéX-Credits-Charged
Ce qu'il resteX-Credits-Balance
Quelles règles s'appliquaientX-Price-Book
Tracer un débitrequest_id dans le corps de la réponse
Limiter le débitAlertez sur X-Credits-Balance de l'appel que vous venez de faire

Checklist de mise en production

  • Journalisez X-Credits-Charged, X-Credits-Balance et request_id à chaque appel.
  • Alertez sur l'en-tête de solde plutôt que d'interroger un endpoint d'usage.
  • Conservez request_id — c'est ainsi qu'un débit précis se retrouve.
  • Attendez-vous à X-Credits-Charged: 0 sur un résultat vide et n'y voyez pas un échec.

Étapes suivantes

Lancez d'abord l'estimation. Elle ne coûte rien et applique exactement le même calcul que le compteur.