# Trimiteți și citiți un fișier
> Trimiteți un fișier, retrimiteți-l în siguranță, așteptați până este citit, citiți-i documentele, obțineți originalul, ștergeți-l.
>
> Înainte: [Chei și drepturi](https://ocost.io/docs/ro/authentication.md)

Trimiteți un PDF, o imagine sau o factură electronică, așteptați până când Ocost l-a citit, apoi citiți-i documentele. Un fișier poate conține mai multe documente. O scanare a trei facturi este un fișier cu trei documente.

## Trimiteți fișierul

Trimiteți fișierul ca `multipart/form-data` la `POST /public/v1/files`. Cheia are nevoie de dreptul [`documents:write`](https://ocost.io/docs/ro/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"
```

| Câmp | Semnificație |
| --- | --- |
| `file` | Obligatoriu. Un PDF, o imagine (JPEG, PNG, TIFF, WebP), un fișier Word (.docx, .doc) sau XML-ul unei facturi electronice (XRechnung, UBL, CII), până la 25 MB. |
| `name` | Numele fișierului. Fără el, Ocost îl ia pe cel al încărcării. |
| `external_ref` | Propriul dumneavoastră id, până la 200 de caractere, returnat împreună cu fișierul. |

API-ul refuză foile de calcul (.xls, .xlsx) și arhivele (.zip, .7z) cu `415`. Încărcați-le în schimb în Ocost. Acolo Ocost citește o factură dintr-o foaie de calcul cu o singură filă, de până la 200 de rânduri și 30 de coloane. Despachetează o arhivă o singură dată, în societatea în care ajunge. Alte XML și HTML sunt stocate, dar se termină ca `not_read` cu `nothing_found`.

Un fișier nou primește răspunsul `202 Accepted` cu `"status": "received"`, iar citirea începe imediat:

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

Fiecare răspuns poartă `X-Ocost-Documents-Left`, documentele care îi mai rămân planului dumneavoastră în această lună. [Limite și erori](https://ocost.io/docs/ro/limits.md) listează refuzurile.

## Retrimiteți-l în siguranță

Ocost recunoaște un fișier după SHA-256 al octeților săi, nu după nume. Aceiași octeți trimiși din nou primesc `200 OK` cu acel fișier, așa cum este acum. Ocost nu îl citește și nu îl numără din nou. Așadar, după un timeout, trimiteți fișierul din nou.

Un fișier păstrează fiecare `external_ref` trimis cu octeții săi. `external_ref` rămâne primul, iar `external_refs` le listează pe toate, primul întâi, fiecare o dată, până la 50. Așadar, când două dintre înregistrările dumneavoastră au același PDF, trimiteți-l pentru fiecare: ambele id-uri revin cu același fișier. Un al 51-lea id nou este refuzat cu `422`.

## Așteptați până este citit

Cereți fișierul cu `GET /public/v1/files/{file_id}`, cu dreptul `documents:read`. Interogați la fiecare 2–3 secunde timp de jumătate de minut, apoi la fiecare 10–30 de secunde. Majoritatea PDF-urilor durează sub un minut, cele lungi câteva minute.

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

Fișierul este gata când `status` este `read`, `not_read` sau `failed`. [Stări și motive](https://ocost.io/docs/ro/statuses.md) le explică pe fiecare. Pentru multe fișiere deodată, [rămâneți sincronizat](https://ocost.io/docs/ro/sync.md) în loc să interogați fiecare fișier.

## Citiți-i documentele

Un fișier `read` își listează documentele în `documents`, fiecare cu `id`, `kind`, `number` și `pages`. `GET /public/v1/files/{file_id}/document` îl returnează pe primul. `GET /public/v1/documents/{document_id}` îl returnează pe oricare dintre ele.

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

Răspunsul este documentul ca `ocost.document.v1`. [Documentul](https://ocost.io/docs/ro/document.md) arată unul întreg și explică fiecare câmp.

## Obțineți originalul

`GET /public/v1/files/{file_id}/content` returnează octeții așa cum i-ați trimis.

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

## Ștergeți un fișier

`DELETE /public/v1/files/{file_id}` șterge fișierul imediat și definitiv. Asta include documentele sale, ce s-a citit, indexul de căutare și originalul. Cheia are nevoie de `documents:write`.

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

Ocost răspunde `204`, iar de atunci încolo `404`. Refuză în două cazuri:

| Răspuns | Ce faceți |
| --- | --- |
| `409 urn:ocost:file:reading` | Fișierul este în curs de citire. Încercați din nou mai târziu. |
| `409 urn:ocost:file:linked` | Ocost încă are nevoie de fișier, pentru o factură înregistrată, un extras de cont, o întrebare deschisă sau un proiect. `detail` spune pentru ce. Ștergeți-l în Ocost când nimic nu mai are nevoie de el. |

## Vezi și

- [Stări și motive](https://ocost.io/docs/ro/statuses.md): Stările unui fișier și motivele pentru care nu a fost citit, și ce faceți în fiecare caz.
- [Documentul](https://ocost.io/docs/ro/document.md): Schema ocost.document.v1 în termenii EN 16931 (se mapează pe UBL și CII): un exemplu, tip și direcție, surse, verificări, versiuni și fiecare câmp și valoare.
- [Rămâneți sincronizat](https://ocost.io/docs/ro/sync.md): Adunați fiecare fișier modificat cu un singur apel: GET /public/v1/files cu updated_since, un cursor și un filtru de stare.
- [Grupuri de firme](https://ocost.io/docs/ro/groups.md): Grupuri de firme: la ce societăți ajunge o cheie, antetul Ocost-Business, redirecționarea după identificatorii documentului, needs_company și fișierele din grup.
- Pe ocost.io: [Invoice processing](https://ocost.io/en/product/invoice-processing)
