REST API Битрикс24: 10 лучших практик

REST API Битрикс24 мощный, но с особенностями. Собрали 10 практик, которые избавят от большинства проблем при интеграции.

1. Батч-запросы вместо одиночных

Метод batch позволяет выполнить до 50 запросов за одно обращение. Вместо 100 последовательных вызовов — 2 батча. В 50 раз быстрее и экономит rate limit.

2. Пагинация через start

Не используйте OFFSET — на больших коллекциях он медленный. Передавайте start=next из предыдущего ответа.

3. Выборка только нужных полей

Через параметр select — только нужные поля. Экономит трафик и память.

4. Webhook vs Application

Для внутренних интеграций — входящий webhook. Просто, быстро. Для публикации в Маркетплейсе — только Application с OAuth2.

5. Rate limits

2 запроса в секунду для входящих вебхуков, 50 для приложений. Превышение — 429. Ставьте throttling на своей стороне.

6. Обработка ошибок

Ошибки возвращаются в поле error. Экспоненциальный backoff при 429 и 500.

7. Не храните токены в коде

Токены — в секретах (Vault, AWS Secrets Manager, переменные окружения). Никогда в git.

8. Версионирование

Битрикс24 иногда добавляет новые поля, редко — меняет существующие. Тестируйте интеграцию после каждого обновления коробки.

9. Асинхронные задачи

Не вызывайте API синхронно из запроса пользователя. Используйте очереди.

10. Логируйте всё

Каждый вызов API — лог с correlation-id. Без этого дебажить интеграцию невозможно.