# Списки й поля Методи цієї сторінки працюють зі схемою списку — назвою та полями. Як влаштовані поля і які в них бувають типи, описано на сторінці [Списки](https://support.watbot.org/uk/api/lists#типи-полів). ## getListSchemas Повертає списки всіх проєктів, власник яких — власник ключа, по 50 на сторінку. ```endpoint GET POST https://watbot.org/api/v1/getListSchemas ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `page` | ціле число | ні | Номер сторінки, за замовчуванням `1` | ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/getListSchemas" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"page": 1}' ``` ```json title="Відповідь 200" { "data": [ { "id": "6650a1f2c3d4e5f6a7b8c9d0", "fields": { "nazva": { "name": "Назва", "type": "string", "is_required": true, "is_hidden": false, "is_encryptable": false }, "tsina": { "name": "Ціна", "type": "money", "currency": "UAH", "is_required": true, "is_hidden": false, "is_encryptable": false } }, "name": "Меню кафе", "bot_id": 12345, "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c", "is_menu": false, "created_at": "2026-10-01T09:15:00+00:00", "updated_at": "2026-10-02T11:40:12+00:00" } ], "links": { "first": "…/v1/getListSchemas?page=1", "last": "…/v1/getListSchemas?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "…/v1/getListSchemas", "per_page": 50, "to": 1, "total": 1 } } ``` Поля списку у відповіді: | Поле | Опис | |---|---| | `id` | Id списку | | `fields` | Поля: ключ — `slug`, значення — назва (`name`), тип (`type`) і налаштування. У грошового поля є `currency`. У полів, створених у кабінеті, можуть бути й інші ключі | | `name` | Назва списку | | `bot_id` | Бот, у якому створено список; `null`, якщо список створено в проєкті | | `project` | UUID проєкту, якому належить список | | `is_menu` | Застаріла позначка, на роботу списку не впливає | | `created_at`, `updated_at` | Коли список створено і змінено востаннє | Особливості: - Розмір сторінки — 50 списків, змінити його не можна. Скільки всього сторінок — у `meta.last_page`, адреса наступної — у `links.next`. - Списки проєктів, до яких вас запросили співробітником, у відповідь не потрапляють: API працює лише з проєктами власника ключа. ## getListSchema Повертає один список із полями. ```endpoint GET POST https://watbot.org/api/v1/getListSchema ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `schema_id` | рядок | так | Id списку | ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/getListSchema" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}' ``` ```json title="Відповідь 200" { "data": { "id": "6650a1f2c3d4e5f6a7b8c9d0", "fields": { "nazva": { "name": "Назва", "type": "string", "is_required": true, "is_hidden": false, "is_encryptable": false }, "tsina": { "name": "Ціна", "type": "money", "currency": "UAH", "is_required": true, "is_hidden": false, "is_encryptable": false } }, "name": "Меню кафе", "bot_id": 12345, "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c", "is_menu": false, "created_at": "2026-10-01T09:15:00+00:00", "updated_at": "2026-10-02T11:40:12+00:00" } } ``` ```json title="Відповідь 404" { "message": "Schema not found", "error": "Schema not found", "errors": { "schema_id": ["Schema not found"] } } ``` Помилки: - Списку немає або його видалено — `404`. Текст помилки — в `error` і `message`; для сумісності він же лежить у `errors.schema_id`. - Список із чужого проєкту — `403`. ## createListSchema Створює список із полями — у проєкті або в боті. ```endpoint GET POST https://watbot.org/api/v1/createListSchema ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `name` | рядок | так | Назва списку, до 255 символів | | `project_uuid` | рядок | так, якщо немає `bot_id` | UUID проєкту, у якому створити список | | `bot_id` | ціле число | так, якщо немає `project_uuid` | Номер бота: список потрапить до проєкту цього бота й буде позначений як створений у ньому. Якщо передано обидва параметри, використовується `bot_id` | | `fields` | масив | так | Поля списку — від 1 до 30 | | `fields[].name` | рядок | так | Назва поля, до 255 символів | | `fields[].slug` | рядок | так | Ім'я поля: літери, цифри, `-` і `_`, до 255 символів; краще латиницею. Не повторюється в межах списку й не збігається зі [службовими іменами](https://support.watbot.org/uk/api/lists#обмеження) | | `fields[].type` | рядок | так | Тип поля: `string`, `number`, `bool`, `date`, `datetime`, `money`, `file`, `image`, `contact`, `bot` | | `fields[].currency` | рядок | ні | Лише для `money`: трилітерний код валюти за ISO 4217 — `UAH`, `USD`, `EUR`. За замовчуванням `USD`. Невідомий код — `422` | | `fields[].is_required` | логічний | ні | Обов'язкове поле. За замовчуванням `true` | | `fields[].is_hidden` | логічний | ні | Приховати поле з інтерфейсу. За замовчуванням `false` | | `fields[].is_encryptable` | логічний | ні | Зберігати значення зашифрованим. За замовчуванням `false` | | `is_menu` | логічний | ні | Застаріла позначка, на роботу списку не впливає | ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/createListSchema" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "project_uuid": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c", "name": "Меню кафе", "fields": [ {"name": "Назва", "slug": "nazva", "type": "string"}, {"name": "Ціна", "slug": "tsina", "type": "money", "currency": "UAH"}, {"name": "Фото", "slug": "foto", "type": "image", "is_required": false}, {"name": "У наявності", "slug": "v_naiavnosti", "type": "bool", "is_required": false} ] }' ``` ```json title="Відповідь 201" { "data": { "id": "6650a1f2c3d4e5f6a7b8c9d0", "fields": { "nazva": { "name": "Назва", "type": "string", "is_required": true, "is_hidden": false, "is_encryptable": false }, "tsina": { "name": "Ціна", "type": "money", "is_required": true, "is_hidden": false, "is_encryptable": false, "currency": "UAH" }, "foto": { "name": "Фото", "type": "image", "is_required": false, "is_hidden": false, "is_encryptable": false }, "v_naiavnosti": { "name": "У наявності", "type": "bool", "is_required": false, "is_hidden": false, "is_encryptable": false } }, "name": "Меню кафе", "bot_id": null, "project": "3f2b8c1e-5a7d-4e9b-8c6f-1d2e3f4a5b6c", "is_menu": false, "created_at": "2026-10-03T08:00:00+00:00", "updated_at": "2026-10-03T08:00:00+00:00" } } ``` ```json title="Відповідь 422" { "message": "The slug is reserved.", "errors": { "fields.0.slug": ["The slug is reserved."] } } ``` Особливості й помилки: - Поля стають у список у тому порядку, у якому їх передано. - Створити список можна лише у своєму проєкті або своєму боті. Бот чи проєкт іншого акаунта, зокрема той, до якого вас запросили співробітником, — `403`. - `bot_id` або `project_uuid`, якого не існує, — `422`. - `slug`, що повторюється, — `422` з помилкою в полі `fields.N.slug`, де N — номер поля в масиві, починаючи з нуля. - Невідомий код валюти — `422` з помилкою в полі `fields.N.currency`. - У проєкті вже 5000 списків — `403`: `{"message": "A project cannot have more than 5000 lists", "error": "A project cannot have more than 5000 lists"}`. - У `GET`-запиті поля передаються в адресі так: `fields[0][name]=Назва&fields[0][slug]=nazva&fields[0][type]=string`. Зручніше надсилати `POST` із JSON. ## deleteListSchema Видаляє список разом із його записами. ```endpoint GET POST https://watbot.org/api/v1/deleteListSchema ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `schema_id` | рядок | так | Id списку | ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/deleteListSchema" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0"}' ``` ```json title="Відповідь 404" { "message": "Schema not found", "error": "Schema not found", "errors": { "schema_id": ["Schema not found"] } } ``` Успішна відповідь — код `204` без тіла. Особливості й помилки: - Перед видаленням перевірте, що список не вибрано в блоках ботів: після видалення блоки не знайдуть записів. - Після видалення записи списку не знаходяться ні в `getListItems`, ні за `item_id`: `updateListItem` і `deleteListItem` відповідають `404`. - Списку немає або його вже видалено — `404`, як у [`getListSchema`](#getlistschema). - Список із чужого проєкту — `403`. ## addListSchemaField Додає поле в кінець списку. ```endpoint GET POST https://watbot.org/api/v1/addListSchemaField ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `schema_id` | рядок | так | Id списку | | `field` | об'єкт | так | Нове поле | | `field.name` | рядок | так | Назва поля, до 255 символів | | `field.slug` | рядок | так | Ім'я поля: літери, цифри, `-` і `_`, до 255 символів; краще латиницею | | `field.type` | рядок | так | Тип поля — як у `createListSchema` | | `field.is_required` | логічний | ні | Обов'язкове поле. За замовчуванням `true` | | `field.is_hidden` | логічний | ні | Приховати поле з інтерфейсу. За замовчуванням `false` | | `field.is_encryptable` | логічний | ні | Зберігати значення зашифрованим. За замовчуванням `false` | | `field.currency` | рядок | для `money` | Лише для `money`: трилітерний код валюти за ISO 4217 — `UAH`, `USD`, `EUR` | ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/addListSchemaField" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "field": {"name": "Обʼєм, мл", "slug": "obiem", "type": "number", "is_required": false} }' ``` ```json title="Відповідь 422" { "message": "The list already has a field with this slug", "errors": { "field.slug": ["The list already has a field with this slug"] } } ``` Успішна відповідь — код `204` без тіла. Щоб побачити список із новим полем, викличте [`getListSchema`](#getlistschema). Особливості й помилки: - Поле з таким `slug` уже є — `422` з помилкою в `field.slug`. - Для поля `money` потрібна валюта `field.currency`: без неї або з невідомим кодом — `422` з помилкою в `field.currency`. - Якщо нове поле обов'язкове, його доведеться заповнювати під час кожного додавання запису. Записи, які вже є в списку, не змінюються. - Списку немає — `404`, як у [`getListSchema`](#getlistschema); список із чужого проєкту — `403`. ## deleteListSchemaField Видаляє поле зі списку й стирає його значення в усіх записах. ```endpoint GET POST https://watbot.org/api/v1/deleteListSchemaField ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `schema_id` | рядок | так | Id списку | | `slug` | рядок | так | Ім'я поля | ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/deleteListSchemaField" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "slug": "obiem"}' ``` ```json title="Відповідь 422" { "message": "Field not found", "errors": { "slug": ["Field not found"] } } ``` Успішна відповідь — код `204` без тіла. > [!WARNING] > Значення поля стираються в усіх записах одразу. Повернути їх не можна — так само, як під час [видалення поля в кабінеті](https://support.watbot.org/uk/lists/create#видалити-поле). Помилки: - Поля з таким `slug` немає — `422` з помилкою в `slug`. - Списку немає — `404`, як у [`getListSchema`](#getlistschema); список із чужого проєкту — `403`.