# Отправить файл и прочитать
> Отправить файл, безопасно отправить его повторно, дождаться чтения, прочитать его документы, получить оригинал, удалить его.
>
> Сначала: [Ключи и права](https://ocost.io/docs/ru/authentication.md)

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

## Отправить файл

Отправьте файл как `multipart/form-data` на `POST /public/v1/files`. Ключу нужно право [`documents:write`](https://ocost.io/docs/ru/authentication.md).

```bash
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`: сколько документов осталось в вашем тарифе в этом месяце. Отказы перечислены на странице [Лимиты и ошибки](https://ocost.io/docs/ru/limits.md).

## Отправить повторно без риска

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`. Каждый статус объясняет страница [Статусы и причины](https://ocost.io/docs/ru/statuses.md). Для многих файлов сразу используйте [синхронизацию](https://ocost.io/docs/ru/sync.md) вместо опроса каждого файла.

## Прочитать документы

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

```bash
curl -sS https://api.ocost.io/public/v1/documents/01a1b08c-7aa1-7b52-9d4e-2f1f1c0c4f11 \
  -H "Authorization: Bearer $OCOST_KEY"
```

Ответ — документ в формате `ocost.document.v1`. Страница [Документ](https://ocost.io/docs/ru/document.md) показывает документ целиком и объясняет каждое поле.

## Получить оригинал

`GET /public/v1/files/{file_id}/content` отдаёт байты в том виде, в каком вы их отправили.

```bash
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`.

```bash
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, когда он больше ничему не нужен. |

## См. также

- [Статусы и причины](https://ocost.io/docs/ru/statuses.md): Статусы файла и причины, по которым он не прочитан, и что делать в каждом случае.
- [Документ](https://ocost.io/docs/ru/document.md): Схема ocost.document.v1 в терминах EN 16931 (переносится в UBL и CII): пример, вид и направление, источники, проверки, версии, каждое поле и значение.
- [Синхронизация](https://ocost.io/docs/ru/sync.md): Собрать все изменённые файлы одним вызовом: GET /public/v1/files с updated_since, курсором и фильтром по статусу.
- [Группы компаний](https://ocost.io/docs/ru/groups.md): Группы компаний: до каких компаний достаёт ключ, заголовок Ocost-Business, перенаправление по кодам документа, needs_company и файлы в группе.
- На ocost.io: [Invoice processing](https://ocost.io/en/product/invoice-processing)
