# Usa la API para responder las disputas

Más información sobre cómo manejar las disputas mediante programación.

Puedes gestionar disputas mediante programación utilizando la API. Con la API, puedes subir evidencia, responder a disputas y recibir eventos de disputas utilizando webhooks.

Si deseas gestionar disputas utilizando el Dashboard en lugar de la API, consulta [Responder a disputas](https://docs.stripe.com/disputes/responding.md).

## Recupera una disputa

Para obtener detalles sobre una disputa, [recupera](https://docs.stripe.com/api/disputes/retrieve.md) un objeto `Dispute`:

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

La respuesta contiene información acerca de la disputa y toda respuesta o evidencia que ya se haya proporcionado.

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

## Actualiza una disputa

Debes [actualizar](https://docs.stripe.com/api/disputes/update.md) el objeto `Dispute` y pasar la evidencia estructurada con el 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}}"
```

Con el fin de ver todos los campos disponibles para el parámetro `evidence`, consulta la sección [Evidencia de la disputa](https://docs.stripe.com/api/disputes/update.md#update_dispute-evidence). Hay dos tipos de evidencia que puedes proporcionar, según el campo que estés actualizando:

- Evidencia basada en texto, como `customer_email` y `service_date`. Estos tipos de evidencia requieren una cadena de texto.
- Evidencia basada en archivos, como `service_documentation` y `customer_communication`. Este tipo de evidencia requiere el ID de objeto de [file_upload](https://docs.stripe.com/api/files/object.md#file_object-id).

> El total de caracteres combinados para todas las presentaciones de campos de evidencia basada en texto se limita a 150,000.

Puedes proporcionar documentos o imágenes (por ejemplo, un contrato o una captura de pantalla) como parte de la evidencia para una disputa usando la [Carga del archivo en la API](https://docs.stripe.com/file-upload.md). En primer lugar, cargas un documento con `dispute_evidence` como propósito, y eso genera un objeto `File_upload` que podrás utilizar para presentar la evidencia. Asegúrate de que el archivo cumpla con las [recomendaciones de Stripe](https://docs.stripe.com/disputes/best-practices.md#file-upload-recommendations) antes de cargarlo y enviarlo como evidencia.

Si solo te interesa presentar un único archivo o una gran cantidad de texto sin formato como evidencia, usa los parámetros `uncategorized_text` o `uncategorized_file`. Sin embargo, debes completar la mayor cantidad posible de campos para poder tener la mejor oportunidad de anular una disputa.

## Múltiples disputas en un solo pago

Aunque no sucede con frecuencia, es posible que un cliente dispute el mismo pago más de una vez. Por ejemplo, un cliente puede disputar parcialmente el pago de uno de los artículos de un pedido si se dañó durante la entrega, y luego presentar una segunda disputa por un artículo diferente del mismo pedido debido a que no funcionó correctamente.

Stripe distingue todas las disputas por un identificador único, independientemente de si están relacionadas con un solo pago. Cuando [enumeras disputas](https://docs.stripe.com/api/disputes/list.md), puedes filtrar los resultados para mostrar solo disputas para un pago particular especificando el `id` del objeto `PaymentIntent` o `Charge` e incluyendo el filtro [payment_intent](https://docs.stripe.com/api/disputes/list.md#list_disputes-payment_intent) o [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 Charge

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

Cuando un pago tiene varias disputas, usa la `id` proporcionada para cada disputa que aparece en la lista. De esta manera, te asegurarás de que estás respondiendo a la disputa correcta. Para eso, especifica su `id` cuando [recuperas](https://docs.stripe.com/disputes/api.md#retrieve-a-dispute) o [actualizas la disputa](https://docs.stripe.com/disputes/api.md#update-a-dispute).

## See also

- [Categorías de disputas](https://docs.stripe.com/disputes/categories.md)
- [Medición de disputas](https://docs.stripe.com/disputes/measuring.md)
- [Cómo prevenir las disputas y el fraude](https://docs.stripe.com/disputes/prevention.md)