Списки#

Методи цього розділу створюють і видаляють списки, змінюють їхні поля та ведуть записи: додають, читають, змінюють і видаляють. Наприклад, сайт може сам поповнювати список «Меню кафе», а бот — показувати його людям.

Як влаштований список#

Список складається з двох частин:

• Схема — назва списку та його поля. З нею працюють методи на сторінці Списки й поля. У назвах методів схема так і називається: getListSchema, createListSchema.
• Записи — рядки списку зі значеннями полів. З ними працюють методи на сторінці Записи.

Списки належать проєкту. Створити список можна в проєкті або в боті — тоді він теж потрапляє до проєкту цього бота. Через API доступні всі списки проєктів, власник яких — власник ключа: і створені в ботах, і створені безпосередньо в проєкті.

Ідентифікатори#

slug — це ім'я поля в підстановках: під ним значення лежить у записі й під ним же його читають блоки бота. Поля, створені в кабінеті, отримують його автоматично; через API ви задаєте його самі.

Типи полів#

Тип задається під час створення поля в параметрі type і потім не змінюється.

Порожнє поле приходить у відповіді як null.

Дата і час#

Час без часового поясу вважається часом UTC: "2026-10-15 14:30" збережеться як 14:30 UTC. Щоб передати місцевий час, укажіть пояс: "2026-10-15T14:30:00+03:00". Поле date час не обрізає: якщо передати дату з часом, час збережеться.

Гроші#

Валюта задається в полі під час його створення (currency) і в записі не передається. Це трилітерний код за ISO 4217: UAH, USD, EUR. У createListSchema валюту можна не вказувати — тоді USD; в addListSchemaField вона обов'язкова. Невідомий код — 422.

Суму передавайте в основних одиницях — гривнях, а не копійках. Вона округлюється до знаків валюти (у гривні й долара — два), половина — у більший бік: 0.295 збережеться як 0.30.

Файли й картинки#

Значення поля file або image — об'єкт. Через API в нього можна записати лише посилання на файл, який лежить в інтернеті:

{
  "url": "https://example.com/menu/cappuccino.jpg",
  "storage": "url",
  "name": "cappuccino.jpg",
  "type": "image"
}

Увага

Без "storage": "url" або з посиланням іншого виду (не http/https) значення мовчки не збережеться — у полі опиниться null, помилки не буде.

Інші ключі (наприклад, uuid або path) ігноруються: у полі зберігається лише зовнішнє посилання, і у відповіді воно приходить таким самим, яким його передали. Посилання на файл зі сховища платформи — таке, що приходить у відповідях на файли, завантажені в кабінеті, — можна записати лише в межах свого акаунта; посилання на файл іншого акаунта не збережеться — у полі опиниться null. Якщо в updateListItem передати файл, який уже лежить у записі, наприклад цілий запис із getListItems, він залишиться як був.

У відповіді файл описано об'єктом із ключами type, mime_type, created_at, name, size, storage, caption, meta (ширина, висота, тривалість, кодек) і url. Посилання на файли, завантажені в кабінеті, — тимчасові: завантажуйте файл одразу або запитуйте запис знову.

Контакт і бот#

У поля contact і bot передають номер. Контакт має належати вашому боту, бот — вам: інакше відповідь 403. Номер, якого не існує, не пройде перевірку — 422.

Окрім значення самого поля, запис отримує службові contact_id або bot_id — за ними працює відбір у getListItems. Якщо в списку кілька таких полів, там опиниться значення останнього з них.

Налаштування поля#

Важливо

За замовчуванням поле, створене через API, обов'язкове — на відміну від кабінету. Якщо поле можна залишати порожнім, передайте "is_required": false.

Обмеження#

• У проєкті — не більше 5000 списків.
• Під час створення списку — від 1 до 30 полів.
• Назва списку й поля — до 255 символів.
• Не можна використовувати службові імена полів: id, _id, contact, contact_id, bot, bot_id, user, user_id, project, project_id, data, schema_id, created_at, updated_at, deleted_at і будь-які імена, що починаються з __. На такий slug API відповість 422 з текстом «The slug is reserved.».

Загальні правила — ключ, частота запитів, коди помилок — описано на сторінці API.

Методи#