# Wysłać plik i go odczytać
> Wysłać plik, bezpiecznie wysłać go ponownie, poczekać, aż zostanie odczytany, odczytać jego dokumenty, pobrać oryginał, usunąć go.
>
> Najpierw: [Klucze i uprawnienia](https://ocost.io/docs/pl/authentication.md)

Wyślij PDF, obraz lub e-fakturę, poczekaj, aż Ocost go odczyta, a potem odczytaj jego dokumenty. Jeden plik może zawierać kilka dokumentów. Skan trzech faktur to jeden plik z trzema dokumentami.

## Wyślij plik

Wyślij plik jako `multipart/form-data` na `POST /public/v1/files`. Klucz potrzebuje uprawnienia [`documents:write`](https://ocost.io/docs/pl/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"
```

| Pole | Znaczenie |
| --- | --- |
| `file` | Wymagane. PDF, obraz (JPEG, PNG, TIFF, WebP), plik Word (.docx, .doc) lub XML e-faktury (XRechnung, UBL, CII), do 25 MB. |
| `name` | Nazwa pliku. Bez niej Ocost bierze nazwę przesłanego pliku. |
| `external_ref` | Twój własny identyfikator, do 200 znaków, zwracany razem z plikiem. |

API odrzuca arkusze kalkulacyjne (.xls, .xlsx) i archiwa (.zip, .7z) kodem `415`. Prześlij je zamiast tego w Ocost. Tam Ocost odczytuje fakturę z arkusza z jedną zakładką, do 200 wierszy i 30 kolumn. Archiwum rozpakowuje raz, w spółce, do której trafia. Inne pliki XML i HTML są zapisywane, ale kończą jako `not_read` z `nothing_found`.

Nowy plik dostaje odpowiedź `202 Accepted` z `"status": "received"`, a odczyt zaczyna się od razu:

```json
{ "id": "01a1b08c-6e3a-7562-8f4a-7924722667b1", "name": "scan.pdf", "status": "received", "external_ref": "account.move,42", "external_refs": ["account.move,42"], "documents": [] }
```

Każda odpowiedź niesie `X-Ocost-Documents-Left`, czyli dokumenty, które zostały Twojemu planowi w tym miesiącu. [Limity i błędy](https://ocost.io/docs/pl/limits.md) wymienia odmowy.

## Wyślij go ponownie bez ryzyka

Ocost rozpoznaje plik po SHA-256 jego bajtów, nie po nazwie. Te same bajty wysłane ponownie dostają `200 OK` z tym plikiem w obecnym stanie. Ocost nie odczytuje go ani nie liczy ponownie. Po przekroczeniu czasu wyślij więc plik jeszcze raz.

Plik zachowuje każdy `external_ref` wysłany z jego bajtami. `external_ref` pozostaje pierwszym, a `external_refs` wymienia wszystkie, pierwszy na początku, każdy raz, do 50. Gdy więc dwa Twoje rekordy mają ten sam PDF, wyślij go dla każdego z nich: oba identyfikatory wracają z jednym plikiem. 51. nowy identyfikator zostaje odrzucony z `422`.

## Poczekaj, aż zostanie odczytany

Pobierz plik przez `GET /public/v1/files/{file_id}`, z uprawnieniem `documents:read`. Odpytuj co 2 do 3 sekund przez pół minuty, potem co 10 do 30 sekund. Większość plików PDF zajmuje mniej niż minutę, długie kilka minut.

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

Plik jest gotowy, gdy jego `status` to `read`, `not_read` lub `failed`. [Statusy i powody](https://ocost.io/docs/pl/statuses.md) objaśnia każdy z nich. Przy wielu plikach naraz [synchronizuj się](https://ocost.io/docs/pl/sync.md), zamiast odpytywać każdy z osobna.

## Odczytaj jego dokumenty

Plik `read` wymienia swoje dokumenty w `documents`, każdy z jego `id`, `kind`, `number` i `pages`. `GET /public/v1/files/{file_id}/document` zwraca pierwszy z nich. `GET /public/v1/documents/{document_id}` zwraca dowolny z nich.

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

Odpowiedź to dokument jako `ocost.document.v1`. [Dokument](https://ocost.io/docs/pl/document.md) pokazuje cały przykład i objaśnia każde pole.

## Pobierz oryginał

`GET /public/v1/files/{file_id}/content` zwraca bajty dokładnie tak, jak je wysłałeś.

```bash
curl -sS -o scan.pdf https://api.ocost.io/public/v1/files/$FILE_ID/content \
  -H "Authorization: Bearer $OCOST_KEY"
```

## Usuń plik

`DELETE /public/v1/files/{file_id}` usuwa plik od razu i na zawsze. Dotyczy to jego dokumentów, tego, co odczytano, jego indeksu wyszukiwania i oryginału. Klucz potrzebuje `documents:write`.

```bash
curl -sS -X DELETE https://api.ocost.io/public/v1/files/$FILE_ID \
  -H "Authorization: Bearer $OCOST_KEY"
```

Ocost odpowiada `204`, a od tej chwili `404`. Odmawia w dwóch przypadkach:

| Odpowiedź | Co zrobić |
| --- | --- |
| `409 urn:ocost:file:reading` | Plik jest właśnie odczytywany. Spróbuj ponownie później. |
| `409 urn:ocost:file:linked` | Ocost wciąż potrzebuje pliku: do zaksięgowanej faktury, wyciągu bankowego, otwartego pytania lub projektu. `detail` podaje, do czego. Usuń go w Ocost, gdy nic go już nie potrzebuje. |

## Zobacz też

- [Statusy i powody](https://ocost.io/docs/pl/statuses.md): Statusy pliku i powody, dla których nie został odczytany, oraz co zrobić w każdym przypadku.
- [Dokument](https://ocost.io/docs/pl/document.md): Schemat ocost.document.v1 w pojęciach EN 16931 (odwzorowywalny na UBL i CII): przykład, rodzaj i kierunek, źródła, kontrole, wersje oraz każde pole i każda wartość.
- [Synchronizacja](https://ocost.io/docs/pl/sync.md): Zebrać każdy zmieniony plik jednym wywołaniem: GET /public/v1/files z updated_since, kursorem i filtrem statusu.
- [Grupy spółek](https://ocost.io/docs/pl/groups.md): Grupy spółek: do których spółek sięga klucz, nagłówek Ocost-Business, przekierowanie po identyfikatorach dokumentu, needs_company i pliki w grupie.
- Na ocost.io: [Invoice processing](https://ocost.io/en/product/invoice-processing)
