# Записи

Методы этой страницы работают с записями списка. Значения полей передаются в объекте `data`: ключ — `slug` поля, значение — в формате его типа. Форматы всех типов описаны на странице [Списки](https://support.watbot.ru/api/lists#типы-полей).

## getListItems

Возвращает записи списка постранично — с отбором по значениям полей и сортировкой.

```endpoint
GET POST https://watbot.ru/api/v1/getListItems
```

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `schema_id` | строка | да | Id списка |
| `limit` | целое | нет | Записей на странице — от 1 до 1000, по умолчанию 50 |
| `page` | целое | нет | Номер страницы, по умолчанию `1` |
| `order_by` | строка | нет | Сортировка: `slug` поля и направление через запятую — `price,desc`. Направление — `asc` (по возрастанию, по умолчанию) или `desc`. Можно сортировать и по `created_at`, `updated_at`. Другое поле или направление — `422` |
| `filters` | объект | нет | Отбор по значениям полей — см. ниже |
| `contact_id` | целое | нет | Только записи, привязанные к этому контакту через поле типа `contact` |
| `bot_id` | целое | нет | Только записи, привязанные к этому боту через поле типа `bot` |

Например, латте объёмом от 250 мл, сначала самые большие:

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/getListItems" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "filters": {"volume": ">=,250", "nazvanie": "like,%латте%"},
    "order_by": "volume,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",
      "nazvanie": "Латте на овсяном",
      "price": 290,
      "photo": {
        "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"
      },
      "in_stock": true,
      "volume": 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 — поле равно значению: `{"nazvanie": "Капучино"}`, `{"volume": 300}`, `{"in_stock": true}`;
- `"оператор,значение"` — сравнение: `{"volume": ">=,250"}`.

| Оператор | Значение |
|---|---|
| `=` | равно |
| `!=`, `<>` | не равно |
| `<`, `<=`, `>`, `>=` | меньше, меньше или равно, больше, больше или равно |
| `like` | совпадает с шаблоном: `%` — любые символы, `_` — один символ. Регистр не важен. Без `%` значение должно совпасть целиком |
| `not like` | не совпадает с шаблоном |

Оператор узнаётся, только если текст до первой запятой — оператор из таблицы. Иначе вся строка — значение: `{"nazvanie": "Раф, большой"}` найдёт запись «Раф, большой». Если само значение начинается с оператора и запятой, например `">, 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.<slug>`. Если `filters` — не объект, ошибка у `filters`.

Условие пропускается без ошибки, если поля с таким `slug` нет в списке, оно зашифровано, это файл или картинка, или значение — `null`.

В `GET`-запросе отбор передаётся в адресе: `filters[volume]=>=,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`.
- Неверные `order_by` или `filters` — `422`.

## addListItem

Добавляет запись в список.

```endpoint
GET POST https://watbot.ru/api/v1/addListItem
```

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `schema_id` | строка | да | Id списка |
| `data` | объект | да | Значения полей: ключ — `slug`, значение — в формате типа поля |

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/addListItem" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "data": {
      "nazvanie": "Капучино",
      "price": 250,
      "photo": {
        "url": "https://example.com/menu/cappuccino.jpg",
        "storage": "url",
        "name": "cappuccino.jpg",
        "type": "image"
      },
      "in_stock": true,
      "volume": 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",
    "nazvanie": "Капучино",
    "price": 250,
    "photo": {
      "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"
    },
    "in_stock": true,
    "volume": 300
  }
}
```

```json title="Ответ 422"
{
  "message": "The data.nazvanie field is required.",
  "errors": {
    "data.nazvanie": ["The data.nazvanie field is required."]
  }
}
```

Особенности и ошибки:

- Обязательные поля (`is_required: true`) нужно заполнить, иначе `422`. Поля, которых нет в `data`, остаются пустыми. Ключи, которых нет среди полей списка, игнорируются.
- Значение не своего типа — `422` с ошибкой у `data.<slug>`: например, текст в поле `number` или несуществующий номер контакта.
- Контакт чужого бота или чужой бот в полях `contact` и `bot` — `403`.
- Даты в ответе — строкой в UTC, как в `getListItems`: `"2026-10-15T00:00:00.000000Z"`.
- Списка нет — `404`, как в `getListItems`; список из чужого проекта — `403`.

## updateListItem

Меняет значения полей записи. Поля, которых нет в `data`, не меняются.

```endpoint
GET POST https://watbot.ru/api/v1/updateListItem
```

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `item_id` | строка | да | Id записи |
| `data` | объект | да | Новые значения полей: ключ — `slug`, значение — в формате типа поля |

Например, новая цена и отметка «нет в наличии»:

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/updateListItem" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id": "6650b7a1c3d4e5f6a7b8c9e2",
    "data": {"price": 270, "in_stock": 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",
    "nazvanie": "Капучино",
    "price": 270,
    "photo": {
      "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"
    },
    "in_stock": false,
    "volume": 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.ru/api/v1/deleteListItem
```

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `item_id` | строка | да | Id записи |

```bash title="Запрос"
curl -X POST "https://watbot.ru/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`.