Списки и поля

Методы этой страницы работают со схемой списка — названием и полями. Как устроены поля и какие у них бывают типы, описано на странице Списки.

getListSchemas

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

GETPOSThttps://watbot.ru/api/v1/getListSchemas

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

Запрос

curl -X POST "https://watbot.ru/api/v1/getListSchemas" \
  -H "Authorization: Bearer ВАШ_КЛЮЧ" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{"page": 1}'

Ответ 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

Возвращает один список с полями.

GETPOSThttps://watbot.ru/api/v1/getListSchema

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

Запрос

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"}'

Ответ 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"
  }
}

Ответ 404

{
  "message": "Schema not found",
  "error": "Schema not found",
  "errors": {
    "schema_id": ["Schema not found"]
  }
}

Ошибки:

Списка нет или он удалён — 404. Текст ошибки — в error и message; для совместимости он же лежит в errors.schema_id.
Список из чужого проекта — 403.

createListSchema

Создаёт список с полями — в проекте или в боте.

GETPOSThttps://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 символов; лучше латиницей. Не повторяется внутри списка и не совпадает со служебными именами
`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`	логический	нет	Устаревшая отметка, на работу списка не влияет

Запрос

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}
    ]
  }'

Ответ 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"
  }
}

Ответ 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

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

GETPOSThttps://watbot.ru/api/v1/deleteListSchema

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

Запрос

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"}'

Ответ 404

{
  "message": "Schema not found",
  "error": "Schema not found",
  "errors": {
    "schema_id": ["Schema not found"]
  }
}

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

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

Перед удалением проверьте, что список не выбран в блоках ботов: после удаления блоки не найдут записей.
После удаления записи списка не находятся ни getListItems, ни по item_id: updateListItem и deleteListItem отвечают 404.
Списка нет или он уже удалён — 404, как в getListSchema.
Список из чужого проекта — 403.

addListSchemaField

Добавляет поле в конец списка.

GETPOSThttps://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`

Запрос

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}
  }'

Ответ 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.

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

Поле с таким slug уже есть — 422 с ошибкой у field.slug.
Для поля money нужна валюта field.currency: без неё или с неизвестным кодом — 422 с ошибкой у field.currency.
Если новое поле обязательное, его придётся заполнять при каждом добавлении записи. Записи, которые уже есть в списке, не меняются.
Списка нет — 404, как в getListSchema; список из чужого проекта — 403.

deleteListSchemaField

Удаляет поле из списка и стирает его значения во всех записях.

GETPOSThttps://watbot.ru/api/v1/deleteListSchemaField

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

Запрос

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"}'

Ответ 422

{
  "message": "Field not found",
  "errors": {
    "slug": ["Field not found"]
  }
}

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

Внимание

Значения поля стираются во всех записях сразу. Вернуть их нельзя — так же, как при удалении поля в кабинете.

Ошибки:

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

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

getListSchemas#

getListSchema#

createListSchema#

deleteListSchema#

addListSchemaField#

deleteListSchemaField#

Списки и поля

getListSchemas

getListSchema

createListSchema

deleteListSchema

addListSchemaField

deleteListSchemaField