{"name":"Битрикс24 REST API","vendor":"Битрикс24","industry":"crm","summary":"REST API облачного и коробочного Битрикс24: CRM (лиды, сделки, контакты, компании, смарт-процессы), задачи, пользователи, события и многое другое. Методы вызываются HTTP-запросом к адресу конкретного портала и выполняются от имени пользователя с его правами. Для CRM основной набор — универсальные методы `crm.item.*`, которые работают с любым типом объекта через `entityTypeId`.","docsUrl":"https://apidocs.bitrix24.ru/","coverage":{"included":[],"excluded":[]},"scenarios":[{"id":"sozdat-sdelku-s-kontaktom-iz-zayavki","title":"Создать сделку с контактом из заявки на сайте","summary":"Заявка с сайта превращается в контакт и сделку, привязанную к нему, — менеджер сразу видит её в воронке.","steps":["Создай входящий вебхук в Битрикс24 (Разработчикам → Другое → Входящий вебхук) со скоупом crm. Адрес вида https://<портал>.bitrix24.ru/rest/<id пользователя>/<код>/ — это пароль, храни его только на сервере.","Создай контакт: crm.item.add с entityTypeId = 3 и полями name, lastName, phone, email. Запомни id из result.item.","Создай сделку: crm.item.add с entityTypeId = 2, title, opportunity, currencyId и contactIds = [id контакта]. stageId и categoryId задают стадию и воронку; по умолчанию — первая стадия основной воронки.","Чтобы сделать оба вызова за один HTTP-запрос, отправь их через batch: результат первой команды подставляется во вторую как $result[contact][item][id].","Ошибку проверяй по полям error и error_description в ответе, а не по HTTP-статусу."],"code":"HOOK='https://<портал>.bitrix24.ru/rest/<id пользователя>/<код вебхука>'\n\n# Контакт и сделка одним запросом\ncurl -X POST \"$HOOK/batch.json\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"halt\": 1,\n        \"cmd\": {\n          \"contact\": \"crm.item.add?entityTypeId=3&fields[name]=Иван&fields[lastName]=Петров&fields[phone][0][value]=%2B79990001122&fields[phone][0][valueType]=WORK\",\n          \"deal\": \"crm.item.add?entityTypeId=2&fields[title]=Заявка с сайта&fields[opportunity]=15000&fields[currencyId]=RUB&fields[contactIds][0]=$result[contact][item][id]\"\n        }\n      }'","language":"bash","methods":["crm.item.add","batch"]},{"id":"vygruzit-vse-sdelki-na-nuzhnoy-stadii","title":"Выгрузить все сделки на нужной стадии","summary":"Забрать сделки из Битрикс24 в свою аналитику или учётную систему.","steps":["Запроси список: crm.item.list с entityTypeId = 2, filter (например, по stageId или по дате изменения) и select с нужными полями — так ответ будет легче.","Страница всегда содержит 50 записей. Следующую получай с параметром start = 50, 100 и так далее, пока в ответе есть next.","Для больших выгрузок собирай до 50 вызовов crm.item.list с разными start в один batch — это в десятки раз быстрее отдельных запросов.","Учитывай лимит частоты: на обычных тарифах — примерно 2 запроса в секунду. При превышении приходит HTTP 503 с QUERY_LIMIT_EXCEEDED — подожди и повтори."],"code":"curl -X POST \"$HOOK/crm.item.list.json\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"entityTypeId\": 2,\n        \"select\": [\"id\", \"title\", \"stageId\", \"opportunity\", \"currencyId\", \"contactIds\", \"updatedTime\"],\n        \"filter\": {\"stageId\": \"WON\", \">=updatedTime\": \"2026-01-01T00:00:00+03:00\"},\n        \"order\": {\"id\": \"ASC\"},\n        \"start\": 0\n      }'","language":"bash","methods":["crm.item.list","batch"]},{"id":"perevesti-sdelku-na-stadiyu-i-postavit","title":"Перевести сделку на стадию и поставить задачу менеджеру","summary":"Когда в твоей системе что-то произошло (оплата, отгрузка), сдвинуть сделку и напомнить ответственному.","steps":["Узнай коды стадий: crm.item.fields с entityTypeId = 2 покажет поля, а список стадий воронки виден в настройках CRM (например, NEW, PREPARATION, WON или C1:NEW для дополнительной воронки).","Переведи сделку: crm.item.update с entityTypeId = 2, id сделки и fields.stageId. Если значения не изменились, сохранения не будет; после сохранения запускаются роботы стадии.","Поставь задачу: tasks.task.add с TITLE и RESPONSIBLE_ID (обычно assignedById сделки). Чтобы задача была видна в карточке сделки, передай UF_CRM_TASK = [\"D_<id сделки>\"]. Для вебхука нужен скоуп task."],"code":"curl -X POST \"$HOOK/crm.item.update.json\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"entityTypeId\": 2, \"id\": 342, \"fields\": {\"stageId\": \"PREPARATION\"}}'\n\ncurl -X POST \"$HOOK/tasks.task.add.json\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\n        \"fields\": {\n          \"TITLE\": \"Позвонить клиенту: оплата получена\",\n          \"RESPONSIBLE_ID\": 6,\n          \"DEADLINE\": \"2026-11-01T18:00:00+03:00\",\n          \"UF_CRM_TASK\": [\"D_342\"]\n        }\n      }'","language":"bash","methods":["crm.item.update","crm.item.fields","tasks.task.add"]},{"id":"zapolnit-polzovatelskie-polya-sdelki","title":"Заполнить пользовательские поля сделки","summary":"У каждого портала свои поля (UF_CRM_…): источник заявки, номер договора, ссылка на заказ. Узнать их имена и записать значения.","steps":["Получи список полей: crm.item.fields с entityTypeId = 2. Пользовательские поля в crm.item.* называются в camelCase, например ufCrm1700000000; с useOriginalUfNames = Y — как в интерфейсе, UF_CRM_1700000000.","Посмотри в ответе тип поля, isRequired и isMultiple: множественное поле принимает массив, список — id варианта, а не текст.","Запиши значения: crm.item.update с fields, где ключи — имена полей из шага 1. При создании сделки те же поля передаются в crm.item.add."],"code":"curl -X POST \"$HOOK/crm.item.fields.json\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"entityTypeId\": 2}'\n\ncurl -X POST \"$HOOK/crm.item.update.json\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"entityTypeId\": 2, \"id\": 342, \"fields\": {\"ufCrm1700000000\": \"Договор № 15/2026\"}}'","language":"bash","methods":["crm.item.add","crm.item.update","crm.item.fields"]},{"id":"poluchat-uvedomleniya-o-novyh-lidah","title":"Получать уведомления о новых лидах","summary":"Реагировать на появление лида в Битрикс24 сразу: отправить приветственное письмо, записать в свою базу.","steps":["Подписка на события работает только в приложении (OAuth), не во входящем вебхуке — вебхук вернёт WRONG_AUTH_TYPE. Создай локальное приложение на портале.","Зарегистрируй обработчик: event.bind с event = ONCRMLEADADD и handler — адрес твоего сервера (с доменом, localhost не принимается).","Битрикс24 пришлёт POST-запрос с data[FIELDS][ID] — id нового лида. Проверь application_token из запроса, чтобы отсечь чужие вызовы.","Получи сам лид: crm.item.get с entityTypeId = 1 и этим id.","access_token приложения живёт час — обновляй его через https://oauth.bitrix.info/oauth/token/ по refresh_token."],"code":"# Вызов от имени приложения: токен передаётся в параметре auth\ncurl -X POST \"https://<портал>.bitrix24.ru/rest/event.bind.json\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"auth\": \"<access_token>\", \"event\": \"ONCRMLEADADD\", \"handler\": \"https://example.ru/b24/lead-added\"}'\n\ncurl -X POST \"https://<портал>.bitrix24.ru/rest/crm.item.get.json\" \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"auth\": \"<access_token>\", \"entityTypeId\": 1, \"id\": 253}'","language":"bash","methods":["crm.item.get","event.bind"]}],"baseUrls":[{"label":"Боевой (входящий вебхук)","url":"https://<ваш-портал>.bitrix24.ru/rest/<id пользователя>/<код вебхука>/<метод>.json"},{"label":"Боевой (приложение OAuth 2.0)","url":"https://<ваш-портал>.bitrix24.ru/rest/<метод>.json"},{"label":"Сервер авторизации OAuth","url":"https://oauth.bitrix.info/"}],"auth":{"type":"other","description":"Два способа:\n\n- **Входящий вебхук** — постоянный секретный код в URL запроса вместе с ID пользователя, создавшего вебхук. Метод выполняется с правами этого пользователя и в рамках выбранных в настройках вебхука скоупов. Подходит для интеграции с одним порталом. Код вебхука — это пароль: не публикуйте его и не передавайте в браузерный код.\n- **OAuth 2.0** — для локальных и тиражных приложений. Временный `access_token` передаётся в параметре `auth`; живёт один час и обновляется через `https://oauth.bitrix.info/oauth/token/` с помощью `refresh_token`. `client_secret` используется только в запросах к oauth.bitrix.info.\n\nБез данных авторизации запрос отклоняется с ошибкой `NO_AUTH_FOUND`.","example":"curl -X POST \\\n-H \"Content-Type: application/json\" \\\n-d '{\n\t\"entityTypeId\": 2,\n\t\"fields\": {\n\t\t\"title\": \"New Deal\",\n\t\t\"typeId\": \"SALE\",\n\t\t\"stageId\": \"NEW\"\n\t}\n}' \\\nhttps://your-domain.bitrix24.com/rest/1/8g9l071eismy9q2l/crm.item.add.json"},"methods":[{"id":"crm.item.add","title":"Создать элемент CRM","httpMethod":"POST","path":"crm.item.add","description":"Универсальный метод создания лидов, сделок, контактов, компаний и элементов смарт-процессов. Скоуп `crm`. При создании проверяются права и обязательные поля, запускаются роботы.\n\nПример ответа (сокращён):","params":[{"name":"entityTypeId","in":"body","type":"integer","required":true,"description":"Тип объекта CRM"},{"name":"fields","in":"body","type":"object","required":true,"description":"Поля элемента; набор зависит от типа объекта"},{"name":"fields.title","in":"body","type":"string","required":false,"description":"Название; по умолчанию по шаблону {entityTypeName} #{id}"},{"name":"fields.stageId","in":"body","type":"crm_status","required":false,"description":"Стадия, например NEW"},{"name":"fields.categoryId","in":"body","type":"integer","required":false,"description":"Воронка (для сделок), по умолчанию 0"},{"name":"fields.typeId","in":"body","type":"crm_status","required":false,"description":"Тип, например SALE для сделки"},{"name":"fields.opportunity","in":"body","type":"double","required":false,"description":"Сумма"},{"name":"fields.currencyId","in":"body","type":"crm_currency","required":false,"description":"Валюта"},{"name":"fields.assignedById","in":"body","type":"user","required":false,"description":"Ответственный; по умолчанию вызывающий пользователь"},{"name":"fields.companyId","in":"body","type":"crm_company","required":false,"description":"Привязанная компания"},{"name":"fields.contactIds","in":"body","type":"crm_contact[]","required":false,"description":"Привязанные контакты"},{"name":"fields.sourceId","in":"body","type":"crm_status","required":false,"description":"Источник, например CALL"},{"name":"fields.comments","in":"body","type":"text","required":false,"description":"Комментарий"},{"name":"useOriginalUfNames","in":"body","type":"boolean","required":false,"description":"Y — оригинальные имена пользовательских полей (UF_CRM_...)"}],"requestExample":"{\n    \"result\": {\n        \"item\": {\n            \"id\": 342,\n            \"createdTime\": \"2024-07-18T14:00:14+02:00\",\n            \"assignedById\": 6,\n            \"categoryId\": 9,\n            \"stageId\": \"C9:UC_KN8KFI\",\n            \"title\": \"New deal (specifically for rest method examples)\",\n            \"typeId\": \"SERVICE\",\n            \"opportunity\": 999\n        }\n    }\n}","responseExample":"","docsUrl":""},{"id":"crm.item.get","title":"Получить элемент по ID","httpMethod":"POST","path":"crm.item.get","description":"","params":[{"name":"entityTypeId","in":"body","type":"integer","required":true,"description":"Тип объекта CRM"},{"name":"id","in":"body","type":"integer","required":true,"description":"ID элемента"},{"name":"useOriginalUfNames","in":"body","type":"boolean","required":false,"description":"Формат имён пользовательских полей"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"crm.item.list","title":"Список элементов","httpMethod":"POST","path":"crm.item.list","description":"Возвращает только элементы, на которые у пользователя есть право чтения. Размер страницы всегда 50 записей.\n\nПример ответа (сокращён):","params":[{"name":"entityTypeId","in":"body","type":"integer","required":true,"description":"Тип объекта CRM"},{"name":"select","in":"body","type":"array","required":false,"description":"Поля для выборки или '*'"},{"name":"filter","in":"body","type":"object","required":false,"description":"Фильтр вида {поле: значение}, допускает вложенность и логику"},{"name":"order","in":"body","type":"object","required":false,"description":"Сортировка вида {поле: \"ASC\" | \"DESC\"}"},{"name":"start","in":"body","type":"integer","required":false,"description":"Смещение для пагинации: 50 — вторая страница"},{"name":"useOriginalUfNames","in":"body","type":"boolean","required":false,"description":"Формат имён пользовательских полей"}],"requestExample":"{\n    \"result\": {\n        \"items\": [\n            {\n                \"id\": 253,\n                \"assignedById\": 6,\n                \"stageId\": \"NEW\",\n                \"opportunity\": 19000,\n                \"sourceId\": \"WEB\",\n                \"title\": \"Lead #253\",\n                \"name\": \"Admin\",\n                \"lastName\": null,\n                \"isManualOpportunity\": \"Y\"\n            }\n        ]\n    }\n}","responseExample":"","docsUrl":""},{"id":"crm.item.update","title":"Изменить элемент","httpMethod":"POST","path":"crm.item.update","description":"Если значения полей не изменились, сохранение не выполняется. После сохранения запускаются роботы.","params":[{"name":"entityTypeId","in":"body","type":"integer","required":true,"description":"Тип объекта CRM"},{"name":"id","in":"body","type":"integer","required":true,"description":"ID элемента"},{"name":"fields","in":"body","type":"object","required":true,"description":"Новые значения полей"},{"name":"useOriginalUfNames","in":"body","type":"boolean","required":false,"description":"Формат имён пользовательских полей"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"crm.item.delete","title":"Удалить элемент","httpMethod":"POST","path":"crm.item.delete","description":"","params":[{"name":"entityTypeId","in":"body","type":"integer","required":true,"description":"Тип объекта CRM"},{"name":"id","in":"body","type":"integer","required":true,"description":"ID элемента"}],"requestExample":"","responseExample":"{\n    \"result\": [],\n    \"time\": {\n        \"start\": 1721657688.755373,\n        \"finish\": 1721657689.65017,\n        \"duration\": 0.8947970867156982,\n        \"processing\": 0.6092040538787842,\n        \"date_start\": \"2024-07-22T16:14:48+02:00\",\n        \"date_finish\": \"2024-07-22T16:14:49+02:00\",\n        \"operating\": 0\n    }\n}","docsUrl":""},{"id":"crm.item.fields","title":"Поля элемента CRM","httpMethod":"POST","path":"crm.item.fields","description":"Список полей и их настроек (тип, обязательность, только чтение, множественность) для типа объекта.","params":[{"name":"entityTypeId","in":"body","type":"integer","required":true,"description":"Тип объекта CRM"},{"name":"useOriginalUfNames","in":"body","type":"boolean","required":false,"description":"Формат имён пользовательских полей"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"batch","title":"Пакетный запрос","httpMethod":"POST","path":"batch","description":"Выполняет несколько вызовов за один HTTP-запрос — независимых или связанных (результат одного передаётся в следующий). Скоуп `basic`. В одном batch — не больше 50 команд.","params":[{"name":"cmd","in":"body","type":"array","required":true,"description":"Подзапросы: ключ — идентификатор, значение — строка method?parameter=value"},{"name":"halt","in":"body","type":"boolean","required":false,"description":"Прерывать последовательность при ошибке"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"tasks.task.add","title":"Создать задачу","httpMethod":"POST","path":"tasks.task.add","description":"Скоуп `task`.","params":[{"name":"fields","in":"body","type":"object","required":true,"description":"Поля задачи; обязательны TITLE (название) и RESPONSIBLE_ID (ответственный)"}],"requestExample":"","responseExample":"","docsUrl":""},{"id":"event.bind","title":"Подписаться на событие","httpMethod":"POST","path":"event.bind","description":"Регистрирует обработчик события (например `ONCRMLEADADD`). Работает только в контексте приложения: через вебхук вернёт `WRONG_AUTH_TYPE`. Bitrix24 отправляет данные события POST-запросом на адрес обработчика.","params":[{"name":"event","in":"body","type":"string","required":true,"description":"Код события, например ONCRMLEADADD"},{"name":"handler","in":"body","type":"string","required":true,"description":"URL обработчика; хост должен содержать точку, localhost не принимается"},{"name":"auth_type","in":"body","type":"integer","required":false,"description":"Пользователь, под которым авторизуется обработчик"},{"name":"event_type","in":"body","type":"string","required":false,"description":"online (по умолчанию) или offline"},{"name":"auth_connector","in":"body","type":"string","required":false,"description":"Ключ источника для офлайн-событий"},{"name":"options","in":"body","type":"object","required":false,"description":"Доп. настройки события"}],"requestExample":"","responseExample":"","docsUrl":""}],"codeExamples":[],"errors":[{"code":"NO_AUTH_FOUND","description":"В запросе нет ни токена, ни кода вебхука"},{"code":"INVALID_CREDENTIALS","description":"Не найден активный вебхук с такой парой ID пользователя и кода"},{"code":"INVALID_REQUEST","description":"Запрос по http — замените на https"},{"code":"QUERY_LIMIT_EXCEEDED","description":"Превышена интенсивность запросов (HTTP 503)"},{"code":"OPERATION_TIME_LIMIT","description":"Исчерпан лимит ресурсоёмкости метода; ориентируйтесь на operating_reset_at"},{"code":"OVERLOAD_LIMIT","description":"Ручная блокировка — повторять бесполезно, нужна техподдержка"},{"code":"ACCESS_DENIED","description":"Со статусом 401 — нужен коммерческий тариф; с другим статусом — ошибка метода"},{"code":"ERROR_METHOD_NOT_FOUND","description":"Неверное имя метода или нет нужного скоупа"},{"code":"insufficient_scope","description":"Добавьте недостающий скоуп приложению или вебхуку"},{"code":"expired_token","description":"Обновите токены и повторите вызов"},{"code":"user_access_error","description":"Администратор должен дать пользователю доступ к приложению"},{"code":"WRONG_AUTH_TYPE","description":"Метод недоступен при этом способе авторизации"},{"code":"INTERNAL_SERVER_ERROR","description":"Повторите вызов через несколько секунд"},{"code":"PORTAL_DELETED","description":"Публичная часть сайта закрыта — REST API не отвечает"}],"limits":"- Облако: один запрос должен выполниться за 60 секунд, иначе прерывается по таймауту.\n- Частота запросов — алгоритм Leaky Bucket: Enterprise — счётчик уменьшается на 5 в секунду, блокировка после 250; остальные тарифы — 2 в секунду, блокировка после 50. При превышении — HTTP 503 `QUERY_LIMIT_EXCEEDED`.\n- Лимиты считаются отдельно для каждого портала.\n- `batch` — до 50 команд в одном запросе.\n- Для каждого метода считается накопленное время выполнения (`time.operating`); при превышении — `OPERATION_TIME_LIMIT`.","gotchas":["Методы `crm.deal.*`, `crm.lead.*` и аналогичные больше не развиваются; для новых интеграций используйте `crm.item.*`.","Ошибку распознают по полям ответа, а не по HTTP-статусу: подзапросы `batch` с ошибкой приходят со статусом 200, а поле `error` может быть пустым — тогда причина только в `error_description`.","В ответе `batch` поле `result.result_error` есть всегда; признак ошибки — непустое содержимое.","Методы `*.list` отдают по 50 записей; для больших выгрузок используйте пагинацию без подсчёта общего количества и `batch`.","Некоторые методы (например `placement.bind`, `event.bind`) недоступны вебхуку и возвращают `WRONG_AUTH_TYPE`.","Несколько приложений с одного сервера к одному порталу делят общий лимит частоты запросов — лимит учитывает IP-адрес источника.","Запрос по `http` вместо `https` вернёт `INVALID_REQUEST`.","У Битрикс24 есть MCP-сервер `b24-dev-mcp` для AI-инструментов: он даёт доступ к официальной документации REST API (без доступа к данным портала)."],"slug":"bitrix24","version":2,"updatedAt":"2026-10-24T17:05:31.659Z","sources":[{"title":"Официальная документация REST API (репозиторий)","url":"https://github.com/bitrix24/b24restdocs","kind":"research","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"Авторизация в REST","url":"https://github.com/bitrix24/b24restdocs/blob/main/settings/how-to-call-rest-api/authorization.md","kind":"research","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"OAuth 2.0","url":"https://github.com/bitrix24/b24restdocs/blob/main/settings/oauth/index.md","kind":"research","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"crm.item.add","url":"https://github.com/bitrix24/b24restdocs/blob/main/api-reference/crm/universal/crm-item-add.md","kind":"research","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"crm.item.list","url":"https://github.com/bitrix24/b24restdocs/blob/main/api-reference/crm/universal/crm-item-list.md","kind":"research","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"batch","url":"https://github.com/bitrix24/b24restdocs/blob/main/settings/how-to-call-rest-api/batch.md","kind":"research","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"Коды ошибок","url":"https://github.com/bitrix24/b24restdocs/blob/main/error-codes.md","kind":"research","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"Лимиты","url":"https://github.com/bitrix24/b24restdocs/blob/main/limits.md","kind":"research","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"MCP-сервер","url":"https://github.com/bitrix24/b24restdocs/blob/main/ai-tools/mcp.md","kind":"research","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"Вставленный текст","url":"","kind":"import","addedAt":"2026-10-12T11:00:52.590Z"},{"title":"scenarios-bitrix24.md","url":"","kind":"import","addedAt":"2026-10-24T17:05:23.544Z"}],"logoUrl":null}