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.
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âmp | Semnificație |
|---|---|
file | Obligatoriu. 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. |
name | Numele fișierului. Fără el, Ocost îl ia pe cel al încărcării. |
external_ref | Propriul 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:
{ "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.
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 fileFiș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.
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.
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.
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ăspuns | Ce faceți |
|---|---|
409 urn:ocost:file:reading | Fișierul este în curs de citire. Încercați din nou mai târziu. |
409 urn:ocost:file:linked | Ocost î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. |