# Anleitung zum Hochladen von Dateien

Verwenden Sie die File Upload API, um Nachweise zu Zahlungsanfechtungen, Identitätsnachweise und mehr sicher an Stripe zu senden.

Wir unterstützen die Möglichkeit, Dateien direkt über den Browser bei Stripe hochzuladen. Programmieren Sie ein JavaScript, das den entsprechenden Endpoint aufruft und Ihren *veröffentlichbaren* API-Schlüssel enthält. Wenn Sie beim Hochladen einer Datei einen Link zur Datei erstellen möchten, müssen Sie aber den Geheimschlüssel verwenden.

Wenn Sie eine Datei mit der API bei Stripe hochladen, werden ein Datei-Token und andere Informationen über die Datei zurückgegeben. Das Token kann anschließend in anderen API-Aufrufen verwendet werden. Diese Anleitung führt Sie Schritt für Schritt durch diesen Vorgang.

## Datei hochladen

Um eine Datei hochzuladen, senden Sie eine `multipart/form-data`-Anfrage an **https://files.stripe.com/v1/files**. Beachten Sie, dass die Subdomain **files.stripe.com** sich von den meisten API-Endpoints von Stripe unterscheidet. In der Anfrage sollten ein `purpose` und eine `file` angegeben werden. Im folgenden Beispiel wird eine Datei hochgeladen, die sich unter **/path/to/a/file.jpg** auf Ihrem lokalen Dateisystem befindet und den Zweck `dispute_evidence` hat:

#### curl

```bash
curl https://files.stripe.com/v1/files \
  -u <<YOUR_SECRET_KEY>>: \
  -F "file"="@/path/to/a/file.jpg" \
  -F "purpose"="dispute_evidence"
```

Im folgenden Beispiel wird eine Datei über unser Android SDK mit dem Zweck `dispute_evidence` hochgeladen:

#### Kotlin

```kotlin
class CheckoutActivity : AppCompatActivity() {
    private val stripe: Stripe by lazy {
        Stripe(this, "<<YOUR_PUBLISHABLE_KEY>>")
    }

    private fun uploadFile(file: File) {
        stripe.createFile(
            StripeFileParams(
                file,
                StripeFilePurpose.DisputeEvidence
            ),
            callback = object : ApiResultCallback<StripeFile> {
                override fun onSuccess(result: StripeFile) {
                    // File upload succeeded
                }

                override fun onError(e: Exception) {
                    // File upload failed
                }

            }
        )
    }
}
```

Es gibt mehrere [gültige Werte für Zwecke](https://docs.stripe.com/api.md#create_file-purpose), die unterschiedliche Anforderungen an das Dateiformat und die Größe haben.

> Die Größe der `identity_document`-Bilder darf 8.000 x 8.000 Pixel nicht überschreiten.

Der MIME-Typ der Datei, die Sie hochladen möchten, muss dem Dateiformat entsprechen.

> Microsoft Office-Dokumente mit VBA-Makros werden aus Sicherheitsgründen abgelehnt.

Eine erfolgreiche Anfrage gibt ein [File](https://docs.stripe.com/api/files/object.md)-Objekt zurück.

## File API-Ressource abrufen

Um die API-Ressource für eine Datei abzurufen, stellen Sie eine GET-Anfrage an den Endpoint **/v1/files** der Subdomain **files.stripe.com** unter Angabe der ID für den Datei-Upload:

#### curl

```bash
curl https://files.stripe.com/v1/files/{{FILE_ID}} \
  -u <<YOUR_SECRET_KEY>>
```

Wenn Sie eingeschränkte API-Schlüssel verwenden, müssen Sie zuvor Zugriff auf die Ressource `Files` erhalten.

## Dateiinhalte herunterladen

Wenn der Dateizweck das Herunterladen des Dateiinhalts zulässt, dann enthält die [Datei](https://docs.stripe.com/api/files/object.md) das Feld `url`. Dieses ist nicht null und gibt die Zugriffsmöglichkeit auf den Inhalt an. Die URL erfordert eine Authentifizierung mit Ihren Stripe-API-Schlüsseln.

```bash
curl https://files.stripe.com/v1/files/{{FILE_ID}}/contents
  -u <<YOUR_SECRET_KEY>>
```

Wenn Sie nicht authentifizierten Zugriff auf eine Datei benötigen, deren Zweck das Herunterladen zulässt, dann können Sie durch Erstellen eines [file_link](https://docs.stripe.com/api.md#file_links) anonyme Download-Links erzeugen.

#### curl

```bash
curl https://api.stripe.com/v1/file_links \
  -u <<YOUR_SECRET_KEY>>
  -d file={{FILE_ID}}
```

Die file_link-Ressource verfügt über das Feld `url`, das einen nicht authentifizierten Zugriff auf den Inhalt der Datei ermöglicht.

## Datei verwenden

Nachdem eine Datei hochgeladen wurde, kann die ID des Datei-Uploads in anderen API-Anfragen verwendet werden. So lässt sich beispielsweise eine hochgeladene Datei einer bestimmten Zahlungsanfechtung als Nachweis zuordnen.

#### curl

```bash
curl https://api.stripe.com/v1/disputes/{{DISPUTE_ID}}
  -u <<YOUR_SECRET_KEY>>
  -d "evidence[receipt]"={{FILE_ID}}
```

Beachten Sie, dass Sie eine hochgeladene Datei nur in einer einzelnen API-Anfrage verwenden können.

## Fehler beim Hochladen beheben

Wenn Sie die File API zum Hochladen eines PDF-Dokuments verwenden, wird das Dokument einer Reihe von Prüfungen unterzogen, um die korrekte Formatierung und die Einhaltung der PDF-Spezifikationen sicherzustellen. Falls eine der Prüfungen für das Hochladen fehlschlägt, wird ein Fehler zurückgegeben.

Führen Sie folgende Schritte aus, um erkannte Fehler zu beheben:

- Entfernen Sie Kommentare oder sonstige dem Dokument hinzugefügte Medien.
- Wenn Sie Ihre Kommentare oder Medien nicht entfernen können oder wenn Sie mehrere PDF-Dateien zu einer zusammengefasst haben, können Sie mit der Funktion „Print to PDF” Ihres Computers ein neues Dokument erstellen.
  - [Als PDF druckeen mit macOS](https://support.apple.com/guide/mac-help/save-a-document-as-a-pdf-on-mac-mchlp1531/mac)
  - [Als PDF drucken mit Adobe Acrobat](https://helpx.adobe.com/acrobat/using/print-to-pdf.html)