# Use a API para responder a contestações

Aprenda a programar a gestão de contestações.

Você pode gerenciar contestações automaticamente usando a API. Com a API, você pode enviar comprovantes, responder a contestações e receber eventos de contestação usando webhooks.

Se você quiser gerenciar contestações usando o Dashboard em vez de usar a API, consulte [Responder a contestações](https://docs.stripe.com/disputes/responding.md).

## Recuperar uma contestação

Para obter detalhes sobre uma contestação, [recupere](https://docs.stripe.com/api/disputes/retrieve.md) um objeto `Dispute`:

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

A resposta contém informações sobre a contestação e todas as respostas ou comprovantes já fornecidos.

```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
  }
  ...
}
```

## Atualizar uma contestação

Você [atualiza](https://docs.stripe.com/api/disputes/update.md) o objeto `Dispute` e passa comprovantes estruturados com o parâmetro `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}}"
```

Para visualizar todos os campos disponíveis para o parâmetro `evidence`, consulte [Comprovante de contestação](https://docs.stripe.com/api/disputes/update.md#update_dispute-evidence). Há dois tipos de comprovantes que você pode fornecer, dependendo do campo que está sendo atualizado:

- Comprovantes em texto, como `customer_email` e `service_date`. Esse tipo de comprovante é uma string de texto.
- Comprovantes estabelecidos em arquivos, como `service_documentation` e `customer_communication` recebem um ID de objeto [file_upload](https://docs.stripe.com/api/files/object.md#file_object-id).

> O limite de caracteres para a soma de todos os envios do campo de comprovantes é de 150.000.

Para fornecer documentos ou imagens (como contratos ou capturas de tela) como comprovantes para a contestação, use a [API File Upload](https://docs.stripe.com/file-upload.md). Primeiro, você carrega um documento com a finalidade de `dispute_evidence`, a qual gera um objeto `File_upload` que você pode usar ao enviar comprovantes. Confira as [recomendações da Stripe](https://docs.stripe.com/disputes/best-practices.md#file-upload-recommendations) antes de enviar arquivos como comprovantes.

Se quiser enviar um único arquivo ou uma grande quantidade de texto simples como comprovante, use `uncategorized_text` ou `uncategorized_file`. No entanto, preencha o máximo de campos possível para ter a melhor chance de reverter uma contestação.

## Várias contestações em um único pagamento

Não é comum, mas um cliente pode contestar o mesmo pagamento mais de uma vez. Por exemplo, um cliente pode contestar parcialmente o pagamento de um dos itens em um pedido se ele foi danificado na entrega e, em seguida, registrar uma segunda contestação contra um item diferente no mesmo pedido porque o item não funcionou corretamente.

A Stripe distingue todas as contestações por um identificador único, independentemente de estarem relacionadas a um único pagamento. Quando você [lista contestações](https://docs.stripe.com/api/disputes/list.md), pode filtrar os resultados para mostrar apenas contestações de um pagamento específico, especificando a `id` do objeto `PaymentIntent` ou `Charge` e incluindo o filtro [payment_intent](https://docs.stripe.com/api/disputes/list.md#list_disputes-payment_intent) ou [charge](https://docs.stripe.com/api/disputes/list.md#list_disputes-charge).

#### Por PaymentIntent

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

#### Por cobrança

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

Quando um pagamento tem várias contestações, use o `id` fornecido para cada contestação retornada na lista para assegurar que está respondendo à contestação correta ao especificar `id` quando você [recupera](https://docs.stripe.com/disputes/api.md#retrieve-a-dispute) ou [atualiza a contestação](https://docs.stripe.com/disputes/api.md#update-a-dispute).

## See also

- [Categorias de contestação](https://docs.stripe.com/disputes/categories.md)
- [Avaliação de contestações](https://docs.stripe.com/disputes/measuring.md)
- [Como evitar contestações e fraudes](https://docs.stripe.com/disputes/prevention.md)