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.
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 :
{
"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 passageasync 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.
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.
curl -sS -G https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY" \
--data-urlencode "external_ref=account.move,42"