# Записи Методи цієї сторінки працюють із записами списку. Значення полів передаються в об'єкті `data`: ключ — `slug` поля, значення — у форматі його типу. Формати всіх типів описано на сторінці [Списки](https://support.watbot.org/uk/api/lists#типи-полів). ## getListItems Повертає записи списку посторінково — з відбором за значеннями полів і сортуванням. ```endpoint GET POST https://watbot.org/api/v1/getListItems ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `schema_id` | рядок | так | Id списку | | `limit` | ціле число | ні | Записів на сторінці — від 1 до 1000, за замовчуванням 50 | | `page` | ціле число | ні | Номер сторінки, за замовчуванням `1` | | `order_by` | рядок | ні | Сортування: `slug` поля й напрямок через кому — `tsina,desc`. Напрямок — `asc` (за зростанням, за замовчуванням) або `desc`. Сортувати можна й за `created_at`, `updated_at`. Інше поле або напрямок — `422` | | `filters` | об'єкт | ні | Відбір за значеннями полів — див. нижче | | `contact_id` | ціле число | ні | Лише записи, прив'язані до цього контакту через поле типу `contact` | | `bot_id` | ціле число | ні | Лише записи, прив'язані до цього бота через поле типу `bot` | Наприклад, лате об'ємом від 250 мл, спершу найбільші: ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/getListItems" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "filters": {"obiem": ">=,250", "nazva": "like,%лате%"}, "order_by": "obiem,desc", "limit": 20 }' ``` ```json title="Відповідь 200" { "data": [ { "id": "6650b7a1c3d4e5f6a7b8c9e1", "created_at": "2026-10-03T08:05:00+00:00", "updated_at": "2026-10-03T08:05:00+00:00", "nazva": "Лате на вівсяному", "tsina": 85, "foto": { "type": "image", "mime_type": "image/jpeg", "created_at": null, "name": "latte.jpg", "size": 0, "storage": "url", "caption": null, "meta": {"width": null, "height": null, "duration": null, "codec": null}, "url": "https://example.com/menu/latte.jpg" }, "v_naiavnosti": true, "obiem": 350 } ], "links": { "first": "…/v1/getListItems?page=1", "last": "…/v1/getListItems?page=1", "prev": null, "next": null }, "meta": { "current_page": 1, "from": 1, "last_page": 1, "path": "…/v1/getListItems", "per_page": 20, "to": 1, "total": 1 } } ``` ```json title="Відповідь 422" { "message": "The limit field must not be greater than 1000.", "errors": { "limit": ["The limit field must not be greater than 1000."] } } ``` У кожному записі — `id`, `created_at`, `updated_at` і значення всіх полів списку, зокрема прихованих і зашифрованих (розшифрованими). Якщо запис прив'язано до контакту чи бота, у ньому є ще `contact_id` або `bot_id`. ### Відбір У `filters` ключ — `slug` поля, значення — одне з: - `"значення"` або просто значення з JSON — поле дорівнює значенню: `{"nazva": "Капучино"}`, `{"obiem": 300}`, `{"v_naiavnosti": true}`; - `"оператор,значення"` — порівняння: `{"obiem": ">=,250"}`. | Оператор | Значення | |---|---| | `=` | дорівнює | | `!=`, `<>` | не дорівнює | | `<`, `<=`, `>`, `>=` | менше, менше або дорівнює, більше, більше або дорівнює | | `like` | збігається із шаблоном: `%` — будь-які символи, `_` — один символ. Регістр не важливий. Без `%` значення має збігтися повністю | | `not like` | не збігається із шаблоном | Оператор розпізнається, лише якщо текст до першої коми — оператор із таблиці. Інакше весь рядок — значення: `{"nazva": "Раф, великий"}` знайде запис «Раф, великий». Якщо саме значення починається з оператора й коми, наприклад `">, 5"`, вкажіть оператор явно: `"=,>, 5"`. Умови за різними полями об'єднуються через «і». Як порівнюється значення, залежить від типу поля: | Тип поля | Значення у відборі | Оператори | |---|---|---| | `string` | Текст. Число з JSON порівнюється як текст | усі | | `number` | Число: `250`, `"250"`, `"4.5"` | усі, крім `like` і `not like` | | `money` | Сума в основних одиницях, як під час запису: `250` або `"199.99"` | усі, крім `like` і `not like` | | `bool` | `true`, `false`, `"true"`, `"false"`, `1`, `0` | `=`, `!=` | | `date` | Дата: `"2026-10-15"`. Порівнюється день за UTC: `"2026-10-15"` знайде й запис із датою 15 жовтня 14:30, `"<=,2026-10-15"` — усе до кінця цього дня | усі, крім `like` і `not like` | | `datetime` | Дата й час: `"2026-10-15 14:30"` або `"2026-10-15T14:30:00+03:00"`. Час без поясу — UTC | усі, крім `like` і `not like` | | `contact`, `bot` | Номер контакту або бота | усі, крім `like` і `not like` | Шаблон для `like` і `not like` — не довший за 255 символів і не більше ніж 10 знаків `%`; кілька `%` поспіль вважаються одним. Значення, яке не підходить полю (текст у полі `number`, `like` за сумою, об'єкт замість значення), — відповідь `422` з помилкою в `filters.`. Якщо `filters` — не об'єкт, помилка в `filters`. Умова пропускається без помилки, якщо поля з таким `slug` у списку немає, воно зашифроване, це файл або картинка, або значення — `null`. У `GET`-запиті відбір передається в адресі: `filters[obiem]=>=,250`. Спецсимволи кодуйте: `%` — як `%25`. ### Сторінки Скільки всього записів і сторінок — у `meta.total` і `meta.last_page`, адреса наступної сторінки — у `links.next` (`null` на останній). Без `order_by` порядок записів не визначено: під час обходу сторінками вказуйте сортування, наприклад `created_at`. Помилки: - Списку немає — `404`: `{"message": "Schema not found", "error": "Schema not found", "errors": {"schema_id": ["Schema not found"]}}`. - Список із чужого проєкту — `403`. ## addListItem Додає запис до списку. ```endpoint GET POST https://watbot.org/api/v1/addListItem ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `schema_id` | рядок | так | Id списку | | `data` | об'єкт | так | Значення полів: ключ — `slug`, значення — у форматі типу поля | ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/addListItem" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "data": { "nazva": "Капучино", "tsina": 65, "foto": { "url": "https://example.com/menu/cappuccino.jpg", "storage": "url", "name": "cappuccino.jpg", "type": "image" }, "v_naiavnosti": true, "obiem": 300 } }' ``` ```json title="Відповідь 201" { "data": { "id": "6650b7a1c3d4e5f6a7b8c9e2", "created_at": "2026-10-03T08:10:00+00:00", "updated_at": "2026-10-03T08:10:00+00:00", "nazva": "Капучино", "tsina": 65, "foto": { "type": "image", "mime_type": null, "created_at": null, "name": "cappuccino.jpg", "size": 0, "storage": "url", "caption": null, "meta": {"width": null, "height": null, "duration": null, "codec": null}, "url": "https://example.com/menu/cappuccino.jpg" }, "v_naiavnosti": true, "obiem": 300 } } ``` ```json title="Відповідь 422" { "message": "The data.nazva field is required.", "errors": { "data.nazva": ["The data.nazva field is required."] } } ``` Особливості й помилки: - Обов'язкові поля (`is_required: true`) треба заповнити, інакше `422`. Поля, яких немає в `data`, залишаються порожніми. Ключі, яких немає серед полів списку, ігноруються. - Значення не свого типу — `422` з помилкою в `data.`: наприклад, текст у полі `number` або номер контакту, якого не існує. - Контакт чужого бота або чужий бот у полях `contact` і `bot` — `403`. - Дати у відповіді — рядком в UTC, як у `getListItems`: `"2026-10-15T00:00:00.000000Z"`. - Списку немає — `404`, як у `getListItems`; список із чужого проєкту — `403`. ## updateListItem Змінює значення полів запису. Поля, яких немає в `data`, не змінюються. ```endpoint GET POST https://watbot.org/api/v1/updateListItem ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `item_id` | рядок | так | Id запису | | `data` | об'єкт | так | Нові значення полів: ключ — `slug`, значення — у форматі типу поля | Наприклад, нова ціна й позначка «немає в наявності»: ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/updateListItem" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "item_id": "6650b7a1c3d4e5f6a7b8c9e2", "data": {"tsina": 70, "v_naiavnosti": false} }' ``` ```json title="Відповідь 200" { "data": { "id": "6650b7a1c3d4e5f6a7b8c9e2", "created_at": "2026-10-03T08:10:00+00:00", "updated_at": "2026-10-03T09:30:00+00:00", "nazva": "Капучино", "tsina": 70, "foto": { "type": "image", "mime_type": null, "created_at": null, "name": "cappuccino.jpg", "size": 0, "storage": "url", "caption": null, "meta": {"width": null, "height": null, "duration": null, "codec": null}, "url": "https://example.com/menu/cappuccino.jpg" }, "v_naiavnosti": false, "obiem": 300 } } ``` ```json title="Відповідь 404" { "message": "Item not found", "error": "Item not found", "errors": { "item_id": ["Item not found"] } } ``` У відповіді — запис повністю. Особливості й помилки: - Перевіряються лише передані поля. Обов'язкове поле не можна передати порожнім — `422`. - Очистити поле цим методом не можна: `null` і порожнє значення пропускаються, поле зберігає попереднє значення. - Дати у відповіді — рядком в UTC, як у `getListItems`. - Запису немає, його видалено або видалено його список — `404`. Текст помилки — в `error` і `message`; для сумісності він же лежить у `errors.item_id`. - Запис зі списку чужого проєкту — `403`. ## deleteListItem Видаляє запис. ```endpoint GET POST https://watbot.org/api/v1/deleteListItem ``` | Параметр | Тип | Обов'язковий | Опис | |---|---|---|---| | `item_id` | рядок | так | Id запису | ```bash title="Запит" curl -X POST "https://watbot.org/api/v1/deleteListItem" \ -H "Authorization: Bearer ВАШ_КЛЮЧ" \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"item_id": "6650b7a1c3d4e5f6a7b8c9e2"}' ``` ```json title="Відповідь 404" { "message": "Item not found", "error": "Item not found", "errors": { "item_id": ["Item not found"] } } ``` Успішна відповідь — код `204` без тіла. Помилки: - Запису немає, його вже видалено або видалено його список — `404`, як в [`updateListItem`](#updatelistitem). - Запис зі списку чужого проєкту — `403`.