> ## Documentation Index
> Fetch the complete documentation index at: https://platform.doodocs.kz/llms.txt
> Use this file to discover all available pages before exploring further.

# Список документов

> Фильтры GET /documents и что в этот список не попадает

`GET /documents` возвращает документы, видимые владельцу ключа в реестре, от
новых к старым. Область — `documents:read`.

Элементы списка несут только скалярные поля документа: `files` и `route` в них
не входят, за ними обращайтесь к `GET /documents/{document_id}`.

```bash theme={null}
curl -H "X-API-Key: $DOODOCS_API_KEY" \
  "https://app.doodocs.kz/api/developer/v1/documents?status=DOCUMENT_STATUS_ON_SIGN&limit=50"
```

```json theme={null}
{
  "documents": [
    {
      "id": "8c2d5a91-…",
      "title": "Приказ о приёме на работу",
      "status": "DOCUMENT_STATUS_ON_SIGN",
      "type_id": "5c9e1f04-…",
      "initiator_employee_id": "3f2a9c7e-…",
      "subject_employee_ids": ["b7e41c2d-…"],
      "number": "ПР-000142",
      "date": "2026-02-10",
      "organization_id": "a90f…",
      "create_time": "2026-02-10T09:30:00Z",
      "update_time": "2026-02-10T10:05:00Z"
    }
  ],
  "next_page_token": "CgYIyAE.7f3a"
}
```

## Фильтры

| Параметр                | Значение                                                                                          |
| ----------------------- | ------------------------------------------------------------------------------------------------- |
| `status`                | Одно значение `DocumentStatus`, например `DOCUMENT_STATUS_ON_SIGN`                                |
| `type_id`               | Тип документа из [справочника типов](/ru/guides/documents/types)                                  |
| `initiator_employee_id` | Кто создал документ                                                                               |
| `created_after`         | Дата создания не раньше, `YYYY-MM-DD`, включительно                                               |
| `created_before`        | Дата создания не позже, `YYYY-MM-DD`, включительно                                                |
| `search`                | Совпадение по названию или номеру, без учёта регистра                                             |
| `updated_since`         | Документы, изменённые не раньше указанного момента, RFC 3339                                      |
| `order_by`              | Порядок: по умолчанию новые сверху, `DOCUMENT_ORDER_UPDATED_AT_ASC` — от старых изменений к новым |

Фильтр `status` принимает ровно одно значение: чтобы собрать документы в двух
статусах, сделайте два запроса. Пагинация — общая, через `limit` и `page_token`;
поля `total_count` здесь нет.

```bash theme={null}
curl -H "X-API-Key: $DOODOCS_API_KEY" \
  "https://app.doodocs.kz/api/developer/v1/documents?type_id=5c9e1f04-…&created_after=2026-02-01&created_before=2026-02-29&search=%D0%BF%D1%80%D0%B8%D1%91%D0%BC"
```

## Чего в списке нет

<Warning>
  Документ, доступный вам **только** через участие в маршруте — вы подписант или
  согласующий, но не инициатор и прав на документ у вас нет, — в списке не
  появится. Реестр перечисляет документы по инициатору и по правам, участие в
  маршруте туда не входит. `GET /documents/{id}` по такому документу работает.
</Warning>

Значит, интегратору-участнику нужен другой вход: подпишитесь на события
`document.approval_started` и `document.signing_started` и запоминайте
`document_id` из них. Пошагово это разобрано в рецепте
[Согласовать документ как участник](/ru/guides/recipes/approve-as-participant).

## Что использовать вместо опроса

Списковый опрос не заменяет события: между двумя опросами документ успевает
пройти несколько статусов. Держите список для сверки и отчётов, а реакцию
стройте на [событиях документов](/ru/guides/documents/events).

## Сверка после простоя

Если вебхуки не доходили, заберите всё изменившееся с момента последней успешной
доставки:

```bash theme={null}
curl -H "X-API-Key: $DOODOCS_API_KEY" \
  "https://app.doodocs.kz/api/developer/v1/documents?updated_since=2026-02-10T09:00:00Z&order_by=DOCUMENT_ORDER_UPDATED_AT_ASC&limit=1000"
```

Порядок `DOCUMENT_ORDER_UPDATED_AT_ASC` важен: документ, изменившийся во время
обхода, уезжает вперёд от вашего чекпойнта, а не проскакивает мимо. Двигайте
чекпойнт по `update_time` последней обработанной записи.

<Note>
  Смещение часового пояса в query кодируйте как `%2B05:00` или присылайте время в
  `Z` (UTC): «плюс» в URL иначе трактуется как пробел.
</Note>