# Rămâneți sincronizat
> Adunați fiecare fișier modificat cu un singur apel: GET /public/v1/files cu updated_since, un cursor și un filtru de stare.
>
> Înainte: [Trimiteți și citiți un fișier](https://ocost.io/docs/ro/files.md)

Adunați fiecare fișier modificat de la ultima verificare, în loc să interogați fiecare fișier. `GET /public/v1/files` listează fișierele după ultima modificare, cele mai vechi primele. Un cursor îi spune lui Ocost unde v-ați oprit. Cheia are nevoie de dreptul [`documents:read`](https://ocost.io/docs/ro/authentication.md).

## Cereți prima pagină

Transmiteți `updated_since` ca să începeți de la un anumit moment. Omiteți-l ca să începeți de la primul fișier.

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

Răspunsul conține fișierele, cursorul și dacă mai urmează altele:

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

O pagină conține până la `limit` fișiere, de la 1 la 100, implicit 50. Un fișier apare o dată pentru fiecare modificare.

## Urmați cursorul

Cât timp `more` este `true`, cereți din nou imediat, cu `cursor` setat la `next_cursor`. Când `more` este `false`, păstrați ultimul `next_cursor`. Folosiți-l la următoarea interogare și primiți doar ce s-a schimbat de atunci.

```python
def changed_since(session, cursor=None):
    """Every file changed since the cursor kept from the last poll (None: all)."""
    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  # keep the cursor for the next poll
```

```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 }; // keep the cursor for the next poll
  }
}
```

## Doar fișierele terminate

Cereți cu `status` ca să listați doar fișierele aflate în acele stări. Repetați-l pentru mai multe stări.

```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` filtrează după paginare. De aceea o pagină poate conține mai puține fișiere decât `limit`, sau niciunul. Urmați `more`, nu numărul de fișiere.

Apoi tratați fiecare fișier după starea lui. [Stări și motive](https://ocost.io/docs/ro/statuses.md) spune ce înseamnă fiecare.

## Găsiți un fișier după id-ul dumneavoastră

Cereți cu `external_ref` ca să listați doar fișierele care au acel id printre `external_refs`, potrivit exact. Se combină cu `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"
```

## Vezi și

- [Trimiteți și citiți un fișier](https://ocost.io/docs/ro/files.md): Trimiteți un fișier, retrimiteți-l în siguranță, așteptați până este citit, citiți-i documentele, obțineți originalul, ștergeți-l.
- [Stări și motive](https://ocost.io/docs/ro/statuses.md): Stările unui fișier și motivele pentru care nu a fost citit, și ce faceți în fiecare caz.
- [Căutare](https://ocost.io/docs/ro/search.md): Căutați în fiecare document după cuvinte și după sens: parametri, filtre, rezultate, exemple.
