Estime antes de chamar: cote qualquer ação de graça
O que você vai construir: um padrão de dois passos que cota o custo de uma chamada, compara com um orçamento e só então a executa. Você termina com um utilitário que pode envolver qualquer ação do catálogo.
| Seção | Fundamentos da API |
|---|---|
| Ações usadas | POST /v1/data/{action}:estimatePOST /v1/data/contacts/find-email |
| Créditos | Grátis — estes endpoints nunca cobram |
| Funciona com chave de teste | Sim — roda em qk_test_ por zero créditos |
| Tempo estimado | ~5 min |
| Pré-requisitos | Um workspace, uma chave qk_test_ ou qk_live_ e curl ou qualquer cliente HTTP. |
O endpoint de estimativa
Toda ação cobrada tem uma estimativa correspondente. Pegue o caminho da ação, acrescente :estimate e envie o mesmo corpo que você já ia enviar. Você recebe o custo em créditos daquela chamada exata e não é cobrado por perguntar.
# 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"}'Leia a cotação
A resposta usa o envelope padrão — status, request_id, data — com a cotação dentro de data. Como estimar é grátis, o cabeçalho X-Credits-Charged de uma estimativa é sempre 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 */ }
}Cote, verifique e então execute
A forma útil é um portão: estime, compare com o orçamento que você tiver e execute somente se passar. As duas chamadas usam o mesmo corpo, então o portão custa uma requisição a mais e zero 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
)Fluxos cotam do mesmo jeito
Os fluxos no servidor usam dry_run em vez do sufixo :estimate — envie dry_run: true e você recebe o detalhamento por etapa sem executar nada. Mesma ideia, mesmo custo zero.
# 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 billsResumo
| Padrão | Como |
|---|---|
| Cotar uma ação | POST /v1/data/{action}:estimate com o corpo que você pretende enviar |
| Cotar um fluxo | POST /v1/data/workflows/{name} com dry_run: true |
| Custo de estimar | Zero — X-Credits-Charged é sempre 0 numa estimativa |
| Envelope | { status, request_id, data } — igual em estimativas e chamadas reais |
| O que o número significa | Pior caso, assumindo que toda etapa encontra algo |
Checklist de produção
- Coloque chamadas caras ou disparadas pelo usuário atrás de uma estimativa.
- Faça o orçamento pela estimativa e depois concilie por X-Credits-Charged.
- Cotações continuam funcionando com saldo zero — estimar é sempre grátis.
- Envie à estimativa o mesmo corpo da chamada real, ou a cotação não vai bater.
Próximos passos
Rode a estimativa primeiro. Ela não custa nada e aplica exatamente a mesma aritmética que o medidor.