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