# Списки и поля

Методы этой страницы работают со схемой списка — названием и полями. Как устроены поля и какие у них бывают типы, описано на странице [Списки](https://support.watbot.ru/api/lists#типы-полей).

## getListSchemas

Возвращает списки всех проектов, владелец которых — хозяин ключа, по 50 на страницу.

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

| Параметр | Тип | Обязательный | Описание |
|---|---|---|---|
| `page` | целое | нет | Номер страницы, по умолчанию `1` |

```bash title="Запрос"
curl -X POST "https://watbot.ru/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": {
        "nazvanie": {
          "name": "Название",
          "type": "string",
          "is_required": true,
          "is_hidden": false,
          "is_encryptable": false
        },
        "price": {
          "name": "Цена",
          "type": "money",
          "currency": "RUB",
          "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.ru/api/v1/getListSchema
```

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

```bash title="Запрос"
curl -X POST "https://watbot.ru/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": {
      "nazvanie": {
        "name": "Название",
        "type": "string",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      },
      "price": {
        "name": "Цена",
        "type": "money",
        "currency": "RUB",
        "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.ru/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.ru/api/lists#ограничения) |
| `fields[].type` | строка | да | Тип поля: `string`, `number`, `bool`, `date`, `datetime`, `money`, `file`, `image`, `contact`, `bot` |
| `fields[].currency` | строка | нет | Только для `money`: трёхбуквенный код валюты по ISO 4217 — `RUB`, `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.ru/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": "nazvanie", "type": "string"},
      {"name": "Цена", "slug": "price", "type": "money", "currency": "RUB"},
      {"name": "Фото", "slug": "photo", "type": "image", "is_required": false},
      {"name": "В наличии", "slug": "in_stock", "type": "bool", "is_required": false}
    ]
  }'
```

```json title="Ответ 201"
{
  "data": {
    "id": "6650a1f2c3d4e5f6a7b8c9d0",
    "fields": {
      "nazvanie": {
        "name": "Название",
        "type": "string",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false
      },
      "price": {
        "name": "Цена",
        "type": "money",
        "is_required": true,
        "is_hidden": false,
        "is_encryptable": false,
        "currency": "RUB"
      },
      "photo": {
        "name": "Фото",
        "type": "image",
        "is_required": false,
        "is_hidden": false,
        "is_encryptable": false
      },
      "in_stock": {
        "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]=nazvanie&fields[0][type]=string`. Удобнее отправлять `POST` с JSON.

## deleteListSchema

Удаляет список вместе с его записями.

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

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

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

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/addListSchemaField" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "schema_id": "6650a1f2c3d4e5f6a7b8c9d0",
    "field": {"name": "Объём, мл", "slug": "volume", "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.ru/api/v1/deleteListSchemaField
```

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

```bash title="Запрос"
curl -X POST "https://watbot.ru/api/v1/deleteListSchemaField" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"schema_id": "6650a1f2c3d4e5f6a7b8c9d0", "slug": "volume"}'
```

```json title="Ответ 422"
{
  "message": "Field not found",
  "errors": {
    "slug": ["Field not found"]
  }
}
```

Успешный ответ — код `204` без тела.

> [!WARNING]
> Значения поля стираются во всех записях сразу. Вернуть их нельзя — так же, как при [удалении поля в кабинете](https://support.watbot.ru/lists/create#удалить-поле).

Ошибки:

- Поля с таким `slug` нет — `422` с ошибкой у `slug`.
- Списка нет — `404`, как в [`getListSchema`](#getlistschema); список из чужого проекта — `403`.