## Список складских документов `GET /v1/catalog-documents` Возвращает складские документы портала с фильтрацией, сортировкой и постраничным выводом. Подходит, чтобы найти документы нужного типа или статуса проведения перед работой с их позициями. ## Параметры | Параметр | Тип | По умолч. | Описание | |----------|-----|-----------|---------| | `filter` (query) | object | — | Фильтрация по полям `GET /v1/catalog-documents/fields`.
[Синтаксис фильтрации](/docs/filtering). Пример: `?filter[docType]=S&filter[status]=N` | | `select` (query) | string | — | Поля в ответе через запятую: `?select=id,title,docType,status`. Имена — из [`GET /v1/catalog-documents/fields`](/docs/entities/catalog-documents/fields) | | `order` (query) | object | — | Сортировка: `?order[id]=desc`. Короткая форма — `?sort=-id`, минус означает убывание. Без параметра документы идут по возрастанию `id` | | `limit` (query) | number | `50` | Количество записей, от 1 до 5000. Значение больше 5000 сокращается до 5000, нечисловое заменяется на `50` | | `offset` (query) | number | `0` | Сколько записей пропустить. Смещение построчное: `offset=7` начинает выдачу с восьмого документа | | `withTotal` (query) | string | — | `true` или `false`. При точном `false` ключ `meta.total` не возвращается, но Битрикс24 всё равно подсчитывает документы: параметр не ускоряет запрос. Без параметра или при `true` сохраняется прежний режим с подсчётом | **Пагинация.** При `limit > 50` Вайбкод собирает ответ из нескольких страниц автоматически. Чтобы пройти всю выборку, увеличивайте `offset` на `limit`, пока `meta.hasMore` равно `true`. ## Примеры ### curl — личный ключ ```bash curl "https://vibecode.bitrix24.tech/v1/catalog-documents?limit=2" \ -H "X-Api-Key: YOUR_API_KEY" ``` ### curl — OAuth-приложение ```bash curl "https://vibecode.bitrix24.tech/v1/catalog-documents?limit=2" \ -H "X-Api-Key: YOUR_APP_KEY" \ -H "Authorization: Bearer USER_SESSION_TOKEN" ``` ### JavaScript — личный ключ ```javascript const res = await fetch('https://vibecode.bitrix24.tech/v1/catalog-documents?limit=2', { 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/catalog-documents?limit=2', { headers: { 'X-Api-Key': 'YOUR_APP_KEY', 'Authorization': 'Bearer USER_SESSION_TOKEN', }, }) const { success, data, meta } = await res.json() ``` ## Поля ответа | Поле | Тип | Описание | |------|-----|---------| | `success` | boolean | Всегда `true` при успехе | | `data` | array | Массив складских документов (все поля — см. [Поля складского документа](/docs/entities/catalog-documents/fields)) | | `meta.total` | number | Общее количество документов, соответствующих фильтру. Необязательное поле: при `withTotal=false` отсутствует | | `meta.hasMore` | boolean | Есть ли ещё документы за пределами `limit` | | `meta.warnings` | array | Предупреждения о запросе. Приходит, когда в `select` есть имя, которого нет среди полей документа: код `UNKNOWN_SELECT_FIELD`, имя в поле `field`. Запрос при этом выполняется, остальные поля возвращаются | Товары и склады документа в ответ не входят — их возвращает [список позиций](/docs/entities/catalog-document-elements/list) с `filter[docId]`. ## Пример ответа ```json { "success": true, "data": [ { "commentary": null, "createdBy": 1, "currency": "RUB", "dateCreate": "2025-01-10T11:49:37.000Z", "dateDocument": null, "dateModify": "2025-01-10T11:49:59.000Z", "dateStatus": "2025-01-10T11:49:59.000Z", "docNumber": null, "docType": "S", "id": 1, "modifiedBy": 1, "responsibleId": 1, "siteId": "s1", "status": "Y", "statusBy": 1, "title": "Оприходование #2", "total": 275000 }, { "commentary": null, "createdBy": 1, "currency": "RUB", "dateCreate": "2025-06-27T05:00:47.000Z", "dateDocument": "2025-06-27T05:00:47.000Z", "dateModify": "2025-06-27T05:00:47.000Z", "dateStatus": "2025-06-27T05:00:47.000Z", "docNumber": null, "docType": "A", "id": 3, "modifiedBy": 1, "responsibleId": 1, "siteId": "s1", "status": "Y", "statusBy": 1, "title": "Приходная накладная #12", "total": 5940 } ], "meta": { "total": 143, "hasMore": true } } ``` ## Пример ответа при ошибке 400 — фильтр по полю, которого нет у документа: ```json { "success": false, "error": { "code": "UNKNOWN_FILTER_FIELD", "message": "Unknown filter field 'bogus' for entity 'catalog-documents'. Available: id, docType, currency, responsibleId, status, dateStatus, createdBy, dateCreate, title, docNumber, commentary, dateDocument, siteId, total, modifiedBy, statusBy, dateModify" } } ``` ## Ошибки | HTTP | Код | Описание | |------|-----|---------| | 400 | `UNKNOWN_FILTER_FIELD` | Фильтр по полю, которого нет у документа. Сообщение перечисляет допустимые поля | | 400 | `UNKNOWN_SORT_FIELD` | Сортировка по полю, которого нет у документа. Сообщение перечисляет допустимые поля | | 400 | `INVALID_FILTER` | Значение `filter` не распознано: передайте его в скобочной записи `?filter[docType]=S` или JSON-объектом `?filter={"docType":"S"}`. Обе записи в одном запросе тоже отклоняются | | 400 | `INVALID_FILTER_OPERATOR` | В фильтре передан неподдерживаемый оператор. Сообщение перечисляет поддерживаемые | | 403 | `SCOPE_DENIED` | API-ключ не имеет скоупа `catalog` | | 401 | `MISSING_API_KEY` | Не передан заголовок `X-Api-Key` | | 401 | `INVALID_API_KEY` | Переданный API-ключ не найден | | 401 | `TOKEN_MISSING` | API-ключ не имеет настроенных токенов | | 429 | `RATE_LIMITED` | Превышен лимит запросов: 300 в минуту на портал, все API-ключи портала делят один лимит. Действующее значение — в заголовке `x-ratelimit-limit`. Повторите после срока из заголовка `Retry-After` | Полный список общих ошибок API — [Ошибки](/docs/errors). ## Смотрите также - [Получить складской документ](/docs/entities/catalog-documents/get) - [Поиск складских документов](/docs/entities/catalog-documents/search) - [Поля складского документа](/docs/entities/catalog-documents/fields) - [Список позиций документа](/docs/entities/catalog-document-elements/list) - [Складские документы](/docs/entities/catalog-documents) - [Синтаксис фильтрации](/docs/filtering) - [Лимиты и оптимизация](/docs/optimization)