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.

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"
PoleZnaczenie
fileWymagane. PDF, obraz (JPEG, PNG, TIFF, WebP), plik Word (.docx, .doc) lub XML e-faktury (XRechnung, UBL, CII), do 25 MB.
nameNazwa pliku. Bez niej Ocost bierze nazwę przesłanego pliku.
external_refTwó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:

JSON
{ "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.

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

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

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

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

Shell
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:readingPlik jest właśnie odczytywany. Spróbuj ponownie później.
409 urn:ocost:file:linkedOcost 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.

Zobacz też