# Rester synchronisé
> Récupérer chaque fichier modifié en un seul appel : GET /public/v1/files avec updated_since, un curseur et un filtre de statut.
>
> Avant: [Envoyer un fichier et le lire](https://ocost.io/docs/fr/files.md)

Récupérez chaque fichier modifié depuis votre dernier passage, au lieu d'interroger chaque fichier. `GET /public/v1/files` liste les fichiers par leur dernière modification, du plus ancien au plus récent. Un curseur indique à Ocost où vous vous êtes arrêté. La clé a besoin de l'autorisation [`documents:read`](https://ocost.io/docs/fr/authentication.md).

## Demander la première page

Passez `updated_since` pour commencer à une date. Omettez-le pour commencer au premier fichier.

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

La réponse contient les fichiers, le curseur et s'il en reste d'autres :

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

Une page contient jusqu'à `limit` fichiers, de 1 à 100, 50 par défaut. Un fichier revient une fois par modification.

## Suivre le curseur

Tant que `more` vaut `true`, redemandez aussitôt avec `cursor` égal à `next_cursor`. Quand `more` vaut `false`, gardez le dernier `next_cursor`. Demandez avec lui lors de votre prochain passage, et vous n'obtenez que ce qui a changé depuis.

```python
def changed_since(session, cursor=None):
    """Chaque fichier modifié depuis le curseur gardé au dernier passage (None : tous)."""
    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  # garder le curseur pour le prochain passage
```

```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 }; // garder le curseur pour le prochain passage
  }
}
```

## Seulement les fichiers terminés

Demandez avec `status` pour ne lister que les fichiers dans ces statuts. Répétez-le pour en donner plusieurs.

```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` filtre après la pagination. Une page peut donc contenir moins de fichiers que `limit`, voire aucun. Suivez `more`, pas le nombre.

Traitez ensuite chaque fichier selon son statut. [Statuts et raisons](https://ocost.io/docs/fr/statuses.md) dit ce que chacun signifie.

## Trouver un fichier par votre identifiant

Demandez avec `external_ref` pour ne lister que les fichiers qui portent cet identifiant parmi leurs `external_refs`, à l'identique. Il se combine avec `status`, `updated_since` et `cursor`.

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

## Voir aussi

- [Envoyer un fichier et le lire](https://ocost.io/docs/fr/files.md): Envoyer un fichier, le renvoyer sans risque, attendre qu'il soit lu, lire ses documents, récupérer l'original, le supprimer.
- [Statuts et raisons](https://ocost.io/docs/fr/statuses.md): Les statuts d'un fichier et les raisons pour lesquelles il n'a pas été lu, et que faire pour chacun.
- [Recherche](https://ocost.io/docs/fr/search.md): Rechercher chaque document par ses mots et par son sens : paramètres, filtres, résultats, exemples.
