Rămâneți sincronizat

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.

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.

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"

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.

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

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.

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

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

Vezi și