REST API Битрикс24: с чего начать и какие есть лимиты
REST API нужен, когда данные должны ходить между Битрикс24 и чем-то ещё: сайтом, учётной системой, личным кабинетом, самописным сервисом. Разбирать весь справочник методов смысла нет, но несколько вещей стоит понимать до первой строки кода.
Вебхук или приложение
Вебхук — это адрес с ключом, который выпускается в портале и даёт доступ к выбранным разделам. Подходит, когда нужно связать конкретный портал с конкретным скриптом: выгрузить сделки, принять заявку с сайта, обновить остатки.
Приложение с авторизацией нужно, когда решением будут пользоваться разные компании или когда оно должно открываться внутри интерфейса портала. Там сложнее: регистрация, OAuth, обработка установки.
Ключ вебхука равносилен паролю от тех разделов, которые ему открыты. Его нельзя публиковать в репозитории и передавать в переписке, а при подозрении на утечку выпускают новый.
Лимиты, которые встретите первыми
Интенсивность запросов ограничена. На большинстве тарифов счётчик уменьшается со скоростью два запроса в секунду, на Энтерпрайзе пять, и есть порог, после которого портал начинает отвечать ошибкой. Считается лимит на каждый Битрикс24 отдельно, но приложения с одного адреса делят его между собой.
Один запрос выполняется не дольше минуты, дальше обрывается по таймауту. Списочные методы отдают по пятьдесят записей за раз, поэтому большие выборки читают постранично. Чтобы не тратить лимит на мелочи, вызовы собирают в пакет: в одном HTTP-запросе можно передать до пятидесяти команд.
Отдельно есть лимит операционного времени: портал считает, сколько суммарно работал конкретный метод, и при переборе временно его придерживает. В коробочной версии такой лимит по умолчанию выключен.
Что приходит при превышении
Слишком частые запросы дают ошибку с кодом QUERY_LIMIT_EXCEEDED и статусом 503. Лечится снижением частоты и повтором с растущей задержкой, а не повтором в цикле: параллельные серии с одного адреса делают только хуже.
Исчерпанное операционное время возвращает OPERATION_TIME_LIMIT со статусом 429. В ответе приходит отметка, когда счётчик начнёт освобождаться, и ориентироваться стоит на неё.
Чем помочь себе на старте
Нейросети уверенно придумывают методы, которых в API нет. Чтобы код писался по настоящей документации, подключите MCP-сервер Битрикс24. Если задача — собрать приложение для портала целиком, посмотрите в сторону Вайбкода: там агент получает документацию платформы сам.
Когда интеграция касается учётной системы, отдельная тема — обмен с 1С: там обычно хватает штатного коннектора, и писать своё по API не нужно.
Частые вопросы
Вебхук или приложение?
Вебхук проще: это адрес с ключом внутри, им удобно связать портал со своим скриптом. Приложение нужно, когда решением пользуется несколько порталов или когда оно встраивается в интерфейс. Ключ вебхука равносилен паролю, поэтому в публичный код его не кладут.
Сколько запросов в секунду можно делать?
На большинстве тарифов счётчик уменьшается со скоростью два запроса в секунду, на Энтерпрайзе пять. Кратковременный всплеск допустим, постоянное превышение приводит к ошибке.
Почему метод вдруг перестал отвечать, а остальные работают?
Похоже на лимит операционного времени: он считается отдельно для конкретного метода и конкретного приложения или вебхука. Остальные вызовы при этом продолжают работать.
