# Eine Datei schicken und lesen
> Eine Datei schicken, sicher erneut schicken, warten, bis sie gelesen ist, ihre Belege lesen, das Original holen, sie löschen.
>
> Vorher: [Schlüssel und Berechtigungen](https://ocost.io/docs/de/authentication.md)

Schicken Sie ein PDF, ein Bild oder eine E-Rechnung, warten Sie, bis Ocost sie gelesen hat, und lesen Sie dann ihre Belege. Eine Datei kann mehrere Belege enthalten. Ein Scan von drei Rechnungen ist eine Datei mit drei Belegen.

## Die Datei schicken

Schicken Sie die Datei als `multipart/form-data` an `POST /public/v1/files`. Der Schlüssel braucht die Berechtigung [`documents:write`](https://ocost.io/docs/de/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"
```

| Feld | Bedeutung |
| --- | --- |
| `file` | Pflicht. Ein PDF, ein Bild (JPEG, PNG, TIFF, WebP), eine Word-Datei (.docx, .doc) oder das XML einer E-Rechnung (XRechnung, UBL, CII), bis 25 MB. |
| `name` | Der Dateiname. Ohne ihn nimmt Ocost den des Uploads. |
| `external_ref` | Ihre eigene Kennung, bis 200 Zeichen, mit der Datei zurückgegeben. |

Tabellen (.xls, .xlsx) und Archive (.zip, .7z) lehnt die API mit `415` ab. Laden Sie sie stattdessen in Ocost hoch. Dort liest Ocost eine Rechnung in einer Tabelle mit einem Blatt, bis 200 Zeilen und 30 Spalten. Ein Archiv packt es einmal aus, in der Gesellschaft, in der es landet. Anderes XML und HTML speichert Ocost, sie enden aber als `not_read` mit `nothing_found`.

Eine neue Datei ergibt `202 Accepted` mit `"status": "received"`, und das Lesen beginnt sofort:

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

Jede Antwort trägt `X-Ocost-Documents-Left`, die Belege, die Ihr Tarif in diesem Monat noch hat. [Grenzen und Fehler](https://ocost.io/docs/de/limits.md) listet die Ablehnungen.

## Sicher erneut schicken

Ocost erkennt eine Datei am SHA-256 ihrer Bytes, nicht an ihrem Namen. Dieselben Bytes ergeben erneut `200 OK` mit dieser Datei, wie sie gerade ist. Ocost liest und zählt sie nicht noch einmal. Nach einem Timeout schicken Sie die Datei also erneut.

Eine Datei behält jede `external_ref`, die mit ihren Bytes kam. `external_ref` bleibt die erste, und `external_refs` listet alle, die erste zuerst, jede einmal, bis zu 50. Tragen also zwei Ihrer Datensätze dasselbe PDF, schicken Sie es für jeden: Beide Kennungen kommen mit der einen Datei zurück. Eine 51. neue Kennung wird mit `422` abgelehnt.

## Warten, bis sie gelesen ist

Fragen Sie die Datei mit `GET /public/v1/files/{file_id}` ab, Berechtigung `documents:read`. Fragen Sie eine halbe Minute lang alle 2 bis 3 Sekunden, danach alle 10 bis 30 Sekunden. Die meisten PDFs brauchen unter einer Minute, lange einige.

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

Die Datei ist fertig, wenn ihr `status` `read`, `not_read` oder `failed` ist. [Status und Gründe](https://ocost.io/docs/de/statuses.md) erklärt jeden. Für viele Dateien zugleich [bleiben Sie synchron](https://ocost.io/docs/de/sync.md), statt jede einzeln abzufragen.

## Ihre Belege lesen

Eine gelesene Datei listet ihre Belege in `documents`, jeden mit `id`, `kind`, `number` und `pages`. `GET /public/v1/files/{file_id}/document` liefert den ersten. `GET /public/v1/documents/{document_id}` liefert jeden davon.

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

Die Antwort ist der Beleg als `ocost.document.v1`. [Der Beleg](https://ocost.io/docs/de/document.md) zeigt einen ganzen und erklärt jedes Feld.

## Das Original holen

`GET /public/v1/files/{file_id}/content` liefert die Bytes, wie Sie sie geschickt haben.

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

## Eine Datei löschen

`DELETE /public/v1/files/{file_id}` löscht die Datei sofort und endgültig. Das umfasst ihre Belege, alles Gelesene, ihren Suchindex und das Original. Der Schlüssel braucht `documents:write`.

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

Ocost antwortet `204` und danach `404`. In zwei Fällen lehnt es ab:

| Antwort | Was tun |
| --- | --- |
| `409 urn:ocost:file:reading` | Die Datei wird gerade gelesen. Versuchen Sie es später erneut. |
| `409 urn:ocost:file:linked` | Ocost braucht die Datei noch, für eine gebuchte Rechnung, einen Kontoauszug, eine offene Frage oder ein Projekt. `detail` sagt, wofür. Löschen Sie sie in Ocost, sobald nichts sie mehr braucht. |

## Siehe auch

- [Status und Gründe](https://ocost.io/docs/de/statuses.md): Die Status einer Datei und die Gründe, aus denen sie nicht gelesen wurde, und was jeweils zu tun ist.
- [Der Beleg](https://ocost.io/docs/de/document.md): Das Schema ocost.document.v1 in den Begriffen der EN 16931 (auf UBL und CII abbildbar): ein Beispiel, Art und Richtung, Quellen, Prüfungen, Versionen und jedes Feld und jeder Wert.
- [Synchron bleiben](https://ocost.io/docs/de/sync.md): Jede geänderte Datei mit einem Aufruf einsammeln: GET /public/v1/files mit updated_since, einem Cursor und einem Statusfilter.
- [Unternehmensgruppen](https://ocost.io/docs/de/groups.md): Unternehmensgruppen: welche Gesellschaften ein Schlüssel erreicht, der Header Ocost-Business, das Umleiten nach den Kennungen des Belegs, needs_company und Dateien in der Gruppe.
- Auf ocost.io: [Rechnungsverarbeitung](https://ocost.io/produkt/rechnungsverarbeitung)
