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

Збирайте кожен файл, що змінився після вашого останнього запиту, замість опитувати кожен файл окремо. `GET /public/v1/files` перелічує файли за їхньою останньою зміною, від найстаріших. Курсор каже Ocost, де ви зупинилися. Ключу потрібен дозвіл [`documents:read`](https://ocost.io/docs/uk/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/uk/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/uk/files.md): Надіслати файл, безпечно надіслати його знову, дочекатися прочитання, прочитати його документи, отримати оригінал, видалити його.
- [Статуси та причини](https://ocost.io/docs/uk/statuses.md): Статуси файлу і причини, з яких його не прочитано, і що робити в кожному випадку.
- [Пошук](https://ocost.io/docs/uk/search.md): Шукати в усіх документах за словами і за змістом: параметри, фільтри, результати, приклади.
