Надіслати файл і прочитати
Надішліть PDF, зображення або електронний рахунок, дочекайтеся, поки Ocost його прочитає, а потім прочитайте його документи. Один файл може містити кілька документів. Скан трьох рахунків — це один файл із трьома документами.
Надішліть файл
Надішліть файл як multipart/form-data на POST /public/v1/files. Ключу потрібен дозвіл 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"| Поле | Зміст |
|---|---|
file | Обов’язкове. PDF, зображення (JPEG, PNG, TIFF, WebP), файл Word (.docx, .doc) або XML електронного рахунку (XRechnung, UBL, CII), до 25 МБ. |
name | Назва файлу. Без неї Ocost бере назву із завантаження. |
external_ref | Ваш власний ідентифікатор, до 200 символів. Він повертається разом із файлом. |
API відхиляє таблиці (.xls, .xlsx) і архіви (.zip, .7z) з кодом 415. Завантажуйте їх натомість в Ocost. Там Ocost читає рахунок у таблиці з одного аркуша, до 200 рядків і 30 стовпців. Архів він розпаковує один раз, у тій компанії, куди той потрапив. Інші XML і HTML зберігаються, але завершуються як not_read з nothing_found.
Новий файл відповідає 202 Accepted зі "status": "received", і читання починається одразу:
{ "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1", "name": "scan.pdf", "status": "received", "external_ref": "account.move,42", "external_refs": ["account.move,42"], "documents": [] }Кожна відповідь містить X-Ocost-Documents-Left: скільки документів ваш тариф ще має цього місяця. Ліміти та помилки перелічує відмови.
Безпечне повторне надсилання
Ocost упізнає файл за SHA-256 його байтів, а не за назвою. Ті самі байти вдруге отримують 200 OK із цим файлом у його поточному стані. Ocost не читає і не рахує його знову. Тож після тайм-ауту надішліть файл ще раз.
Файл зберігає кожен external_ref, надісланий із його байтами. external_ref залишається першим, а external_refs перелічує всі, починаючи з першого, кожен один раз, до 50. Тож коли два ваші записи мають той самий PDF, надішліть його для кожного: обидва ідентифікатори повернуться з одним файлом. 51-й новий ідентифікатор відхиляється з 422.
Дочекайтеся, поки його прочитають
Запитуйте файл через GET /public/v1/files/{file_id}, дозвіл documents:read. Опитуйте кожні 2–3 секунди протягом пів хвилини, потім кожні 10–30 секунд. Більшість PDF читаються менше ніж за хвилину, довгі — за кілька хвилин.
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Файл готовий, коли його status — read, not_read або failed. Сторінка Статуси та причини пояснює кожен. Для багатьох файлів одразу синхронізуйтеся замість опитувати кожен.
Прочитайте його документи
Файл зі статусом read перелічує свої документи в documents, кожен зі своїми id, kind, number і pages. GET /public/v1/files/{file_id}/document повертає перший. GET /public/v1/documents/{document_id} повертає будь-який із них.
curl -sS https://api.ocost.io/public/v1/documents/01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11 \
-H "Authorization: Bearer $OCOST_KEY"Відповідь — документ у форматі ocost.document.v1. Сторінка Документ показує повний приклад і пояснює кожне поле.
Отримайте оригінал
GET /public/v1/files/{file_id}/content повертає байти такими, якими ви їх надіслали.
curl -sS -o scan.pdf https://api.ocost.io/public/v1/files/$FILE_ID/content \
-H "Authorization: Bearer $OCOST_KEY"Видаліть файл
DELETE /public/v1/files/{file_id} стирає файл одразу і назавжди. Разом із ним зникають його документи, прочитане, пошуковий індекс і оригінал. Ключу потрібен documents:write.
curl -sS -X DELETE https://api.ocost.io/public/v1/files/$FILE_ID \
-H "Authorization: Bearer $OCOST_KEY"Ocost відповідає 204, а відтоді 404. Він відмовляє у двох випадках:
| Відповідь | Що робити |
|---|---|
409 urn:ocost:file:reading | Файл саме читається. Спробуйте пізніше. |
409 urn:ocost:file:linked | Файл ще потрібен Ocost: для проведеного рахунку, банківської виписки, відкритого питання чи проєкту. detail каже, для чого. Видаліть його в Ocost, коли він більше нічому не потрібен. |