Как выполняется запрос

Обращение к REST API Битрикс24 строится на HTTP-запросах. Ниже описано, как устроен запрос к методу, какие HTTP-методы и форматы данных поддерживаются и в каком виде приходит ответ. Вопросы авторизации, пакетных вызовов и кодирования данных вынесены на отдельные страницы. После прочтения вы сможете сформировать запрос к любому методу и выбрать формат ответа.

Структура запросаСтруктура запроса

Запрос к методу REST API — это HTTP-запрос по определенному адресу конкретного Битрикс24 вида

        https://your-domain.bitrix24.com/rest/method-name?param1=value1&param2=value2....
        
        

В реальном запросе, помимо параметров метода, передаются авторизационные данные — код входящего вебхука или OAuth-токен приложения. Без них запрос будет отклонен.

Полный вид адреса зависит от способа авторизации:

• вебхук — идентификатор пользователя и секретный код встроены в путь: https://your-domain.bitrix24.com/rest/USER_ID/WEBHOOK_CODE/method
• OAuth-токен — передается в параметре auth запроса: https://your-domain.bitrix24.com/rest/method?auth=ACCESS_TOKEN

Простые запросы можно отправлять через GET. Для передачи массивов и вложенных структур используйте POST с телом в формате JSON — этот способ поддерживает большинство методов. Все методы также принимают запросы GET и POST в формате multipart/form-data. Специальные символы в параметрах нужно кодировать — иначе они могут нарушить структуру URL, и результат окажется неверным.

В ответ на запрос REST API возвращает значимые данные или информацию об ошибке. Рекомендуем попробовать выполнить простой запрос перед тем, как вы начнете глубже знакомиться с REST API Битрикс24.

Заголовки запросаЗаголовки запроса

Для POST-запросов с телом в формате JSON передавайте заголовки:

• Content-Type: application/json — сообщает формат тела запроса
• Accept: application/json — запрашивает ответ в формате JSON
• User-Agent: имя-интеграции/версия — помогает Битрикс24 и промежуточным серверам корректно определить HTTP-клиент

Для GET-запросов без тела Content-Type не нужен. Передавайте Accept: application/json, если ожидаете ответ метода в формате JSON.

Если метод вернул подписанную ссылку на скачивание файла, например DOWNLOAD_URL или urlMachine, скачивайте файл отдельным GET-запросом. В таком запросе передавайте заголовки:

• User-Agent: имя-интеграции/версия
• Accept: */* или MIME-тип ожидаемого файла
• Accept-Language: ru-RU,ru;q=0.9,en;q=0.8
• Referer: https://your-domain.bitrix24.com/

Не изменяйте параметры авторизации и токены в подписанной ссылке. Если сервер вернул заголовок Content-Disposition с именем файла, но тело ответа содержит 404 от Nginx, проверьте, что HTTP-клиент передает заголовки для скачивания файла и не заменяет User-Agent на пустое или техническое значение.

Результат запросаРезультат запроса

Формат ответа по умолчанию — JSON, однако при необходимости можно получить ответ в формате XML. Для этого к названию метода добавьте желаемый формат: .json или .xml.

JSON — рекомендуемый формат ответа: дописывать .json к названию метода не нужно, а сам формат удобно разбирать в большинстве языков программирования. Формат XML выбирайте только тогда, когда этого требует принимающая сторона — например, для legacy-интеграций или парсеров, работающих исключительно с XML.

Разницу форматов удобно увидеть на примере метода batch — он выполняет пакет запросов за один вызов. Один и тот же запрос возвращает результат в JSON или XML в зависимости от расширения в названии метода:

{
            "result": {
                "result": {
                    "get_user": {
                        "ID": "1",
                        "NAME": "Иван",
                        "LAST_NAME": "Петров"
                    }
                }
            }
        }
        

<response>
            <result>
                <result>
                    <get_user>
                        <ID>1</ID>
                        <NAME>Иван</NAME>
                        <LAST_NAME>Петров</LAST_NAME>
                    </get_user>
                </result>
            </result>
        </response>
        

Здесь приведены только ключевые поля ответа. Полную структуру результата batch — с полями result_error, result_total, result_next и временем выполнения — и разбор параметров метода смотрите на странице batch.