# Синхронизация
> Собрать все изменённые файлы одним вызовом: GET /public/v1/files с updated_since, курсором и фильтром по статусу.
>
> Сначала: [Отправить файл и прочитать](https://ocost.io/docs/ru/files.md)

Собирайте все файлы, изменившиеся с вашего последнего запроса, вместо того чтобы опрашивать каждый файл. `GET /public/v1/files` перечисляет файлы по их последнему изменению, начиная с самых старых. Курсор сообщает Ocost, где вы остановились. Ключу нужно право [`documents:read`](https://ocost.io/docs/ru/authentication.md).

## Запросить первую страницу

Передайте `updated_since`, чтобы начать с определённого момента. Без него список начинается с первого файла.

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "updated_since=2026-11-09T08:00:00Z" \
  --data-urlencode "limit=100"
```

Ответ содержит файлы, курсор и признак того, есть ли ещё:

```json
{
  "files": [
    {
      "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1",
      "name": "invoice.pdf",
      "status": "read",
      "external_ref": "account.move,42",
      "external_refs": ["account.move,42"],
      "documents": [
        { "id": "01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11", "kind": "invoice", "number": "RE-2026-1187", "pages": [1] }
      ],
      "updated_at": "2026-11-09T08:02:41Z"
    }
  ],
  "next_cursor": "MjAyNi0xMS0wOVQwODowMjo0MVo",
  "more": false
}
```

Страница содержит до `limit` файлов, от 1 до 100, по умолчанию 50. Файл приходит один раз на каждое изменение.

## Следовать курсору

Пока `more` равно `true`, сразу запрашивайте снова с `cursor`, равным `next_cursor`. Когда `more` равно `false`, сохраните последний `next_cursor`. Передайте его при следующем опросе, и вы получите только то, что изменилось с тех пор.

```python
def changed_since(session, cursor=None):
    """Все файлы, изменённые после курсора с прошлого опроса (None: все)."""
    files = []
    while True:
        params = {"limit": 100, **({"cursor": cursor} if cursor else {})}
        page = session.get(f"{API}/files", params=params, timeout=15).json()
        files += page["files"]
        cursor = page["next_cursor"] or cursor
        if not page["more"]:
            return files, cursor  # сохраните курсор для следующего опроса
```

```javascript
async function changedSince(cursor) {
  const files = [];
  for (;;) {
    const params = new URLSearchParams({ limit: '100', ...(cursor ? { cursor } : {}) });
    const page = await fetch(`${API}/files?${params}`, { headers: auth }).then((r) => r.json());
    files.push(...page.files);
    cursor = page.next_cursor ?? cursor;
    if (!page.more) return { files, cursor }; // сохраните курсор для следующего опроса
  }
}
```

## Только завершённые файлы

Передайте `status`, чтобы получить только файлы в этих статусах. Для нескольких статусов повторите параметр.

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "cursor=$CURSOR" \
  --data-urlencode "status=read" --data-urlencode "status=not_read" \
  --data-urlencode "status=failed"
```

`status` фильтрует уже после разбиения на страницы. Поэтому на странице может оказаться меньше файлов, чем `limit`, или ни одного. Ориентируйтесь на `more`, а не на количество.

Затем обработайте каждый файл по его статусу. Что означает каждый статус, объясняет страница [Статусы и причины](https://ocost.io/docs/ru/statuses.md).

## Найти файл по вашему идентификатору

Передайте `external_ref`, чтобы получить только файлы, у которых этот идентификатор есть среди `external_refs`, с точным совпадением. Параметр сочетается с `status`, `updated_since` и `cursor`.

```bash
curl -sS -G https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  --data-urlencode "external_ref=account.move,42"
```

## См. также

- [Отправить файл и прочитать](https://ocost.io/docs/ru/files.md): Отправить файл, безопасно отправить его повторно, дождаться чтения, прочитать его документы, получить оригинал, удалить его.
- [Статусы и причины](https://ocost.io/docs/ru/statuses.md): Статусы файла и причины, по которым он не прочитан, и что делать в каждом случае.
- [Поиск](https://ocost.io/docs/ru/search.md): Поиск по всем документам по словам и по смыслу: параметры, фильтры, результаты, примеры.
