Для AI-агентов: markdown этой страницы — /docs-content/entities/deals/list.md индекс документации — /llms.txt

Список сделок

GET /v1/deals

Возвращает список сделок с поддержкой фильтрации, сортировки и авто-пагинации.

Параметры

Параметр Тип По умолч. Описание
limit number 50 Количество записей (до 5000). При limit > 50 ответ собирается из нескольких последовательных чтений по 50 записей
offset number 0 Пропустить N записей. При offset > 0 рекомендуется limit ≤ 500. Для обхода всей коллекции дешевле курсор — order[id]=asc и filter[>id] из meta.nextAfterId
select string — Выборка полей: ?select=id,title,amount
order object — Сортировка: ?order[createdAt]=desc
filter object — Фильтрация по полям GET /v1/deals/fields.
Синтаксис фильтрации. Пример: ?filter[stageId]=NEW
withTotal string — Нужно ли количество: true или false. false — не заказывать подсчёт. Это единственный способ гарантированно убрать meta.total из ответа. Без параметра — настройка ключа, затем платформенное умолчание, и тогда на короткой странице точное количество приходит и без заказа. Листание и количество

Примеры

curl — личный ключ

Terminal 
curl "https://vibecode.bitrix24.tech/v1/deals?limit=10&order[amount]=desc&filter[stageId]=NEW" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth-приложение

Terminal 
curl "https://vibecode.bitrix24.tech/v1/deals?limit=10&order[amount]=desc&filter[stageId]=NEW" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — личный ключ

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/deals?limit=10&order[amount]=desc&filter[stageId]=NEW', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data, meta } = await res.json()
console.log(`Найдено ${meta.total} сделок`)

JavaScript — OAuth-приложение

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/deals?limit=10&order[amount]=desc&filter[stageId]=NEW', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data, meta } = await res.json()

Поля ответа

Поле Тип Описание
data array Массив сделок (каждая содержит все поля — см. Поля)
meta.total number Общее количество записей, соответствующих фильтру. Необязательное поле: если количество не заказывалось, его в ответе нет
meta.hasMore boolean Есть ли ещё записи за пределами limit
meta.nextAfterId string Идентификатор последней отданной записи. Приходит при сортировке строго по id по возрастанию, пока hasMore равен true. Передайте его обратно как filter[>id] — это дешёвая замена растущему offset

URL карточки любой сделки из массива data — её id:

https://<portal>.bitrix24.ru/crm/deal/details/<id>/

<portal> — домен портала. Доступ ограничен правами сотрудника в Битрикс24.

Пример ответа

JSON 
{
  "success": true,
  "data": [
    {
      "id": 741,
      "title": "Поставка оборудования",
      "amount": 50000,
      "currency": "RUB",
      "stageId": "NEW",
      "categoryId": 0,
      "assignedById": 1,
      "createdAt": "2026-04-14T08:43:59.000Z",
      "contactId": 71,
      "companyId": 0,
      "opened": true
    }
  ],
  "meta": {
    "total": 156,
    "hasMore": true
  }
}

Пример ответа при ошибке

403 — нет скоупа:

JSON 
{
  "success": false,
  "error": {
    "code": "SCOPE_DENIED",
    "message": "This endpoint requires 'crm' scope"
  }
}

Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Фильтр по полю, которого нет в схеме сделки. Сообщение содержит список доступных полей
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

Полный список общих ошибок API — Ошибки.

Известные особенности

Авто-пагинация: limit > 50 выполняется несколькими последовательными чтениями по 50 записей, а ответ приходит одним массивом. Время ответа растёт вместе с limit — Клиентский таймаут.

Ограничение offset: при offset ≥ 2500 ответ может прийти с INTERNAL_ERROR. Держите limit ≤ 500 на больших смещениях, а всю коллекцию обходите курсором filter[>id] — он не зависит от глубины.

Когда использовать поиск. Сложные фильтры с множеством условий передаются в теле запроса, а не в строке запроса. Поиск дополнительно разбивает широкий диапазон дат на окна — Поиск с разбиением по датам. См. Поиск сделок.

Смотрите также