Правила и ограничения bot API

Правила доступа

• Bot API доступен только пользователю с ролью BOT
• Авторизация: Authorization: Bearer <token>
• Если токен валиден, но пользователь не BOT, API возвращает 403 Bot token required
• Если пользователь не найден, возвращается 401 User not found
• Если токен невалидный, возвращается 401 Invalid token
• Если токен истек, возвращается 401 Token has expired

Бот работает только в рамках accesses пользователя.
Для создания проверяется доступ к form_id.
Для чтения и апдейта доступ проверяется по task.form_id.

Дополнительное правило по доступам:

• один бот может иметь доступ максимум к 2 формам
• если нужен доступ к большему числу форм, нужно создать еще одного бота, выдать ему отдельный token и назначить ему доступы на нужные формы

Поддерживаемые типы полей

Поддерживаются:

• TextField
• TextareaField
• NumberField
• ChoiceField
• DateField
• DueDateField
• PhoneField
• EmailField
• FormField
• TableField

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

• PATCH /bot/tasks/{task_id}/items/{form_field_id} обновляет одно поле, поэтому TableField через этот endpoint не обновляется
• Для таблиц поддерживаются child items только типов: TextField, NumberField, ChoiceField, EmailField, PhoneField, DateField, DueDateField, FormField
• TextareaField внутри таблицы не допускается
• FilesField и TimeTrackerField в bot API create/update сейчас не поддерживаются и дают 400 Unsupported field type for bot create: ...

Лимиты payload и файлов

• JSON payload:
  • create task: 128 KB
  • update item: 32 KB
• Upload file size:
  • 20 MB на файл

При превышении JSON-лимита API возвращает 413 Payload too large. Max size is ... bytes.
При слишком большом файле upload возвращает 400 File too large. Up to 20MB allowed.

Максимумы

• participants_ids <= 5
• task_items <= 50
• files <= 10
• table rows <= 100
• row items <= 15

Типовые сообщения ошибок:

• participants_ids limit exceeded: 5
• task_items limit exceeded: 50
• files limit exceeded: 10
• table rows limit exceeded for field {form_field_id}: 100
• table row items limit exceeded: 15

Rate limits

• create: 30/min
• update item: 120/min
• upload: 10/min
• read: 300/min

При превышении возвращается 429 Rate limit exceeded. Retry after {seconds} seconds.

Если бизнесу нужен больший throughput, практический вариант в текущей модели - создать второго bot-пользователя и использовать отдельный token.

Валидация данных

• TextField, EmailField, PhoneField, FormField: строка до 1 KB, \x00 удаляется
• TextareaField: строка до 30 KB, \x00 удаляется
• ChoiceField: только list или null
• NumberField: число или numeric string, нормализуется под DECIMAL(15,5), округляется до 5 знаков
• DateField / DueDateField: ожидают корректный ISO datetime string

Точные ошибки валидации:

• value must be a string
• value must be a list or null
• choice values must contain only strings or null
• invalid numeric value: ...
• numeric value exceeds DECIMAL(15,5) max: 9999999999.99999
• value must be an ISO datetime string
• invalid datetime value: ...

Ответственные

Для форм со steps:

• responsible_ids обязателен
• bot user не может быть ответственным
• валидируются только активные не-BOT пользователи с доступом к форме
• если валидных пользователей нет, возвращается 400 Responsible users are invalid for this form

Для форм без steps отдельные назначения не требуются.

Типовые ошибки

• 403 Form access not found
• 400 responsible_ids is required for forms with steps
• 400 Responsible users are invalid for this form
• 400 Bot already has access to 2 forms. Create another bot or remove access from another form.
• 404 Form not found
• 404 Task not found
• 400 Form field {id} not found
• 404 Form field not found
• 400 Field {id} type mismatch: expected ..., got ...
• 400 Table child field {id} not found
• 400 Files not found: [...]
• 400 File extension is not allowed: ...
• 400 Invalid file content type for .ext: ...