# API を使用して不審請求の申請に対応する

プログラムを使用して不審請求の申請を管理する方法をご紹介します。

API を使用して、プログラムで不審請求の申し立てを管理することができます。API を使用すると、証拠をアップロードし、不審請求の申し立てに応答し、Webhooks を使用して不審請求の申し立てイベントを受信することができます。

API を使用する代わりにダッシュボードを使用して不審請求の申し立てを管理したい場合は、[不審請求の申し立てに対応する](https://docs.stripe.com/disputes/responding.md) を参照してください。

## 不審請求の申請を取得する

不審請求の申し立ての詳細については、`Dispute` オブジェクトを [取得](https://docs.stripe.com/api/disputes/retrieve.md) してください。

```curl
curl https://api.stripe.com/v1/disputes/{{DISPUTE_ID}} \
  -u "<<YOUR_SECRET_KEY>>:"
```

レスポンスには、不審請求の申請に関する情報と、すでに提供されているレスポンスや反証資料が含まれます。

```json
{
  "object": "dispute",
  "id": "{{DISPUTE_ID}}",
  "charge": "ch_5Q4BjL06oPWwho",
  "evidence": {
    "customer_name": "Jane Austen",
    "customer_purchase_ip": "127.0.0.1",
    "product_description": "Widget ABC, color: red",
    "shipping_tracking_number": "Z01234567890",
    "uncategorized_text": "Additional notes and comments"
  },
  "evidence_details": {
    "due_by": 1403047735,
    "submission_count": 1
  }
  ...
}
```

## 不審請求の申請を更新する

`Dispute` オブジェクトを [更新](https://docs.stripe.com/api/disputes/update.md) し、`evidence` パラメーターで構造化された証拠資料を渡します。

```curl
curl https://api.stripe.com/v1/disputes/{{DISPUTE_ID}} \
  -u "<<YOUR_SECRET_KEY>>:" \
  --data-urlencode "evidence[customer_email_address]=email@example.com" \
  -d "evidence[shipping_date]=2024-02-01" \
  -d "evidence[shipping_documentation]={{FILE_ID}}"
```

`evidence` パラメーターに使用可能なすべてのフィールドを表示するには、[Dispute evidence](https://docs.stripe.com/api/disputes/update.md#update_dispute-evidence) を参照してください。更新されるフィールドに応じて、次の 2 つのタイプの証拠資料を提供できます。

- `customer_email` や `service_date` などのテキストベースの反証資料。これらのタイプの反証資料は、テキストの文字列を使用します。
- `service_documentation` や `customer_communication` などのファイルベースの証拠資料。これらのタイプの証拠資料は、[file_upload](https://docs.stripe.com/api/files/object.md#file_object-id) オブジェクト ID を使用します。

> 提出されるテキストベースのすべての反証資料フィールドの合計文字数は、150,000 文字に制限されています。

[File Upload API](https://docs.stripe.com/file-upload.md) を使用して、不審請求の申請の反証資料の一部として書類や画像 (契約書やスクリーンショットなど) を提供できます。まず、`dispute_evidence` の目的で書類をアップロードします。これにより、反証資料を提出する際に使用できる `File_upload` オブジェクトが生成されます。反証資料として提出するファイルをアップロードする前に、そのファイルが [Stripe の推奨事項](https://docs.stripe.com/disputes/best-practices.md#file-upload-recommendations)に適合していることを確認してください。

ファイル 1 つのみ、または大量のプレーンテキストを反証資料として提出する場合は、`uncategorized_text` または `uncategorized_file` を使用します。ただし、不審請求の申請を覆す可能性を高くするために、できるだけ多くのフィールドに入力してください。

## 1 つの支払いに対する複数の不審請求の申請

頻繁に発生するわけではありませんが、顧客が同じ支払いに対して複数の不審請求の申請を行うことがあります。たとえば、ある注文の商品が配送中に破損していた場合、顧客はその商品の支払いに対して部分的に不審請求の申請を行い、その後、同じ注文の別の商品に対して、その商品が正常に機能しないという理由で 2 回目の不審請求の申請を行うというケースが考えられます。

Stripe では、1つの決済に関連しているかどうかにかかわらず、すべての不審請求の申し立てを一意の識別子で区別します。[不審請求の申し立てリスト](https://docs.stripe.com/api/disputes/list.md) で、`PaymentIntent`または`Charge`オブジェクトの `id` を指定し、[payment_intent](https://docs.stripe.com/api/disputes/list.md#list_disputes-payment_intent) または [charge](https://docs.stripe.com/api/disputes/list.md#list_disputes-charge) フィルタを含めることで、特定の決済に関する不審請求の申し立てだけを表示するように結果をフィルタリングすることができます。

#### PaymentIntent 別

```curl
curl -G https://api.stripe.com/v1/disputes \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d payment_intent={{PAYMENT_INTENT_ID}}
```

#### Charge 別

```curl
curl -G https://api.stripe.com/v1/disputes \
  -u "<<YOUR_SECRET_KEY>>:" \
  -d charge={{CHARGE_ID}}
```

1 つの支払いに複数の不審請求の申請がある場合、一覧で返された個々の不審請求の申請に設定された `id` を使用して、不審請求の申請の[取得](https://docs.stripe.com/disputes/api.md#retrieve-a-dispute)または[更新](https://docs.stripe.com/disputes/api.md#update-a-dispute)時にその `id` を指定することで、正しい不審請求の申請に対応していることを確認します。

## 不審請求の申し立てイベントを処理する

不審請求の申し立てが作成されると、Stripe から `charge.dispute.created` イベントが送信されます。[Dispute](https://docs.stripe.com/api/disputes/object.md) オブジェクトには [charge](https://docs.stripe.com/api/disputes/object.md#dispute_object-charge) と Null 許容の [payment_intent](https://docs.stripe.com/api/disputes/object.md#dispute_object-payment_intent) が含まれますが、Invoice や Subscription への直接参照はありません。影響を受ける顧客への通知やアクセス権の調整などのために関連するサブスクリプションを特定する必要がある場合は、[返金、不審請求の申し立て、不正利用の早期警告イベントを処理する](https://docs.stripe.com/billing/subscriptions/webhooks.md#refund-events)を参照してください。

## See also

- [不審請求の申請のカテゴリ](https://docs.stripe.com/disputes/categories.md)
- [不審請求の申請を測定する](https://docs.stripe.com/disputes/measuring.md)
- [不審請求の申請と不正利用の防止](https://docs.stripe.com/disputes/prevention.md)