Wysłać plik i go odczytać
Wyślij PDF, obraz lub e-fakturę, poczekaj, aż Ocost go odczyta, a potem odczytaj jego dokumenty. Jeden plik może zawierać kilka dokumentów. Skan trzech faktur to jeden plik z trzema dokumentami.
Wyślij plik
Wyślij plik jako multipart/form-data na POST /public/v1/files. Klucz potrzebuje uprawnienia 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"| Pole | Znaczenie |
|---|---|
file | Wymagane. PDF, obraz (JPEG, PNG, TIFF, WebP), plik Word (.docx, .doc) lub XML e-faktury (XRechnung, UBL, CII), do 25 MB. |
name | Nazwa pliku. Bez niej Ocost bierze nazwę przesłanego pliku. |
external_ref | Twój własny identyfikator, do 200 znaków, zwracany razem z plikiem. |
API odrzuca arkusze kalkulacyjne (.xls, .xlsx) i archiwa (.zip, .7z) kodem 415. Prześlij je zamiast tego w Ocost. Tam Ocost odczytuje fakturę z arkusza z jedną zakładką, do 200 wierszy i 30 kolumn. Archiwum rozpakowuje raz, w spółce, do której trafia. Inne pliki XML i HTML są zapisywane, ale kończą jako not_read z nothing_found.
Nowy plik dostaje odpowiedź 202 Accepted z "status": "received", a odczyt zaczyna się od razu:
{ "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1", "name": "scan.pdf", "status": "received", "external_ref": "account.move,42", "external_refs": ["account.move,42"], "documents": [] }Każda odpowiedź niesie X-Ocost-Documents-Left, czyli dokumenty, które zostały Twojemu planowi w tym miesiącu. Limity i błędy wymienia odmowy.
Wyślij go ponownie bez ryzyka
Ocost rozpoznaje plik po SHA-256 jego bajtów, nie po nazwie. Te same bajty wysłane ponownie dostają 200 OK z tym plikiem w obecnym stanie. Ocost nie odczytuje go ani nie liczy ponownie. Po przekroczeniu czasu wyślij więc plik jeszcze raz.
Plik zachowuje każdy external_ref wysłany z jego bajtami. external_ref pozostaje pierwszym, a external_refs wymienia wszystkie, pierwszy na początku, każdy raz, do 50. Gdy więc dwa Twoje rekordy mają ten sam PDF, wyślij go dla każdego z nich: oba identyfikatory wracają z jednym plikiem. 51. nowy identyfikator zostaje odrzucony z 422.
Poczekaj, aż zostanie odczytany
Pobierz plik przez GET /public/v1/files/{file_id}, z uprawnieniem documents:read. Odpytuj co 2 do 3 sekund przez pół minuty, potem co 10 do 30 sekund. Większość plików PDF zajmuje mniej niż minutę, długie kilka minut.
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 filePlik jest gotowy, gdy jego status to read, not_read lub failed. Statusy i powody objaśnia każdy z nich. Przy wielu plikach naraz synchronizuj się, zamiast odpytywać każdy z osobna.
Odczytaj jego dokumenty
Plik read wymienia swoje dokumenty w documents, każdy z jego id, kind, number i pages. GET /public/v1/files/{file_id}/document zwraca pierwszy z nich. GET /public/v1/documents/{document_id} zwraca dowolny z nich.
curl -sS https://api.ocost.io/public/v1/documents/01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11 \
-H "Authorization: Bearer $OCOST_KEY"Odpowiedź to dokument jako ocost.document.v1. Dokument pokazuje cały przykład i objaśnia każde pole.
Pobierz oryginał
GET /public/v1/files/{file_id}/content zwraca bajty dokładnie tak, jak je wysłałeś.
curl -sS -o scan.pdf https://api.ocost.io/public/v1/files/$FILE_ID/content \
-H "Authorization: Bearer $OCOST_KEY"Usuń plik
DELETE /public/v1/files/{file_id} usuwa plik od razu i na zawsze. Dotyczy to jego dokumentów, tego, co odczytano, jego indeksu wyszukiwania i oryginału. Klucz potrzebuje documents:write.
curl -sS -X DELETE https://api.ocost.io/public/v1/files/$FILE_ID \
-H "Authorization: Bearer $OCOST_KEY"Ocost odpowiada 204, a od tej chwili 404. Odmawia w dwóch przypadkach:
| Odpowiedź | Co zrobić |
|---|---|
409 urn:ocost:file:reading | Plik jest właśnie odczytywany. Spróbuj ponownie później. |
409 urn:ocost:file:linked | Ocost wciąż potrzebuje pliku: do zaksięgowanej faktury, wyciągu bankowego, otwartego pytania lub projektu. detail podaje, do czego. Usuń go w Ocost, gdy nic go już nie potrzebuje. |