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

Поиск счетов

POST /v1/invoices/search

Расширенный поиск счетов с фильтрацией, сортировкой и авто-пагинацией. Поддерживает до 5000 записей.

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

Поле Тип Описание
filter object Фильтрация. Допустимые имена перечисляет текст ошибки 400 UNKNOWN_FILTER_FIELD — фильтруется не всякое поле из GET /v1/invoices/fields.
Синтаксис фильтрации. Пример: "filter": { "stageId": "DT31_5:N" }
sort string Сортировка. Префикс - — по убыванию. Сортируется не всякое поле из GET /v1/invoices/fields, допустимые имена — в тексте ошибки 400 UNKNOWN_SORT_FIELD
limit number Количество записей (по умолчанию 50, макс. 5000)
offset number Пропустить N записей. Вместе с фильтром по диапазону дат шире 14 дней отклоняется — см. UNSTABLE_OFFSET_PAGINATION в разделе «Ошибки»
select array Список возвращаемых полей
autoWindow boolean Разбивать выборку по недельным окнам при фильтре по диапазону дат шире 14 дней. По умолчанию true. false отключает разбиение

Синтаксис фильтров

Поддерживаются три формата:

JSON 
{ "filter": { ">=opportunity": 100000 } }
{ "filter": { "opportunity": { "$gte": 100000 } } }
{ "filter": { "opportunity": { ">=": 100000 } } }

Примеры

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/invoices/search \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      ">=opportunity": 100000,
      "assignedById": 1
    },
    "sort": "-createdTime",
    "limit": 100
  }'

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

Terminal 
curl -X POST https://vibecode.bitrix24.tech/v1/invoices/search \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "filter": {
      ">=opportunity": 100000,
      "assignedById": 1
    },
    "sort": "-createdTime",
    "limit": 100
  }'

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/invoices/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { '>=opportunity': 100000, assignedById: 1 },
    sort: '-createdTime',
    limit: 100,
  }),
})

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

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

javascript 
const res = await fetch('https://vibecode.bitrix24.tech/v1/invoices/search', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    filter: { '>=opportunity': 100000, assignedById: 1 },
    sort: '-createdTime',
    limit: 100,
  }),
})

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

Поля ответа

Поле Тип Описание
success boolean Всегда true при успехе
data array Массив счетов. Все поля элемента — см. Поля счёта
meta.total number Сколько записей подошло под фильтр
meta.hasMore boolean Есть ли ещё записи за пределами limit
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/type/31/details/<id>/

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

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

JSON 
{
  "success": true,
  "data": [
    {
      "id": 117,
      "title": "Счёт за услуги",
      "stageId": "DT31_5:N",
      "opportunity": 150000,
      "currencyId": "RUB",
      "assignedById": 1,
      "createdTime": "2026-08-25T08:13:37.000Z"
    }
  ],
  "meta": {
    "total": 12,
    "hasMore": false,
    "durationMs": 240
  }
}

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

JSON 
{
  "success": true,
  "data": [ /* ... */ ],
  "meta": {
    "total": 16,
    "hasMore": true,
    "autoWindowed": true,
    "windowCount": 131,
    "batchWaves": 3,
    "durationMs": 3090
  }
}

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

400 — фильтр по несуществующему полю:

JSON 
{
  "success": false,
  "error": {
    "code": "UNKNOWN_FILTER_FIELD",
    "message": "Unknown filter field 'nosuchfield' for entity 'invoices'. Available: id, title, stageId, categoryId, assignedById, contactId, companyId, opportunity, currencyId, begindate, closedate, accountNumber, comments, mycompanyId, sourceId, sourceDescription, xmlId, opened, isManualOpportunity, isRecurring, createdBy, createdTime, updatedTime, updatedBy, movedBy, movedTime, previousStageId, lastCommunicationTime, lastCommunicationCallTime, lastCommunicationEmailTime, lastCommunicationImolTime, lastCommunicationWebformTime"
  }
}

Ошибки

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

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

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

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

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