# ファイルアップロードガイド

File Upload API を使用することで、不審請求の申請への反証資料、身分証明書などを Stripe に安全に送信できます。

We support the ability to upload files to Stripe directly from the browser. Write JavaScript that calls the appropriate endpoint and includes your *publishable* API key. If you need to generate a *file link* for an uploaded file, you need to call the upload API from your integration’s backend instead, following [best practices](https://docs.stripe.com/keys-best-practices.md) by using a [restricted API key](https://docs.stripe.com/keys/restricted-api-keys.md) that has **Files: Write** permission or a well-protected secret API key.

API を使用して Stripe にファイルをアップロードすると、ファイルトークンとファイルに関するその他の情報が返されます。このトークンは、他の API コールに使用できます。このガイドでは、このプロセスの詳細を説明します。

## ファイルのアップロード

ファイルをアップロードするには、`multipart/form-data` リクエストを **https://files.stripe.com/v1/files** に送信します。サブドメインの **files.stripe.com** は、Stripe の多くの API エンドポイントとは異なることに注意してください。リクエストで、`purpose` と `file` を指定する必要があります。以下の例は、お客様のローカルファイルシステムにあるファイル **/path/to/a/file.jpg** を、purpose を `dispute_evidence` としてアップロードします。

#### curl

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

以下の例は、Stripe の Android SDK を使用し、目的を `dispute_evidence` としてファイルをアップロードします。

#### 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
                }

            }
        )
    }
}
```

[いくつかの有効な目的](https://docs.stripe.com/api.md#create_file-purpose)値があり、それぞれにファイル形式とサイズの要件があります。

> `identity_document` 画像は、8,000 ピクセル x 8,000 ピクセル未満である必要があります。

アップロードするファイルの MIME タイプは、そのファイル形式に対応している必要があります。

> セキュリティ上の理由により、VBA マクロが含まれる Microsoft Office ドキュメントは拒否されます。

リクエストが成功すると、[File (ファイル)](https://docs.stripe.com/api/files/object.md) オブジェクトが返されます。

## File API リソースを取得する

File の API リソースを取得するには、ファイルアップロード ID を指定して、**files.stripe.com** サブドメインの **/v1/files** エンドポイントに対して GET リクエストを実行します。

#### curl

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

制限付き API キーを使用する際は、`Files` リソースへの事前アクセス権を受ける必要があります。

## ファイルコンテンツをダウンロードする

ファイルの目的で、ファイルコンテンツのダウンロードが許可されている場合は、[File (ファイル)](https://docs.stripe.com/api/files/object.md) にコンテンツへのアクセス方法を示す null 以外の `url` フィールドが含まれています。この url は、お客様の Stripe API キーでの認証を必要とします。

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

目的でダウンロードが許可されている場合に、そのファイルへの未認証のアクセスを許可するには、[file_link](https://docs.stripe.com/api.md#file_links) を作成して匿名のダウンロードリンクを生成します。

#### curl

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

file_link リソースには、ファイルのコンテンツへの未認証アクセスを許可する `url` フィールドがあります。

## ファイルを使用する

ファイルをアップロードしたら、そのファイルアップロード ID を他の API リクエストで使用できます。たとえば、アップロードしたファイルを特定の不審請求の申請に反証資料として関連付けることができます。

#### curl

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

アップロードされたファイルは、1 つの API リクエストのみで使用できることに注意してください。

## アップロードエラーを処理する

File API を使用して PDF ドキュメントをアップロードすると、一連のチェックが行われ、そのドキュメントが正しくフォーマットされ、PDF 仕様を満たしていることが検証されます。いずれかのチェックに失敗した場合には、アップロードエラーが返されます。

以下を試し、検出されたエラーを修正してください。

- ドキュメントに追加された注釈や追加メディアを削除します。
- 注釈やメディアを削除できない場合、または複数の PDF を 1 つにまとめた場合には、お使いのコンピュータの「PDF に印刷」機能を使用して、新しいドキュメントを作成してください。
  - [macOS で PDF に印刷する](https://support.apple.com/guide/mac-help/save-a-document-as-a-pdf-on-mac-mchlp1531/mac)
  - [Adobe Acrobat で PDF に印刷する](https://helpx.adobe.com/acrobat/using/print-to-pdf.html)