> ## Documentation Index
> Fetch the complete documentation index at: https://docs.purincash.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Disputas

> O cliente contestou o PIX. O que fica retido, o que você manda e em quanto tempo.

Disputa é o mecanismo de contestação do PIX (MED). Quando o comprador aciona o banco
dizendo que não recebeu o produto, o valor daquela transação fica retido no seu saldo até
a operadora decidir.

Enquanto está aberta, o valor aparece em `disputeBlocked` na [carteira](/guias/carteira) e
sai do `withdrawable`. Não dá pra sacar o que está contestado.

<Info>
  Disputas não existem em sandbox. Os endpoints respondem `404` com chave `ps_test_`,
  porque contestação nasce de uma transação real.
</Info>

## Monitorando

```bash theme={null}
curl "https://api.purincash.com/v1/disputes?status=aberta&limit=50" \
  -H "Authorization: Bearer $PURINCASH_KEY"
```

```json theme={null}
{
  "disputes": [
    {
      "id": "665f1a2b3c4d5e6f7a8b9c0d",
      "code": "MED-2024-001",
      "endToEndId": "E123456782026...",
      "orderCode": "JUE7Y9MPSX",
      "buyer": "João Silva",
      "product": "Plano Premium",
      "amount": 23.07,
      "reason": "Produto não recebido",
      "status": "aberta",
      "evidences": [],
      "resolvedAt": null,
      "createdAt": "2026-03-18T10:00:00.000Z"
    }
  ],
  "total": 3,
  "limit": 50,
  "offset": 0
}
```

Status possíveis: `aberta`, `resolvida` e `perdida`.

<Tip>
  Vale rodar essa listagem uma vez por dia filtrando por `aberta`. Disputa tem prazo, e
  perder por não ter respondido é o pior jeito de perder.
</Tip>

## Respondendo

Só disputa com status `aberta` aceita evidência. Você pode mandar documentos, um texto que
vira PDF, ou os dois.

```bash theme={null}
curl -X POST https://api.purincash.com/v1/disputes/665f1a2b3c4d5e6f7a8b9c0d/evidence \
  -H "Authorization: Bearer $PURINCASH_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "documents": [
      {
        "url": "https://minhaloja.com/comprovantes/1042.pdf",
        "description": "Comprovante de entrega",
        "correlationID": "MED-2024-001-EV1"
      }
    ],
    "textForPdf": "Produto entregue em 15/03 às 10h05. Acesso registrado pelo IP do comprador em 15/03 às 10h12."
  }'
```

```json Resposta 200 theme={null}
{ "uploaded": 2 }
```

<ParamField body="documents" type="array">
  Até 10 itens. Cada um precisa de `url` http ou https. Itens sem URL válida são
  descartados em silêncio.
</ParamField>

<ParamField body="textForPdf" type="string">
  Texto convertido automaticamente em PDF de defesa. Serve sozinho, sem `documents`.
</ParamField>

Um dos dois é obrigatório. Sem nenhum, a resposta é `400`.

<Warning>
  As URLs precisam apontar direto para o arquivo (PDF, PNG, JPEG ou WebP). Link de página
  HTML, tipo encurtador de print, é recusado pela operadora. Se o seu comprovante está numa
  página, gere um PDF e hospede o arquivo.
</Warning>

## O que costuma funcionar como evidência

<CardGroup cols={2}>
  <Card title="Prova de entrega" icon="truck">
    Log de acesso, e-mail de entrega com data e hora, código de rastreio, print do sistema
    mostrando a liberação.
  </Card>

  <Card title="Prova de aceite" icon="file-signature">
    Termos aceitos, confirmação de recebimento, conversa em que o comprador reconhece que
    recebeu.
  </Card>

  <Card title="Identidade do comprador" icon="fingerprint">
    O `endToEndId` da transação, o e-mail usado na compra, o `externalId` que amarra ao
    usuário da sua base.
  </Card>

  <Card title="Contexto de uso" icon="chart-line">
    Histórico mostrando que a conta foi usada depois da compra. É o que mais derruba
    "produto não recebido".
  </Card>
</CardGroup>

<Tip>
  Junte a evidência de forma programática assim que o pagamento confirma, não quando a
  disputa chega. Trinta dias depois o log já rotacionou e o print não existe mais.
</Tip>

## Consultando uma disputa

```bash theme={null}
curl https://api.purincash.com/v1/disputes/665f1a2b3c4d5e6f7a8b9c0d \
  -H "Authorization: Bearer $PURINCASH_KEY"
```

O retorno traz as evidências já enviadas, com URLs assinadas que são regeneradas a cada
consulta. Elas expiram, então não vale guardar a URL: guarde o id e consulte de novo
quando precisar.

Disputa que não é da sua conta responde `404`, e não `403`. É proposital: a API não
confirma a existência de recurso de terceiro.

## Erros

| Código | Motivo                                                                                                      |
| ------ | ----------------------------------------------------------------------------------------------------------- |
| `400`  | Disputa já resolvida, corpo sem `documents` nem `textForPdf`, nenhuma URL válida, ou ID em formato inválido |
| `404`  | Disputa inexistente, de outra conta, ou chamada em sandbox                                                  |
| `502`  | Falha ao enviar a evidência à operadora. Tente de novo                                                      |
| `503`  | Provedor de pagamento não configurado                                                                       |