Estima antes de llamar: cotiza cualquier acción gratis
Lo que vas a construir: un patrón de dos pasos que cotiza el coste de una llamada, lo compara con un presupuesto y solo entonces la ejecuta. Terminarás con un ayudante que puedes envolver alrededor de cualquier acción del catálogo.
| Sección | Fundamentos de la API |
|---|---|
| Acciones usadas | POST /v1/data/{action}:estimatePOST /v1/data/contacts/find-email |
| Créditos | Gratis — estos endpoints nunca cobran |
| Compatible con clave de prueba | Sí — se ejecuta con qk_test_ por cero créditos |
| Tiempo estimado | ~5 min |
| Requisitos previos | Un espacio de trabajo, una clave qk_test_ o qk_live_, y curl o cualquier cliente HTTP. |
El endpoint de estimación
Cada acción con precio tiene su estimación. Toma la ruta de la acción, añade :estimate y envía el mismo cuerpo que ibas a enviar de todos modos. Recuperas el coste en créditos de esa llamada exacta y preguntarlo no se te cobra.
# Append :estimate to any action path. Costs nothing.
curl -X POST https://api.qannasapi.com/v1/data/contacts/find-email:estimate \
-H "Authorization: Bearer $QANNAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"query": "Jane Doe, Acme Logistics"}'Lee la cotización
La respuesta usa el sobre estándar — status, request_id, data — con la cotización dentro de data. Como estimar es gratis, la cabecera X-Credits-Charged de una estimación siempre vale 0.
# < HTTP/1.1 200 OK
# < X-Credits-Charged: 0 # asking is always free
{
"status": "OK",
"request_id": "req_...",
"data": { /* the quote for this exact call */ }
}Cotiza, comprueba y luego ejecuta
La forma útil es una compuerta: estima, compara con el presupuesto que manejes y ejecuta solo si pasa. Ambas llamadas toman el mismo cuerpo, así que la compuerta te cuesta una petición extra y cero créditos.
import os, requests
API = "https://api.qannasapi.com"
HEADERS = {"Authorization": f"Bearer {os.environ['QANNAS_API_KEY']}"}
def quote_then_call(action, body, budget):
# 1 — free quote, same body as the real call
quote = requests.post(
f"{API}/v1/data/{action}:estimate", json=body, headers=HEADERS
).json()
# 2 — gate on your own budget before spending anything
if cost_of(quote) > budget:
raise RuntimeError("quote exceeds budget")
# 3 — run it
return requests.post(
f"{API}/v1/data/{action}", json=body, headers=HEADERS
)Los flujos se cotizan igual
Los flujos del lado del servidor usan dry_run en vez del sufijo :estimate — envía dry_run: true y obtienes el desglose por paso sin ejecutar nada. La misma idea y el mismo coste nulo.
# Workflows use dry_run instead of a :estimate suffix.
curl -X POST https://api.qannasapi.com/v1/data/workflows/lead-list \
-H "Authorization: Bearer $QANNAS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"inputs": {"industry": "logistics"}, "limit": 25, "dry_run": true}'
# < X-Credits-Charged: 0 # a dry run never billsResumen
| Patrón | Cómo |
|---|---|
| Cotizar una acción | POST /v1/data/{action}:estimate con el cuerpo que piensas enviar |
| Cotizar un flujo | POST /v1/data/workflows/{name} con dry_run: true |
| Coste de estimar | Cero — X-Credits-Charged siempre es 0 en una estimación |
| Sobre | { status, request_id, data } — igual en estimaciones y llamadas reales |
| Qué significa el número | El peor caso, asumiendo que cada paso encuentra algo |
Lista para producción
- Pon las llamadas caras o disparadas por el usuario detrás de una estimación.
- Presupuesta contra la estimación y luego concilia contra X-Credits-Charged.
- Las cotizaciones siguen funcionando con saldo cero — estimar siempre es gratis.
- Envía a la estimación el mismo cuerpo que a la llamada real, o la cotización no coincidirá.
Siguientes pasos
Ejecuta primero la estimación. No cuesta nada y aplica exactamente la misma aritmética que el contador.