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

Поиск сделок

POST /v1/deals/search

Поиск сделок с фильтрами и авто-пагинацией. Аналогичен GET /v1/deals с фильтрами, но через POST — удобнее для сложных запросов с большим количеством условий.

Поля запроса (body)

Параметр Тип По умолч. Описание
filter object — Фильтрация по полям GET /v1/deals/fields.
Синтаксис фильтрации. Пример: ?filter[stageId]=NEW
limit number 50 Количество записей (до 5000)
offset number 0 Пропустить N записей. Вместе с фильтром по диапазону дат шире 14 дней отклоняется — см. UNSTABLE_OFFSET_PAGINATION в разделе «Ошибки»
order object — Сортировка: { "createdAt": "desc" }
select string[] — Выборка полей: ["id", "title", "amount"]
autoWindow boolean true Разбивать выборку по недельным окнам при фильтре по диапазону дат шире 14 дней. false отключает разбиение

Примеры

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/deals/search" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "stageId": "NEW" },
    "limit": 10,
    "order": { "amount": "desc" }
  }'

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

Terminal 
curl -X POST "https://vibecode.bitrix24.tech/v1/deals/search" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": { "stageId": "NEW" },
    "limit": 10,
    "order": { "amount": "desc" }
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/deals/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { stageId: 'NEW' },
    limit: 10,
    order: { amount: 'desc' },
  }),
})

const { success, data } = await res.json()
console.log('Найдено:', data.length)

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/deals/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { stageId: 'NEW' },
    limit: 10,
    order: { amount: 'desc' },
  }),
})

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

Поля ответа

Поле Тип Описание
data array Массив сделок (все поля — см. Поля)
meta.total number Сколько записей подошло под фильтр
meta.hasMore boolean Есть ли ещё записи за пределами limit
meta.nextAfterId string Идентификатор последней отданной записи. Приходит при сортировке строго по id по возрастанию, пока hasMore равен true. Передайте его обратно в фильтр >id — это дешёвая замена растущему offset
meta.durationMs number Длительность запроса в миллисекундах
meta.autoWindowed boolean true, если выборка была разбита по временны́м окнам
meta.windowCount number Число окон. Приходит при autoWindowed: true
meta.batchWaves number Число волн параллельных запросов. Приходит при autoWindowed: true

Поля meta лежат рядом с data, а не внутри него. Обходить страницы нужно по meta.hasMore: длина data, равная limit, последней страницы не исключает.

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

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

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

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 3865,
      "title": "Шаблончик",
      "amount": 0,
      "currency": "RUB",
      "stageId": "NEW",
      "categoryId": 0,
      "assignedById": 29,
      "createdAt": "2021-01-13T13:52:44.000Z"
    }
  ],
  "meta": {
    "total": 1915,
    "hasMore": true,
    "durationMs": 690
  }
}

С фильтром по диапазону дат шире 14 дней в meta дополнительно приходят autoWindowed, windowCount и batchWaves:

JSON 
{
  "success": true,
  "data": [ /* ... */ ],
  "meta": {
    "total": 618,
    "hasMore": true,
    "autoWindowed": true,
    "windowCount": 78,
    "batchWaves": 2,
    "durationMs": 2742
  }
}

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

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

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

Ошибки

HTTP Код Описание
400 UNKNOWN_FILTER_FIELD Фильтр по полю, которого нет в схеме сделки. Сообщение содержит список доступных полей
400 UNSTABLE_OFFSET_PAGINATION offset больше нуля вместе с фильтром по диапазону дат шире 14 дней. Два разных алгоритма выдачи дают несогласованные результаты, поэтому запрос отклоняется. Возьмите всё одним запросом с limit до 5000, либо передайте autoWindow: false с сортировкой по id, либо режьте диапазон дат на части сами
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов

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

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

Разбиение по временны́м окнам. Фильтр по диапазону дат шире 14 дней автоматически разбивается на недельные окна, которые выполняются параллельными волнами — так выборка обходит потолок в 5000 записей на один вызов. В meta тогда приходят autoWindowed: true, число окон windowCount и число волн batchWaves. Отключает разбиение параметр autoWindow: false. При активном разбиении offset больше нуля отклоняется с UNSTABLE_OFFSET_PAGINATION.

Отчёты по закрытым сделкам фильтруются по closedAt. Дата закрытия сделки — поле closedAt (ISO 8601 с учётом часового пояса портала), заполняется при переходе сделки в финальную стадию. Имя поля именно closedAt — не closedDate. Для отчёта «выиграно/проиграно за период» отбирайте по диапазону closedAt:

JSON 
{
  "filter": {
    "closedAt": { "$gte": "2026-01-01", "$lte": "2026-01-31T23:59:59" }
  }
}

Чтобы разделить выигранные и проигранные, добавьте к фильтру стадию (stageId). Идентификаторы финальных стадий воронки — GET /v1/statuses?filter[entityId]=DEAL_STAGE.

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