Отправить файл и прочитать

Отправьте 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.

На новый файл Ocost отвечает 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 его байтов, а не по имени. На те же байты Ocost отвечает 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, когда он больше ничему не нужен.

См. также