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ón | Fundamentos de la API |
|---|---|
| Acciones usadas | POST /v1/data/contacts/verify-email |
| Créditos | 1 (peor caso) |
| Compatible con clave de prueba | Sí — se ejecuta con qk_test_ por cero créditos |
| Tiempo estimado | ~5 min |
| Requisitos previos | Una 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.
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 appliedRegistra 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.
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.
// 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ón | Cómo |
|---|---|
| Lo que costó esta llamada | X-Credits-Charged |
| Lo que queda | X-Credits-Balance |
| Qué reglas se aplicaron | X-Price-Book |
| Rastrear un cargo | request_id en el cuerpo de la respuesta |
| Limitar el ritmo | Alerta 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.