Estimer avant d'appeler : chiffrer n'importe quelle action gratuitement
Ce que vous allez construire : un schéma en deux temps qui chiffre le coût d'un appel, le compare à un budget, et ne l'exécute qu'ensuite. Vous repartirez avec un utilitaire à envelopper autour de n'importe quelle action du catalogue.
| Section | Fondamentaux de l'API |
|---|---|
| Actions utilisées | POST /v1/data/{action}:estimatePOST /v1/data/contacts/find-email |
| Crédits | Gratuit — ces endpoints ne facturent jamais |
| Compatible clé de test | Oui — tourne sur qk_test_ pour zéro crédit |
| Temps nécessaire | ~5 min |
| Prérequis | Un espace de travail, une clé qk_test_ ou qk_live_, et curl ou n'importe quel client HTTP. |
L'endpoint d'estimation
Chaque action facturée a son estimation. Prenez le chemin de l'action, ajoutez :estimate, et envoyez le corps que vous alliez envoyer de toute façon. Vous récupérez le coût en crédits de cet appel précis et cette demande ne vous est pas facturée.
# 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"}'Lire le devis
La réponse utilise l'enveloppe standard — status, request_id, data — avec le devis à l'intérieur de data. Comme estimer est gratuit, l'en-tête X-Credits-Charged d'une estimation vaut toujours 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 */ }
}Chiffrer, vérifier, puis lancer
La forme utile est celle d'une barrière : estimez, comparez au budget dont vous disposez, et n'exécutez que si cela passe. Les deux appels prennent le même corps, donc la barrière vous coûte une requête de plus et zéro crédit.
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
)Les workflows se chiffrent pareil
Les workflows côté serveur utilisent dry_run au lieu du suffixe :estimate — envoyez dry_run: true et vous obtenez le détail par étape sans rien exécuter. Même idée, même coût nul.
# 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 billsRésumé
| Motif | Comment |
|---|---|
| Chiffrer une action | POST /v1/data/{action}:estimate avec le corps que vous comptez envoyer |
| Chiffrer un workflow | POST /v1/data/workflows/{name} avec dry_run: true |
| Coût d'une estimation | Zéro — X-Credits-Charged vaut toujours 0 sur une estimation |
| Enveloppe | { status, request_id, data } — identique en estimation et en appel réel |
| Ce que le chiffre signifie | Le pire cas, en supposant que chaque étape trouve quelque chose |
Checklist de mise en production
- Placez les appels coûteux ou déclenchés par un utilisateur derrière une estimation.
- Budgétez sur l'estimation, puis rapprochez sur X-Credits-Charged.
- Les devis fonctionnent même à solde nul — estimer est toujours gratuit.
- Envoyez à l'estimation le même corps qu'à l'appel réel, sinon le devis ne correspondra pas.
Étapes suivantes
Lancez d'abord l'estimation. Elle ne coûte rien et applique exactement le même calcul que le compteur.