QannasAPI
← Все рецептырецепт 01

Оцените до вызова: бесплатная стоимость любого действия

Что вы построите: двухшаговый приём, который оценивает стоимость вызова, сверяет её с бюджетом и только затем выполняет вызов. В итоге у вас будет обёртка, применимая к любому действию каталога.

РазделОсновы API
Используемые действияPOST /v1/data/{action}:estimatePOST /v1/data/contacts/find-email
КредитыБесплатно — эти эндпоинты никогда не тарифицируются
Работает с тестовым ключомДа — работает на qk_test_ за ноль кредитов
Время на выполнение~5 мин
ТребованияРабочее пространство, ключ qk_test_ или qk_live_ и curl либо любой HTTP-клиент.

Эндпоинт оценки

У каждого тарифицируемого действия есть парная оценка. Возьмите путь действия, добавьте :estimate и отправьте то же тело, которое собирались отправить. Вы получите стоимость именно этого вызова в кредитах, и за сам вопрос с вас ничего не спишут.

estimate.sh
# 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"}'

Прочитайте оценку

Ответ использует стандартную обёртку — status, request_id, data — и оценка лежит внутри data. Поскольку оценка бесплатна, заголовок X-Credits-Charged у оценки всегда равен 0.

estimate response
# < 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 */ }
}

Оцените, проверьте, затем запускайте

Полезная форма — это шлюз: оцените, сравните с вашим бюджетом и выполняйте только при прохождении. Оба вызова принимают одно и то же тело, так что шлюз стоит вам одного лишнего запроса и нуля кредитов.

quote_then_call.py
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
    )

Сценарии оцениваются так же

Серверные сценарии используют dry_run вместо суффикса :estimate — отправьте dry_run: true и получите разбивку по шагам, ничего не запуская. Та же идея и та же нулевая стоимость.

workflow-quote.sh
# 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 bills

Итоги

ПриёмКак
Оценить действиеPOST /v1/data/{action}:estimate с телом, которое собираетесь отправить
Оценить сценарийPOST /v1/data/workflows/{name} с dry_run: true
Стоимость оценкиНоль — X-Credits-Charged у оценки всегда 0
Обёртка{ status, request_id, data } — одинаково у оценок и реальных вызовов
Что означает числоХудший случай при условии, что каждый шаг что-то найдёт

Чек-лист перед продакшеном

  • Ставьте дорогие или инициированные пользователем вызовы за оценку.
  • Планируйте бюджет по оценке, затем сверяйтесь по X-Credits-Charged.
  • Оценки продолжают работать при нулевом балансе — оценка всегда бесплатна.
  • Отправляйте в оценку то же тело, что и в реальный вызов, иначе оценка не совпадёт.

Дальше

рецепт 02

Читайте заголовки кредитов

Проверяйте каждое списание прямо из ответа, без сверки в конце месяца.

рецепт 03

Обрабатывайте пустые ответы и повторы

Отличайте пустой результат от сбоя и повторяйте только то, что безопасно повторять.

Сначала запустите оценку. Она ничего не стоит и использует ровно ту же арифметику, что и счётчик.

Получить API-ключЧитать справочник API