Надіслати файл і прочитати

Надішліть PDF, зображення або електронний рахунок, дочекайтеся, поки Ocost його прочитає, а потім прочитайте його документи. Один файл може містити кілька документів. Скан трьох рахунків — це один файл із трьома документами.

Надішліть файл

Надішліть файл як multipart/form-data на POST /public/v1/files. Ключу потрібен дозвіл 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"
ПолеЗміст
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", і читання починається одразу:

JSON
{ "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 читаються менше ніж за хвилину, довгі — за кілька хвилин.

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

Файл готовий, коли його status — read, not_read або failed. Сторінка Статуси та причини пояснює кожен. Для багатьох файлів одразу синхронізуйтеся замість опитувати кожен.

Прочитайте його документи

Файл зі статусом read перелічує свої документи в documents, кожен зі своїми id, kind, number і pages. GET /public/v1/files/{file_id}/document повертає перший. GET /public/v1/documents/{document_id} повертає будь-який із них.

Shell
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 повертає байти такими, якими ви їх надіслали.

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

Shell
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, коли він більше нічому не потрібен.

Див. також