Документация API: зачем нужна и как её использовать
Интеграция без документации — это гадание. Разработчик пробует метод, получает ошибку, ищет причину в интернете, находит устаревший пример на форуме, тратит день. В Битрикс24 документация REST API — это не «справочник на всякий случай», а рабочий инструмент, без которого невозможно построить надёжную интеграцию.
В 2027 году документация стала ещё важнее: REST 3.0 добавил OpenAPI-спецификацию. Это машиночитаемое описание API, которое можно использовать для генерации клиентов, проверки запросов и построения интерактивной документации. Больше не нужно вручную выяснять, какие поля доступны для связи, какие операторы поддерживает фильтр и какой формат ошибки вернёт метод.
В этой статье — как работает документация REST API Битрикс24, зачем нужна OpenAPI-спецификация, как её использовать и почему без документации интеграция умирает. Если нужна разработка интеграции с документированием — поможем.
Зачем документация
Документация решает три задачи: понять, что можно, как это сделать и что делать, если не работает.
Что можно
Список методов, их параметры, ограничения. Без этого разработчик не знает, с чего начать.
Как это сделать
Примеры запросов и ответов, форматы данных, авторизация. Это экономит часы проб и ошибок.
Что делать, если не работает
Коды ошибок, их причины и способы исправления. Без этого интеграция «умирает» при первой проблеме.
Что изменилось
Версии API, устаревшие методы, новые возможности. Без этого интеграция ломается при обновлении.
Если документации нет или она устарела, разработчик тратит время на реверс-инжиниринг. А бизнес теряет деньги, потому что интеграция не работает или работает неправильно.
OpenAPI
OpenAPI — это спецификация, которая описывает REST API в машиночитаемом формате. В Битрикс24 она появилась в REST 3.0.
Что это даёт
- Генерация клиентов — можно автоматически создать SDK для любого языка;
- Проверка запросов — инструменты могут проверить, соответствует ли запрос спецификации;
- Интерактивная документация — Swagger UI и аналогичные инструменты строят документацию на основе OpenAPI;
- Единый источник правды — спецификация обновляется вместе с API, а не отдельно.
Где найти
В документации REST 3.0 OpenAPI упоминается как способ узнать, какие связи и поля поддерживаются. Спецификация доступна в `apidocs.bitrix24.ru` и на GitHub.
💡 Важно
OpenAPI в REST 3.0 пока покрывает не все модули. Если метода нет в спецификации — используйте старую версию API и её документацию.
Поля и связи
В REST 3.0 можно запрашивать поля связанных объектов через точку в `select`. Но чтобы это работало, нужно знать, какие связи и поля существуют.
Как узнать
- OpenAPI-документация — машиночитаемое описание, где перечислены все поля и связи;
- Методы `*.field.list` — возвращают список полей для объекта;
- Методы `*.field.get` — возвращают описание конкретного поля.
Пример
Чтобы получить имя и email ответственного в задаче, в `select` указывается `["responsible.name", "responsible.email"]`. Если указать несуществующее поле связанного объекта — вернётся ошибка `BITRIX_REST_V3_EXCEPTION_UNKNOWNDTOPROPERTYEXCEPTION` с указанием, какого поля не хватает.
А если указать несуществующее поле самого объекта — ошибки не будет. Поле просто не попадёт в ответ. Это важно: проверяйте ответ, если ожидаемое поле отсутствует.
Ошибки
REST 3.0 использует единый формат ошибок с префиксом `BITRIX_REST_V3_EXCEPTION_`. Это упрощает обработку: разработчик сразу видит, что пошло не так.
| Код | HTTP | Причина |
|---|---|---|
VALIDATION_REQUESTVALIDATIONEXCEPTION | 400 | Не заполнено обязательное поле или значение не соответствует типу |
INVALIDJSONEXCEPTION | 400 | Тело запроса — не валидный JSON |
UNKNOWNDTOPROPERTYEXCEPTION | 400 | В `filter` или `select` указано несуществующее поле |
UNKNOWNFILTEROPERATOREXCEPTION | 400 | Несуществующий оператор в фильтре |
ENTITYNOTFOUNDEXCEPTION | 400 | Объект с переданным ID не найден |
ACCESSDENIEDEXCEPTION | 403 | У пользователя нет прав на объект |
INSUFFICIENTSCOPEEXCEPTION | 403 | У вебхука или приложения нет нужного scope |
Знание этих кодов экономит время. Вместо «что-то пошло не так» разработчик видит конкретную причину и исправляет её.
method.get и scope
Помимо документации, в Битрикс24 есть методы, которые помогают проверить API программно.
method.get
Показывает, существует ли метод и доступен ли он приложению. Это полезно, если вы не уверены, поддерживается ли нужный метод в вашей версии API .
scope
Возвращает список скоупов, которые выданы приложению или вебхуку. Если метод возвращает ошибку `insufficient_scope` — проверьте, есть ли нужный скоуп .
Зачем это нужно
Документация может быть большой и не всегда очевидной. Эти методы дают быстрый ответ: «работает ли это в моём случае». Они не заменяют документацию, но дополняют её.
Поддержка документации
Документация — это не «написали и забыли». API меняется, и документация должна меняться вместе с ним. Иначе она становится вредной: разработчик следует устаревшим примерам и получает ошибки.
Что делать
- Хранить документацию рядом с кодом — в том же репозитории, чтобы изменения были видны;
- Обновлять при изменении API — в том же pull request, а не «потом»;
- Генерировать из OpenAPI — если спецификация обновляется, документация обновляется автоматически;
- Тестировать примеры — если пример не работает, документация врёт.
💡 Важно
Устаревшая документация хуже, чем её отсутствие. Разработчик тратит время на «фантомные» ошибки, которые уже исправлены в API, но не в примерах.
Наши рекомендации
Что вы получаете, заказывая разработку у нас
- Документацию — для вашей интеграции
- OpenAPI-спецификацию — если нужна
- Примеры запросов — рабочие, проверенные
- Описание ошибок — с причинами и решениями
- Поддержку — после запуска
📌 Итоговый вывод
Документация — это не «приложение к API», а его часть. Без неё интеграция превращается в реверс-инжиниринг.
Что нужно знать:
- OpenAPI в REST 3.0: машиночитаемая спецификация для генерации и проверки ;
- Поля и связи: `*.field.list` и `*.field.get` показывают, что доступно ;
- Ошибки: единый формат с префиксом `BITRIX_REST_V3_EXCEPTION_` ;
- method.get и scope: проверка доступности метода и скоупов ;
- Поддержка: документация должна обновляться вместе с API .
Также рекомендуем: API, методы REST API, авторизация, все статьи об API.