Готовые рецепты

Сквозные примеры: не отдельные методы, а задачи целиком.

Во всех примерах КЛЮЧ — ваш API-ключ, БОТ — BotID из /bot/list.

---

Заявка с сайта попадает в бот и в список

Человек оставил заявку на сайте. Нужно записать её в список бота и написать менеджеру.

# 1. строка в список заявок
curl -X POST https://api.quescha.com/api/list/row/add \
  -H "Authorization: КЛЮЧ" -H "Content-Type: application/json" \
  -H "Idempotency-Key: lead-2026-08-28-4471" \
  -d '{
    "listid": 288,
    "row": {"Имя": "Пётр", "Телефон": "+79990000000", "Источник": "сайт"}
  }'

# 2. сообщение менеджеру в бот
curl -X POST https://api.quescha.com/api/message/send \
  -H "Authorization: КЛЮЧ" -H "Content-Type: application/json" \
  -d '{
    "botid": "БОТ",
    "clientid": "111222333",
    "text": "Новая заявка с сайта: Пётр, +79990000000"
  }'

Заголовок Idempotency-Key здесь не формальность: если сеть оборвётся и ваш сайт повторит запрос, вторая заявка не появится.

---

Оплата на сайте двигает клиента по воронке

# перевести на этап и запустить цепочку «после оплаты»
curl -X POST https://api.quescha.com/api/crm/stage/set \
  -H "Authorization: КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"botid":"БОТ","clientid":"987654321","stage":"Оплачен"}'

Если у цепочки стоит запуск по тегу этапа, она стартует сама. Если нет — запустите явно:

curl -X POST https://api.quescha.com/api/chain/start \
  -H "Authorization: КЛЮЧ" -H "Content-Type: application/json" \
  -d '{
    "botid": "БОТ",
    "clientid": "987654321",
    "chaincode": "483920174829301",
    "data": {"номер_заказа": "A-1024", "сумма": "3500"}
  }'

Переданные data сценарий увидит как #{номер_заказа} и #{сумма}.

---

Ваша CRM узнаёт о новом подписчике

Вместо опроса — подписка:

curl -X POST https://api.quescha.com/api/hook/create \
  -H "Authorization: КЛЮЧ" -H "Content-Type: application/json" \
  -d '{
    "name": "CRM",
    "url": "https://example.com/quescha/hook",
    "events": ["subscriber.new", "subscriber.stage", "payment.success"]
  }'

Дальше ваш обработчик проверяет подпись и разбирает событие — код на Node.js и Python в статье «Подписка на события».

---

Ключ для подрядчика

Подрядчик делает интеграцию с одним ботом и не должен видеть остальные:

curl -X POST https://api.quescha.com/api/key/create \
  -H "Authorization: КЛЮЧ_АККАУНТА" -H "Content-Type: application/json" \
  -d '{
    "name": "Подрядчик: интеграция с 1С",
    "scopes": ["lists:read", "lists:write", "subscribers:read"],
    "bots": ["БОТ"],
    "days": 60
  }'

Через 60 дней ключ умрёт сам. Отозвать раньше — POST /key/revoke с его id.

---

Синхронизация статусов заказов

Ваша система знает статусы, бот показывает их клиенту.

# найти строку заказа
curl -X POST https://api.quescha.com/api/list/rows/find \
  -H "Authorization: КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"listid": 301, "where": {"Номер": "A-1024"}}'

# обновить статус
curl -X POST https://api.quescha.com/api/list/row/edit \
  -H "Authorization: КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"listid": 301, "rowid": 8412, "row": {"Статус": "Готов к выдаче"}}'

# и показать клиенту нужный блок бота
curl -X POST https://api.quescha.com/api/block/start \
  -H "Authorization: КЛЮЧ" -H "Content-Type: application/json" \
  -d '{
    "botid": "БОТ",
    "clientid": "987654321",
    "chaincode": "483920174829301",
    "stepcode": "718239104829301",
    "block": "3",
    "data": {"номер_заказа": "A-1024"}
  }'

---

Отчёт по боту раз в сутки

curl "https://api.quescha.com/api/stat/get?from=2026-08-01&to=2026-08-28" \
  -H "Authorization: КЛЮЧ"

curl "https://api.quescha.com/api/crm/board" -H "Authorization: КЛЮЧ"

curl "https://api.quescha.com/api/account/get" -H "Authorization: КЛЮЧ"

Первый запрос даёт подписчиков и отправленные сообщения по дням, второй — распределение по воронке, третий — остаток по тарифу и генерациям.

---

Пример на JavaScript

const HOST = 'https://api.quescha.com/api'
const KEY = process.env.QUESCHA_KEY

async function call (method, body) {
  const res = await fetch(HOST + method, {
    method: 'POST',
    headers: { Authorization: KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify(body)
  })
  const data = await res.json()
  if (!res.ok) throw new Error(data.code + ': ' + data.error)
  return data
}

const { items } = await call('/subscriber/list', { botid: 'БОТ', tag: 'vip', limit: 100 })
for (const one of items) {
  await call('/message/send', { botid: one.botid, clientid: one.clientid, text: 'Спасибо, что вы с нами!' })
}

Не частите

Десять запросов в секунду — предел. Для рассылки по сегменту есть /broadcast/send: один запрос вместо сотни, и очередь отправки конструктор построит сам.

---

Пример на Python

import os, requests

HOST = 'https://api.quescha.com/api'
KEY = os.environ['QUESCHA_KEY']

def call(method, **body):
    r = requests.post(HOST + method, json=body, headers={'Authorization': KEY}, timeout=30)
    data = r.json()
    if not r.ok:
        raise RuntimeError(f"{data.get('code')}: {data.get('error')}")
    return data

call('/list/row/add', listid=288, row={'Имя': 'Пётр', 'Телефон': '+79990000000'})