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

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

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

Надішліть файл як `multipart/form-data` на `POST /public/v1/files`. Ключу потрібен дозвіл [`documents:write`](https://ocost.io/docs/uk/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`.

Новий файл відповідає `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/uk/limits.md) перелічує відмови.

## Безпечне повторне надсилання

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`. Сторінка [Статуси та причини](https://ocost.io/docs/uk/statuses.md) пояснює кожен. Для багатьох файлів одразу [синхронізуйтеся](https://ocost.io/docs/uk/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/uk/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/uk/statuses.md): Статуси файлу і причини, з яких його не прочитано, і що робити в кожному випадку.
- [Документ](https://ocost.io/docs/uk/document.md): Схема ocost.document.v1 у термінах EN 16931 (відображається на UBL і CII): приклад, вид і напрям, джерела, перевірки, версії, кожне поле і значення.
- [Синхронізація](https://ocost.io/docs/uk/sync.md): Зібрати кожен змінений файл одним викликом: GET /public/v1/files з updated_since, курсором і фільтром за статусом.
- [Групи компаній](https://ocost.io/docs/uk/groups.md): Групи компаній: яких компаній сягає ключ, заголовок Ocost-Business, перенаправлення за кодами документа, needs_company і файли в групі.
- На ocost.io: [Invoice processing](https://ocost.io/en/product/invoice-processing)
