Для 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
order object нет Сортировка объектом: "order": { "createdTime": "desc" }. Действует так же, как sort. Если переданы оба, применяется sort
limit number нет Количество записей (по умолчанию 50, макс. 5000)
offset number нет Пропустить N записей. Вместе с фильтром по диапазону дат шире 14 дней отклоняется — см. UNSTABLE_OFFSET_PAGINATION в разделе «Ошибки»
select string | array нет Список возвращаемых полей — массивом ["id", "title"] или строкой через запятую "id,title"
include string | array нет Связанные записи: contact, company, deal — массивом или строкой через запятую. Что приходит в ответе — секция «Связанные данные»
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.

Связанные данные

Поле include принимает три имени — contact, company и deal:

JSON 
{ "limit": 10, "include": ["contact", "company", "deal"] }

Имена проверяются: любое другое значение отклоняется с 400 INVALID_INCLUDE, и в тексте ошибки перечислены допустимые. Каждый элемент массива data получает блок _included с объектами контакта, компании и сделки по полям contactId, companyId и parentId2. Если ссылка у счёта пустая, на месте объекта приходит null:

JSON 
{
  "id": 3,
  "contactId": 181,
  "companyId": 73,
  "parentId2": null,
  "_included": {
    "contact": { "id": 181 },
    "company": { "id": 73 },
    "deal": null
  }
}

Объекты в _included сокращены до id — в ответе они приходят со всеми полями записи. Общее описание механизма — Связанные данные.

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

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 Сортировка по полю, которого у счёта нет — в sort или в order. В тексте ошибки перечислены допустимые имена
400 INVALID_INCLUDE В include передано имя, которого у счёта нет. В тексте ошибки перечислены допустимые
403 SCOPE_DENIED API-ключ не имеет скоупа crm
401 TOKEN_MISSING API-ключ не имеет настроенных токенов
429 RATE_LIMITED Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Точное значение — в заголовке x-ratelimit-limit (потолок делится на реплики). Повторите после срока из заголовка Retry-After

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

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

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

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