Rester synchronisé

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.

Demander la première page

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

Shell
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.

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

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.

Shell
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 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.

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

Voir aussi