Документация

Справочник API

Документация

REST API Aitelier позволяет программно запускать исходящие звонки, вести пакетные кампании, читать сессии и просматривать подписки на вебхуки. Эта страница — краткий справочник; интерактивный и всегда актуальный справочник с полными схемами запросов и ответов отдаёт сам API по адресу /v1/docs, а документ OpenAPI — по /v1/openapi.json.

Базовый URL

https://public-api.beta.aitelier.org/v1

Все эндпоинты требуют HTTPS.

Аутентификация

Каждому запросу нужен API-ключ уровня проекта:

Authorization: Bearer avp_live_…

(X-API-Key: avp_live_… тоже работает.)

API-ключи выпускаются во вкладке API keys проекта, права задаются на каждый ключ, отозвать можно в любой момент. Ключи показываются один раз при создании; мы храним их хэшированными и не можем восстановить исходное значение. UI идентифицирует ключи по префиксу.

Доступные права:

  • outbound:trigger — запускать исходящие звонки и пакеты
  • sessions:read — читать метаданные сессий, исходы, значения слотов
  • webhooks:read — просматривать подписки на вебхуки и отправлять тестовые доставки

Выданные права — единственные операции, которые ключ может выполнять. Вход в дашборд (код на почту + JWT) — отдельный механизм; API-ключи — единственный способ обращаться к API из вашего кода.

Идемпотентность

POST /v1/calls принимает заголовок Idempotency-Key. Мы дедуплицируем одинаковые ключи в течение 24 часов с момента первого получения: повтор с тем же ключом возвращает исходный ответ, а повторное использование ключа с другим телом возвращает 409. Используйте его для безопасных повторов при сетевых сбоях.

Ограничения частоты запросов

Значения по умолчанию на API-ключ, в минуту:

  • 100 запросов для изменяющих операций (POST/PUT/PATCH/DELETE)
  • 1000 запросов для чтения (GET)

Каждый ответ несёт состояние лимита:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 42
X-RateLimit-Window: 60

При превышении лимита вы получаете 429 Too Many Requests и заголовок Retry-After. Выдержите паузу и повторите.

Эндпоинты

Исходящие звонки

  • POST /v1/calls — запустить один исходящий звонок. Полная схема тела — в разделе Исходящие звонки.

Исходящие пакеты

  • POST /v1/calls/bulk — запустить пакет (multipart: scenarioId, опциональный callerIdNumber, CSV-файл).
  • GET /v1/calls/batches — список пакетов.
  • GET /v1/calls/batches/{id} — статус пакета и счётчики по состояниям.
  • POST /v1/calls/batches/{id}/cancel — отменить оставшиеся строки.

Сессии

  • GET /v1/sessions — список с фильтрами scenarioId, status, from, to и пагинацией limit/cursor.
  • GET /v1/sessions/{id} — полные данные сессии: статус, исход, значения слотов, достижение цели.

Статусы сессий: pending, live, completed, failed, abandoned.

Вебхуки

  • GET /v1/webhooks — список подписок проекта.
  • GET /v1/webhooks/{id} — одна подписка.
  • POST /v1/webhooks/{id}/test — отправить тестовую доставку на ваш эндпоинт.

Подписки создаются и редактируются в веб-интерфейсе — см. Вебхуки.

Формат ошибок

Каждый ответ с ошибкой — JSON:

{
  "error": {
    "code": "VALIDATION",
    "message": "phone must be a valid E.164 number",
    "details": { … }
  }
}

Частые HTTP-коды:

  • 400 — некорректный ввод (VALIDATION; подробности в сообщении)
  • 401 — отсутствующая / некорректная аутентификация (UNAUTHENTICATED)
  • 402 — баланс кошелька или кредитный лимит не покрывает звонок (PAYMENT_REQUIRED)
  • 403 — аутентификация в порядке, но не хватает прав (FORBIDDEN)
  • 404 — ресурс не существует или вам не виден (NOT_FOUND)
  • 409 — конфликт, например повторное использование idempotency-key с другим телом (CONFLICT)
  • 429 — превышен лимит запросов (RATE_LIMIT)
  • 500 — ошибка платформы (INTERNAL); по таким срабатывают наши оповещения

Версионирование

Текущая версия — v1. Аддитивные изменения — новые поля, новые эндпоинты — выходят без предупреждения и по соглашению не ломают совместимость: игнорируйте поля, которые не распознаёте. Ломающие изменения получают новую мажорную версию с окном вывода из эксплуатации, о котором уведомляется каждый активный интегратор.