Eine Datei schicken und lesen
Schicken Sie ein PDF, ein Bild oder eine E-Rechnung, warten Sie, bis Ocost sie gelesen hat, und lesen Sie dann ihre Belege. Eine Datei kann mehrere Belege enthalten. Ein Scan von drei Rechnungen ist eine Datei mit drei Belegen.
Die Datei schicken
Schicken Sie die Datei als multipart/form-data an POST /public/v1/files. Der Schlüssel braucht die Berechtigung 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"| Feld | Bedeutung |
|---|---|
file | Pflicht. Ein PDF, ein Bild (JPEG, PNG, TIFF, WebP), eine Word-Datei (.docx, .doc) oder das XML einer E-Rechnung (XRechnung, UBL, CII), bis 25 MB. |
name | Der Dateiname. Ohne ihn nimmt Ocost den des Uploads. |
external_ref | Ihre eigene Kennung, bis 200 Zeichen, mit der Datei zurückgegeben. |
Tabellen (.xls, .xlsx) und Archive (.zip, .7z) lehnt die API mit 415 ab. Laden Sie sie stattdessen in Ocost hoch. Dort liest Ocost eine Rechnung in einer Tabelle mit einem Blatt, bis 200 Zeilen und 30 Spalten. Ein Archiv packt es einmal aus, in der Gesellschaft, in der es landet. Anderes XML und HTML speichert Ocost, sie enden aber als not_read mit nothing_found.
Eine neue Datei ergibt 202 Accepted mit "status": "received", und das Lesen beginnt sofort:
{ "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1", "name": "scan.pdf", "status": "received", "external_ref": "account.move,42", "external_refs": ["account.move,42"], "documents": [] }Jede Antwort trägt X-Ocost-Documents-Left, die Belege, die Ihr Tarif in diesem Monat noch hat. Grenzen und Fehler listet die Ablehnungen.
Sicher erneut schicken
Ocost erkennt eine Datei am SHA-256 ihrer Bytes, nicht an ihrem Namen. Dieselben Bytes ergeben erneut 200 OK mit dieser Datei, wie sie gerade ist. Ocost liest und zählt sie nicht noch einmal. Nach einem Timeout schicken Sie die Datei also erneut.
Eine Datei behält jede external_ref, die mit ihren Bytes kam. external_ref bleibt die erste, und external_refs listet alle, die erste zuerst, jede einmal, bis zu 50. Tragen also zwei Ihrer Datensätze dasselbe PDF, schicken Sie es für jeden: Beide Kennungen kommen mit der einen Datei zurück. Eine 51. neue Kennung wird mit 422 abgelehnt.
Warten, bis sie gelesen ist
Fragen Sie die Datei mit GET /public/v1/files/{file_id} ab, Berechtigung documents:read. Fragen Sie eine halbe Minute lang alle 2 bis 3 Sekunden, danach alle 10 bis 30 Sekunden. Die meisten PDFs brauchen unter einer Minute, lange einige.
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 fileDie Datei ist fertig, wenn ihr status read, not_read oder failed ist. Status und Gründe erklärt jeden. Für viele Dateien zugleich bleiben Sie synchron, statt jede einzeln abzufragen.
Ihre Belege lesen
Eine gelesene Datei listet ihre Belege in documents, jeden mit id, kind, number und pages. GET /public/v1/files/{file_id}/document liefert den ersten. GET /public/v1/documents/{document_id} liefert jeden davon.
curl -sS https://api.ocost.io/public/v1/documents/01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11 \
-H "Authorization: Bearer $OCOST_KEY"Die Antwort ist der Beleg als ocost.document.v1. Der Beleg zeigt einen ganzen und erklärt jedes Feld.
Das Original holen
GET /public/v1/files/{file_id}/content liefert die Bytes, wie Sie sie geschickt haben.
curl -sS -o scan.pdf https://api.ocost.io/public/v1/files/$FILE_ID/content \
-H "Authorization: Bearer $OCOST_KEY"Eine Datei löschen
DELETE /public/v1/files/{file_id} löscht die Datei sofort und endgültig. Das umfasst ihre Belege, alles Gelesene, ihren Suchindex und das Original. Der Schlüssel braucht documents:write.
curl -sS -X DELETE https://api.ocost.io/public/v1/files/$FILE_ID \
-H "Authorization: Bearer $OCOST_KEY"Ocost antwortet 204 und danach 404. In zwei Fällen lehnt es ab:
| Antwort | Was tun |
|---|---|
409 urn:ocost:file:reading | Die Datei wird gerade gelesen. Versuchen Sie es später erneut. |
409 urn:ocost:file:linked | Ocost braucht die Datei noch, für eine gebuchte Rechnung, einen Kontoauszug, eine offene Frage oder ein Projekt. detail sagt, wofür. Löschen Sie sie in Ocost, sobald nichts sie mehr braucht. |