Bitrix24

Bitrix24 — единственный сервис стенда, у которого нет OpenAPI. Каталог собран разбором официальной документации, поэтому и покрытие, и его границы здесь выглядят иначе, чем у Ozon и Wildberries.

Откуда взята спецификация

Схемы ответа как типа в источнике нет ни у одного метода — её у Bitrix24 просто не публикуют. Поэтому яруса schema здесь не бывает: метод либо отдаёт пример из документации (example), либо пустой конверт (generic). Промежуточного состояния нет.

Что покрыто

На момент написания в каталоге 1685 методов, из них 1445 с примером ответа и 240 без. Числа живые и меняются с каждой волной пополнения — актуальные отдаёт /api/services и каталог.

Крупнейшие разделы: CRM, Торговый каталог, Интернет-магазин, Задачи, Сайты и магазины, Чаты и уведомления, Открытые линии, Диск, Телефония. Методы, помеченные в документации как устаревшие, в каталоге сохранены с флагом deprecated.

Особенности вызова

1. 1

   Имя метода лежит в пути, а не в теле

   /b24/rest/crm.deal.list.json. Суффикс .json или .xml шлюз отрезает до маршрутизации.

2. 2

   HTTP-глагол не имеет значения

   Документация разрешает звать один и тот же метод и через GET с query-параметрами, и через POST с JSON, и через form-urlencoded. Мок ведёт себя так же: GET /b24/rest/crm.deal.fields отвечает 200, хотя в каталоге метод записан как POST.

3. 3

   Ключ — там же, где у портала

   Путь входящего вебхука /rest/{user_id}/{code}/{method}.json, параметр auth= или поле auth в теле. Подробнее — Авторизация.

Есть и третий адрес: /rest/* в корне стенда. Он нужен приложениям, которые склеивают адрес из DOMAIN, — см. Адресацию.

Лимиты и ошибки

Портал отвечает на превышение 503 QUERY_LIMIT_EXCEEDED, а не 429, и не шлёт Retry-After. Ведро — 50 запросов при скорости около двух в секунду. Конверт ошибки — {"error": …, "error_description": …}:

GATEWAY_TIMEOUT — код шлюза, а не портала: у боевого Bitrix24 таймаут это отсутствие ответа, и кода ошибки для него не заведено.

Локальные приложения

Кроме ключа песочницы шлюз принимает OAuth-токен локального приложения: приложение, написанное для боя, приносит то, что получило при установке. Для таких запросов часть методов отвечает не из каталога, а из состояния портала: app.info, profile, user.current, scope, method.get, methods, server.time, access.name, placement.*, event.*. Такой ответ помечен X-APIStend-Source: app-context.

Там же работают вещи, которых у ключа песочницы нет: пакет batch, ошибка expired_token (401) на истёкшем токене и insufficient_scope (403), если у приложения нет нужного права.

Известные отличия от боя