# Synchronizacja
> Zebrać każdy zmieniony plik jednym wywołaniem: GET /public/v1/files z updated_since, kursorem i filtrem statusu.
>
> Najpierw: [Wysłać plik i go odczytać](https://ocost.io/docs/pl/files.md)

Zbieraj każdy plik zmieniony od Twojego ostatniego sprawdzenia, zamiast odpytywać każdy plik osobno. `GET /public/v1/files` wymienia pliki według ich ostatniej zmiany, od najstarszej. Kursor mówi Ocost, gdzie skończyłeś. Klucz potrzebuje uprawnienia [`documents:read`](https://ocost.io/docs/pl/authentication.md).

## Pobierz pierwszą stronę

Podaj `updated_since`, aby zacząć od danej chwili. Pomiń go, aby zacząć od pierwszego pliku.

```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"
```

Odpowiedź zawiera pliki, kursor i informację, czy są kolejne:

```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
}
```

Strona zawiera do `limit` plików, od 1 do 100, domyślnie 50. Plik pojawia się raz przy każdej zmianie.

## Podążaj za kursorem

Dopóki `more` ma wartość `true`, pytaj od razu ponownie z `cursor` ustawionym na `next_cursor`. Gdy `more` ma wartość `false`, zachowaj ostatni `next_cursor`. Użyj go przy następnym odpytaniu, a dostaniesz tylko to, co zmieniło się od tamtej chwili.

```python
def changed_since(session, cursor=None):
    """Każdy plik zmieniony od kursora zachowanego przy ostatnim odpytaniu (None: wszystkie)."""
    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  # zachowaj kursor na następne odpytanie
```

```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 }; // zachowaj kursor na następne odpytanie
  }
}
```

## Tylko gotowe pliki

Pytaj z `status`, aby wymienić tylko pliki w tych statusach. Powtórz go dla kilku statusów.

```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` filtruje po podziale na strony. Strona może więc zawierać mniej plików niż `limit` albo żadnego. Kieruj się `more`, nie liczbą plików.

Potem obsłuż każdy plik według jego statusu. [Statusy i powody](https://ocost.io/docs/pl/statuses.md) mówi, co oznacza każdy z nich.

## Znajdź plik po swoim identyfikatorze

Pytaj z `external_ref`, aby wymienić tylko pliki, które mają ten identyfikator wśród swoich `external_refs`, dopasowany dokładnie. Łączy się z `status`, `updated_since` i `cursor`.

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

## Zobacz też

- [Wysłać plik i go odczytać](https://ocost.io/docs/pl/files.md): Wysłać plik, bezpiecznie wysłać go ponownie, poczekać, aż zostanie odczytany, odczytać jego dokumenty, pobrać oryginał, usunąć go.
- [Statusy i powody](https://ocost.io/docs/pl/statuses.md): Statusy pliku i powody, dla których nie został odczytany, oraz co zrobić w każdym przypadku.
- [Wyszukiwanie](https://ocost.io/docs/pl/search.md): Przeszukiwać wszystkie dokumenty po słowach i po znaczeniu: parametry, filtry, wyniki, przykłady.
