Trimiteți și citiți un fișier

Trimiteți un PDF, o imagine sau o factură electronică, așteptați până când Ocost l-a citit, apoi citiți-i documentele. Un fișier poate conține mai multe documente. O scanare a trei facturi este un fișier cu trei documente.

Trimiteți fișierul

Trimiteți fișierul ca multipart/form-data la POST /public/v1/files. Cheia are nevoie de dreptul documents:write.

Shell
curl -sS https://api.ocost.io/public/v1/files \
  -H "Authorization: Bearer $OCOST_KEY" \
  -F "file=@scan.pdf" -F "name=scan.pdf" -F "external_ref=account.move,42"
CâmpSemnificație
fileObligatoriu. Un PDF, o imagine (JPEG, PNG, TIFF, WebP), un fișier Word (.docx, .doc) sau XML-ul unei facturi electronice (XRechnung, UBL, CII), până la 25 MB.
nameNumele fișierului. Fără el, Ocost îl ia pe cel al încărcării.
external_refPropriul dumneavoastră id, până la 200 de caractere, returnat împreună cu fișierul.

API-ul refuză foile de calcul (.xls, .xlsx) și arhivele (.zip, .7z) cu 415. Încărcați-le în schimb în Ocost. Acolo Ocost citește o factură dintr-o foaie de calcul cu o singură filă, de până la 200 de rânduri și 30 de coloane. Despachetează o arhivă o singură dată, în societatea în care ajunge. Alte XML și HTML sunt stocate, dar se termină ca not_read cu nothing_found.

Un fișier nou primește răspunsul 202 Accepted cu "status": "received", iar citirea începe imediat:

JSON
{ "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1", "name": "scan.pdf", "status": "received", "external_ref": "account.move,42", "external_refs": ["account.move,42"], "documents": [] }

Fiecare răspuns poartă X-Ocost-Documents-Left, documentele care îi mai rămân planului dumneavoastră în această lună. Limite și erori listează refuzurile.

Retrimiteți-l în siguranță

Ocost recunoaște un fișier după SHA-256 al octeților săi, nu după nume. Aceiași octeți trimiși din nou primesc 200 OK cu acel fișier, așa cum este acum. Ocost nu îl citește și nu îl numără din nou. Așadar, după un timeout, trimiteți fișierul din nou.

Un fișier păstrează fiecare external_ref trimis cu octeții săi. external_ref rămâne primul, iar external_refs le listează pe toate, primul întâi, fiecare o dată, până la 50. Așadar, când două dintre înregistrările dumneavoastră au același PDF, trimiteți-l pentru fiecare: ambele id-uri revin cu același fișier. Un al 51-lea id nou este refuzat cu 422.

Așteptați până este citit

Cereți fișierul cu GET /public/v1/files/{file_id}, cu dreptul documents:read. Interogați la fiecare 2–3 secunde timp de jumătate de minut, apoi la fiecare 10–30 de secunde. Majoritatea PDF-urilor durează sub un minut, cele lungi câteva minute.

Python
def wait_for(session, file_id, timeout=300):
    started = time.monotonic()
    while time.monotonic() - started < timeout:
        file = session.get(f"{API}/files/{file_id}", timeout=15).json()
        if file["status"] not in ("received", "reading"):
            return file
        time.sleep(3 if time.monotonic() - started < 30 else 15)
    return file

Fișierul este gata când status este read, not_read sau failed. Stări și motive le explică pe fiecare. Pentru multe fișiere deodată, rămâneți sincronizat în loc să interogați fiecare fișier.

Citiți-i documentele

Un fișier read își listează documentele în documents, fiecare cu id, kind, number și pages. GET /public/v1/files/{file_id}/document îl returnează pe primul. GET /public/v1/documents/{document_id} îl returnează pe oricare dintre ele.

Shell
curl -sS https://api.ocost.io/public/v1/documents/01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11 \
  -H "Authorization: Bearer $OCOST_KEY"

Răspunsul este documentul ca ocost.document.v1. Documentul arată unul întreg și explică fiecare câmp.

Obțineți originalul

GET /public/v1/files/{file_id}/content returnează octeții așa cum i-ați trimis.

Shell
curl -sS -o scan.pdf https://api.ocost.io/public/v1/files/$FILE_ID/content \
  -H "Authorization: Bearer $OCOST_KEY"

Ștergeți un fișier

DELETE /public/v1/files/{file_id} șterge fișierul imediat și definitiv. Asta include documentele sale, ce s-a citit, indexul de căutare și originalul. Cheia are nevoie de documents:write.

Shell
curl -sS -X DELETE https://api.ocost.io/public/v1/files/$FILE_ID \
  -H "Authorization: Bearer $OCOST_KEY"

Ocost răspunde 204, iar de atunci încolo 404. Refuză în două cazuri:

RăspunsCe faceți
409 urn:ocost:file:readingFișierul este în curs de citire. Încercați din nou mai târziu.
409 urn:ocost:file:linkedOcost încă are nevoie de fișier, pentru o factură înregistrată, un extras de cont, o întrebare deschisă sau un proiect. detail spune pentru ce. Ștergeți-l în Ocost când nimic nu mai are nevoie de el.

Vezi și