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

File Upload API を使用して、不審請求の申し立てに対する反証資料や本人確認書類などのファイルを安全に Stripe に送信できます。

Stripe は、ブラウザから Stripe にファイルを直接アップロードする機能に対応しています。適切なエンドポイントを呼び出し、*公開可能な* API キーを含める JavaScript を記述します。アップロードしたファイルの *ファイルリンク* を生成する必要がある場合は、[ベストプラクティス](https://docs.stripe.com/keys-best-practices.md)に従って、代わりにお客様のバックエンドからアップロード API を呼び出す必要があります。その際は、**Files: Write** 権限を持つ[制限付き API キー](https://docs.stripe.com/keys/restricted-api-keys.md)または厳重に保護されたシークレット API キーを使用してください。

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

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

ファイルをアップロードするには、`multipart/form-data` リクエストを **https://files.stripe.com/v1/files**. に送信します。**files.stripe.com** サブドメインは、ほとんどの Stripe API エンドポイントとは異なります。リクエストでは、`purpose` と `file` を指定します。次の例では、ローカルファイルシステム上の **/path/to/a/file.jpg** にあるファイルを、`dispute_evidence` を purpose としてアップロードします。

#### 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 リソースを取得する

ファイルの 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` フィールドがあり、認証なしでファイルのコンテンツにアクセスできます。

## ファイルを使用する

ファイルをアップロードした後は、他の API リクエストでファイルアップロード ID を使用できます。たとえば、アップロードしたファイルを特定の不審請求の申し立ての反証資料として添付する場合:

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