Перейти к основному содержимому

Авторизация

Для работы с API конструктора Quescha требуется API-ключ. Ключ аккаунта выдаётся в настройках, а рядом с ним можно завести сколько угодно ключей с правами — см. Ключи и права.

API 1

Базовый URL​

https://api.quescha.com/api

Полный URL запроса = базовый адрес + метод. Например, метод /account/balance/get превращается в:

https://api.quescha.com/api/account/balance/get

HTTP-методы​

Читающие методы принимают GET и POST — что удобнее.

Изменяющие методы принимают только POST. Так сделано намеренно: GET-запросы повторяют браузеры, прокси и предпросмотр ссылок в мессенджерах, а повторить отправку сообщения подписчику или добавление строки в список нельзя.

Какой метод чем является, показано в списке методов в колонке «Способ».

Передача API-ключа​

Ключ можно передать тремя способами — выберите тот, который удобнее для вашего клиента.

Заголовок Authorization (рекомендуется)​

Authorization: 43c3130d767cb3fd01417ba5acf9ba12

Приставка Bearer тоже принимается. Подходит для запросов любым методом. Безопаснее: ключ не попадает в логи серверов и URL-историю браузера.

Заголовок X-Api-Key​

X-Api-Key: 43c3130d767cb3fd01417ba5acf9ba12

То же самое — для клиентов, которым так привычнее.

GET-параметр key​

https://api.quescha.com/api/...?key=43c3130d767cb3fd01417ba5acf9ba12

Удобно для быстрого теста в браузере, но не используйте этот способ в продакшене — ключ будет светиться в логах прокси, аналитике и истории браузера.

Храните ключ в секрете

Ключ аккаунта даёт полный программный доступ к вашему аккаунту. Не публикуйте его в репозиториях, не вставляйте в клиентский JavaScript и не делитесь с третьими лицами. Если ключ скомпрометирован — сгенерируйте новый в настройках аккаунта.

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

Параметры запроса​

Параметры принимаются и в строке запроса, и в теле JSON. Если параметр передан обоими способами, побеждает тело.

# в строке запроса
curl "https://api.quescha.com/api/subscriber/list?botid=123456789&limit=10" \
  -H "Authorization: ВАШ_КЛЮЧ"

# телом JSON
curl -X POST https://api.quescha.com/api/subscriber/list \
  -H "Authorization: ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{"botid": "123456789", "limit": 10}'

Постраничная выдача​

Все списочные методы принимают limit (по умолчанию 50, не больше 500) и offset, а отвечают полем total — сколько всего записей подходит под условие.

Частота запросов​

Предел — 10 запросов в секунду на аккаунт. Считается «ведром»: короткая пачка запросов подряд пройдёт, а вот равномерно частить не выйдет.

Каждый ответ несёт заголовки:

ЗаголовокЧто означает
X-RateLimit-Limitсколько запросов в секунду разрешено
X-RateLimit-Remainingсколько осталось прямо сейчас
X-RateLimit-Resetчерез сколько секунд ведро наполнится
Retry-Afterприходит вместе с ответом 429: через сколько секунд повторить

Отдельному ключу с правами можно задать свою частоту.

Повтор запроса без последствий​

Сеть рвётся посреди запроса, и вызывающий не знает, дошёл ли он. Повторить страшно: создастся вторая строка списка, уйдёт второе сообщение подписчику.

Передайте заголовок Idempotency-Key с любой строкой, придуманной на вашей стороне:

curl -X POST https://api.quescha.com/api/list/row/add \
  -H "Authorization: ВАШ_КЛЮЧ" \
  -H "Idempotency-Key: order-2026-08-28-17423" \
  -H "Content-Type: application/json" \
  -d '{"listid": 12, "row": {"Имя": "Пётр", "Телефон": "+79990000000"}}'
  • Первый запрос выполняется как обычно.
  • Повтор с тем же ключом ничего не создаёт, а возвращает сохранённый ответ первого запроса и заголовок Idempotent-Replay: true.
  • Тот же ключ с другими параметрами — ошибка 409 idempotency_conflict: значит, на вашей стороне ключ переиспользован по ошибке.

Ключи живут сутки.

Что дальше​