Интеграция шлёт в портал создание задачи, портал отвечает ошибкой. Дальше обычно начинается перебор: добавить прав вебхуку, поменять поля, переписать запрос. Перебор занимает часы, тогда как ответ портала почти всегда прямо называет класс поломки. Разберём, как его читать.
Минимальный рабочий вызов
С него стоит начинать любую диагностику: если он проходит, дело в ваших дополнительных полях, а не в доступе.
curl -X POST \
-H "Content-Type: application/json" \
-d '{"fields":{"TITLE":"Проверка REST","RESPONSIBLE_ID":1}}' \
"https://ПОРТАЛ.bitrix24.ru/rest/ID/ВЕБХУК/tasks.task.add"Обязательны объект fields, заголовок TITLE и исполнитель RESPONSIBLE_ID. Плюс все обязательные пользовательские поля, которые завели на конкретном портале — их состав у каждого свой. Идентификатор созданной задачи приходит в result.task.id.
Таблица ответов
| Что произошло | HTTP и код | Куда смотреть |
|---|---|---|
Не передан объект fields | 400, код 100 | В описании сказано, что параметр не найден |
| Нет заголовка или исполнителя | 400, ERROR_CORE | Конкретная причина в error_description |
| Исполнителя с таким ID нет | 400, ERROR_CORE | Описание сообщает, что пользователь не найден |
| Пустое обязательное пользовательское поле | 400, ERROR_CORE | Имя поля указано в описании |
| Вебхуку не выдан доступ к задачам | 403, insufficient_scope | Права самого вебхука |
| Доступ есть, прав у владельца нет | 403, INVALID_CREDENTIALS | Права сотрудника, от чьего имени работает вебхук |
| Неверный адрес или секрет | 401, NO_AUTH_FOUND | URL вебхука целиком |
| Слишком частые запросы | 503, QUERY_LIMIT_EXCEEDED | Нужны паузы с нарастанием |
| Метод исчерпал лимит ресурсоёмкости | 429, OPERATION_TIME_LIMIT | Метод блокируется примерно на десять минут |
Отдельно про ERROR_CORE: это общий код, по нему самому решение не принимается. Смысл лежит в error_description, и читать надо именно его.
Два разных 403
Это место путают чаще всего, а лечится оно противоположными способами.
insufficient_scope означает, что вебхуку не выдан доступ к инструменту «Задачи». Правится в настройках самого вебхука.
INVALID_CREDENTIALS означает, что доступ у вебхука есть, а вот у сотрудника, от чьего имени вебхук работает, нет прав на это действие в портале. Добавление новых галочек вебхуку здесь не поможет: проверять надо роль владельца. Простой тест — зайти в портал под этим сотрудником и попробовать создать такую же задачу руками. Если руками нельзя, то и через API нельзя.
Само по себе разрешение вебхука прав пользователю не добавляет. Вебхук действует от имени создавшего его человека и ограничен его правами.
Проверка, доступен ли метод
Прежде чем менять запрос, стоит спросить у портала, видит ли он метод и разрешён ли тот текущей авторизации:
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name":"tasks.task.add"}' \
"https://ПОРТАЛ.bitrix24.ru/rest/ID/ВЕБХУК/method.get"Читается так:
isExisting: false— опечатка в имени метода или метода нет на этом портале;isExisting: true,isAvailable: false— метод есть, но текущей авторизации недоступен, дело в правах вебхука;- оба
true— доступ в порядке, причина дальше: права владельца или сами данные задачи.
Этот способ надёжнее, чем ловить ответ на неизвестный метод: формат такого ответа в разных версиях REST различается.
Обязательные поля конкретного портала
Когда минимальный вызов проходит, а боевой падает с ERROR_CORE, почти всегда виноваты пользовательские поля, которые администратор сделал обязательными. Их список запрашивается у портала:
curl -X POST \
-H "Content-Type: application/json" \
-d '{}' \
"https://ПОРТАЛ.bitrix24.ru/rest/ID/ВЕБХУК/tasks.task.getFields"В ответе у каждого поля есть тип, признак обязательности и допустимые значения. Сверять свой запрос стоит именно с этим списком, а не с чужой статьёй: на другом портале набор полей другой.
Версии REST
Две версии живут одновременно и различаются адресом и форматом ошибок:
- v2: путь вида
/rest/{пользователь}/{вебхук}/{метод}, принимает JSON и form-data; - v3: путь вида
/rest/api/{пользователь}/{вебхук}/{метод}, только JSON и другой формат ошибок.
Смешивать их в одной интеграции — источник ошибок, которые выглядят необъяснимо. Проверьте, какой путь у вас в коде.
Порядок действий
- Записать в лог HTTP-статус, поле
errorиerror_descriptionцеликом. Без этого дальше идёт гадание. - Проверить имя метода через
method.get. - При 403 определить, какой именно: права вебхука или права владельца.
- Запросить схему через
tasks.task.getFields. - Выполнить минимальный вызов с двумя полями.
- Добавлять остальные поля по одному, пока не появится ошибка.
- На 503 — паузы с нарастанием; на 429 — прекратить вызовы этого метода до снятия блокировки.
Что стоит держать в голове
- Локализованный текст ошибки меняется, сравнивать в коде надо машинный код, а не сообщение на русском.
- Создание задачи — изменяющая операция. Слепой повтор после сетевого таймаута создаёт дубль, документированного ключа идемпотентности у метода нет. Повтор стоит делать с проверкой, не создалась ли задача.
- URL вебхука содержит секрет. Он не должен попадать в публичные логи, скриншоты и репозиторий.
- Воспроизводить лимиты на рабочем портале не нужно: блокировка метода затронет живые процессы.
Если разбираться некогда
Пришлите в Telegram тело ответа портала и запрос с замазанным секретом — по ним причина обычно называется сразу. Настройка и починка интеграций — услуга интеграций, связка сайта с порталом — сайт и CRM.
Смежное: порядок выдачи прав вебхуку по шагам — в статье как подключить бота к Bitrix24. Когда портал отвечает нормально, а ломается сам бот, смотрите разборы кнопки не срабатывают и бот не видит сообщения. Готовое решение без разработки — бот для Bitrix24.
