# Anleitung zum Hochladen von Dateien

Verwenden Sie die File Upload API, um Dateien sicher an Stripe zu senden, z. B. Beweise für Zahlungsanfechtungen, Ausweisdokumente usw.

Wir unterstützen die Möglichkeit, Dateien direkt über den Browser bei Stripe hochzuladen. Schreiben Sie ein JavaScript, das den entsprechenden Endpoint aufruft und Ihren *veröffentlichbaren* API-Schlüssel enthält. Wenn Sie einen *Datei-Link* für eine hochgeladene Datei generieren müssen, müssen Sie stattdessen die Upload API über das Backend Ihrer Integration aufrufen und dabei die[Best Practices](https://docs.stripe.com/keys-best-practices.md) befolgen, indem Sie einen [eingeschränkten API-Schlüssel](https://docs.stripe.com/keys/restricted-api-keys.md) mit **Files: Write**-Berechtigung oder einen gut geschützten geheimen API-Schlüssel verwenden.

Wenn Sie eine Datei über die API zu Stripe hochladen, gibt diese einen Datei-Token und weitere Informationen zur Datei zurück. Sie können den Token dann in anderen API-Aufrufen verwenden. In diesem Leitfaden wird dieser Prozess beschrieben.

## Datei hochladen

Um eine Datei hochzuladen, senden Sie eine `multipart/form-data`-Anfrage an **https://files.stripe.com/v1/files**. Die Subdomain **files.stripe.com** unterscheidet sich von den meisten Stripe-API-Endpunkten. Geben Sie in der Anfrage einen `purpose` und eine `file` an. Im folgenden Beispiel wird eine Datei hochgeladen, die sich unter **/path/to/a/file.jpg** in 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.

> Alle Microsoft Office-Dokumente, die VBA-Makros enthalten, werden aus Sicherheitsgründen abgelehnt.

Eine erfolgreiche Anfrage gibt ein [Datei](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.

## Dateiinhalt 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 Ressource file_link hat ein `url`-Feld, das nicht authentifizierten Zugriff auf den Inhalt der Datei ermöglicht.

## Datei verwenden

Nachdem Sie eine Datei hochgeladen haben, können Sie die ID des Datei-Uploads in anderen API-Anfragen verwenden. Zum Beispiel, um eine hochgeladene Datei als Beweis an eine bestimmte Zahlungsanfechtung anzuhängen:

#### curl

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

Eine hochgeladene Datei kann nur in einer einzigen API-Anfrage verwendet werden.

## Umgang mit Upload-Fehlern

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” (Als PDF drucken) 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)