Синхронізація
Збирайте кожен файл, що змінився після вашого останнього запиту, замість опитувати кожен файл окремо. GET /public/v1/files перелічує файли за їхньою останньою зміною, від найстаріших. Курсор каже Ocost, де ви зупинилися. Ключу потрібен дозвіл documents:read.
Запитайте першу сторінку
Передайте updated_since, щоб почати з певного моменту. Без нього список починається з першого файлу.
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"Відповідь містить файли, курсор і ознаку, чи є ще файли:
{
"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
}Сторінка містить до limit файлів, від 1 до 100, типово 50. Файл з’являється один раз на кожну зміну.
Ідіть за курсором
Поки more дорівнює true, одразу запитуйте знову з cursor, рівним next_cursor. Коли more дорівнює false, збережіть останній next_cursor. Запитайте з ним під час наступного опитування, і ви отримаєте лише те, що змінилося відтоді.
def changed_since(session, cursor=None):
"""Кожен файл, змінений після курсора з минулого опитування (None: усі)."""
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 # збережіть курсор для наступного опитування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 }; // збережіть курсор для наступного опитування
}
}Лише завершені файли
Запитуйте зі status, щоб отримати лише файли в цих статусах. Повторіть його для кількох статусів.
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 фільтрує після поділу на сторінки. Тому сторінка може містити менше файлів, ніж limit, або жодного. Орієнтуйтеся на more, а не на кількість.
Потім обробіть кожен файл за його статусом. Сторінка Статуси та причини пояснює, що означає кожен.
Знайдіть файл за своїм ідентифікатором
Запитуйте з external_ref, щоб отримати лише файли, серед external_refs яких є цей ідентифікатор, за точним збігом. Його можна поєднувати зі status, updated_since і cursor.
curl -sS -G https://api.ocost.io/public/v1/files \
-H "Authorization: Bearer $OCOST_KEY" \
--data-urlencode "external_ref=account.move,42"