QannasAPI

Lee las cabeceras de créditos: audita cada cargo desde la respuesta

Lo que vas a construir: un envoltorio ligero de cliente que registra lo que costó cada llamada y lo que te queda, de modo que tus propios registros se conviertan en la pista de auditoría de facturación.

SecciónFundamentos de la API
Acciones usadasPOST /v1/data/contacts/verify-email
Créditos1 (peor caso)
Compatible con clave de pruebaSí — se ejecuta con qk_test_ por cero créditos
Tiempo estimado~5 min
Requisitos previosUna clave y cualquier cliente HTTP que te deje leer cabeceras de respuesta.

Tres cabeceras en cada llamada de datos

X-Credits-Charged es lo que costó esta llamada. X-Credits-Balance es lo que queda después. X-Price-Book identifica el libro de precios con el que se calculó el cargo, de modo que una cotización y un cargo siempre se puedan rastrear a las mismas reglas.

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

Registra el cargo, no la estimación

Envuelve tu cliente HTTP una vez y guarda las tres cabeceras junto a request_id. Eso te da atribución de coste por llamada sin consultar un endpoint de uso, y request_id es lo que pedirá soporte si algún cargo parece incorrecto.

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

Vigila el saldo, no el reloj

Como el saldo vuelve en cada llamada, puedes limitar o alertar con la respuesta que ya tienes. No hay un endpoint de cuota separado que consultar ni desfase entre gastar y saberlo.

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

Resumen

PatrónCómo
Lo que costó esta llamadaX-Credits-Charged
Lo que quedaX-Credits-Balance
Qué reglas se aplicaronX-Price-Book
Rastrear un cargorequest_id en el cuerpo de la respuesta
Limitar el ritmoAlerta con X-Credits-Balance de la llamada que acabas de hacer

Lista para producción

  • Registra X-Credits-Charged, X-Credits-Balance y request_id en cada llamada.
  • Alerta con la cabecera de saldo en vez de consultar un endpoint de uso.
  • Guarda request_id — así se rastrea un cargo concreto.
  • Espera X-Credits-Charged: 0 cuando no hay resultado y no lo trates como un fallo.

Siguientes pasos

Ejecuta primero la estimación. No cuesta nada y aplica exactamente la misma aritmética que el contador.