Списки

Списки — это рабочая база бота: заявки, брони, заказы, записи, каталог водителей. Через API их можно читать, пополнять и править из своей системы.

Авторизация

Права: lists:read для чтения, lists:write для изменений.

---

Как устроена строка

Список — это колонки (headers) и строки значений в порядке этих колонок. Чтобы не считать порядок руками, каждая строка отдаётся сразу в двух видах:

{
  "id": 8412,
  "values": ["Пётр", "+79990000000", "28.08.2026 14:05"],
  "row": {
    "Имя": "Пётр",
    "Телефон": "+79990000000",
    "CreationDate": "28.08.2026 14:05"
  },
  "created": "2026-08-28T11:05:12.000Z"
}

На запись принимаются оба вида: объект row (по названиям колонок) или массив values (по порядку).

Служебные колонки заполняются сами

Если в списке есть колонки CreationDate, ClientID, Messenger, BotID и вы их не передали — они заполнятся сами: дата текущим временем в часовом поясе аккаунта, остальные — из параметров запроса clientid, messenger, botid. Ровно так же ведёт себя действие «Добавить строку» внутри бота.

---

Все списки

GET|POST /list/all

{
  "items": [
    { "id": 288, "name": "Заявки", "headers": ["Имя", "Телефон", "CreationDate"], "count": 412 }
  ]
}

Параметр group ограничивает выборку одним проектом (код проекта — из /group/list).

---

Строки списка

GET|POST /list/rows/get

Поле	Обязательный	Описание
listid	Да*	номер списка
list	Да*	или название списка вместо номера
limit, offset	Нет	постранично, в ответе total
sort	Нет	old (по умолчанию) или new

* нужен один из двух.

---

Поиск строк

POST /list/rows/find

curl -X POST https://api.quescha.com/api/list/rows/find \
  -H "Authorization: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"listid": 288, "where": {"Телефон": "+79990000000"}}'

Поле	Описание
where	объект «колонка: значение»; условий может быть несколько, они складываются по «и»
column + value	одно условие парой — так удобнее в GET-запросе
exact	false — искать по части значения, без учёта регистра

Почему поиск идёт по всему списку

Строки лежат в базе одним полем JSON, разобрать их запросом нельзя — сравнение идёт в памяти. Для списков конструктора это не проблема: их размер ограничен тарифом.

---

Добавить строку

POST /list/row/add

curl -X POST https://api.quescha.com/api/list/row/add \
  -H "Authorization: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1024" \
  -d '{
    "listid": 288,
    "row": {"Имя": "Пётр", "Телефон": "+79990000000"},
    "clientid": "987654321",
    "messenger": "telegram",
    "botid": "123456789"
  }'

Заголовок Idempotency-Key защищает от двойной записи при обрыве сети — см. Авторизация.

{ "row": { … }, "trimmed": false }

Поле trimmed: true означает, что список упёрся в предел строк по тарифу и самая старая строка была удалена — так же, как это делает бот.

Много строк за раз

POST /list/rows/add — параметр rows, массив объектов или массивов, не больше 500 за запрос.

---

Изменить строку

POST /list/row/edit

curl -X POST https://api.quescha.com/api/list/row/edit \
  -H "Authorization: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"listid": 288, "rowid": 8412, "row": {"Статус": "Выполнено"}}'

Меняются только переданные колонки, остальные остаются как были. Чтобы заменить строку целиком, передайте values — массив по порядку колонок.

---

Удалить строки и очистить список

POST /list/row/delete — параметр rowid или rowids (массив номеров).

POST /list/clear — удаляет все строки списка, сам список остаётся.

---

Создать список

POST /list/create

curl -X POST https://api.quescha.com/api/list/create \
  -H "Authorization: ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
  -d '{"name": "Заявки с сайта", "headers": ["Имя", "Телефон", "Комментарий", "CreationDate"]}'

Название должно быть свободным: список с тем же именем даст ошибку list_exists. Параметр group кладёт список в конкретный проект.