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

# Como responder a disputas

> Guia operacional para acompanhar uma disputa, preparar a documentação e enviar a contestação para análise dentro do prazo.

Uma **disputa** acontece quando o portador questiona uma cobrança de cartão.
Quando isso acontece, a Chargefy cria um objeto `dispute` ligado à `charge`
original e abre um prazo para envio de evidências.

Este guia mostra o que fazer quando uma disputa é criada, quais arquivos são
aceitos, como enviar a contestação e como acompanhar a decisão.

<Info>
  O prazo de defesa é de **7 dias corridos** a partir da emissão da notificação.
  Use o campo `evidence_details.due_by` do `dispute` como fonte de verdade para
  o prazo.
</Info>

## Resumo do fluxo

1. Receba o webhook `charge.dispute.created` ou veja a disputa no Dashboard.
2. Consulte o `dispute` e confirme `status`, `reason`, `charge` e
   `evidence_details.due_by`.
3. Reúna todos os documentos em **um único arquivo**.
4. Faça upload da evidência antes do prazo.
5. Envie a contestação para análise.
6. Acompanhe `charge.dispute.updated` e `charge.dispute.closed` até a decisão
   final.

```mermaid theme={}
stateDiagram-v2
  [*] --> needs_response: Disputa criada
  needs_response --> under_review: Contestação enviada
  needs_response --> lost: Contestação concedida
  under_review --> won: Defesa aceita
  under_review --> lost: Defesa recusada
```

## O que muda quando a disputa nasce

Quando o `dispute` é criado, ele normalmente começa em `needs_response`.
Nesse estado, a organização ainda pode enviar evidências.

Campos importantes:

| Campo                               | Como usar                                                                           |
| ----------------------------------- | ----------------------------------------------------------------------------------- |
| `id`                                | ID da disputa (`dp_*`). Use em consultas, upload e envio para análise.              |
| `charge`                            | Charge contestada (`ch_*`). Use para reconciliar com pedido, invoice ou assinatura. |
| `amount`                            | Valor contestado, em centavos.                                                      |
| `customer`                          | Customer relacionado, quando disponível.                                            |
| `evidence_details.due_by`           | Prazo final para envio da contestação.                                              |
| `evidence_details.has_evidence`     | Indica se já existe arquivo associado.                                              |
| `evidence_details.submission_count` | Quantidade de envios para análise já feitos.                                        |
| `reason`                            | Motivo normalizado quando disponível. Pode ser `null`.                              |
| `status`                            | Estado atual da disputa.                                                            |

<Note>
  No 8º dia corrido, pode haver ajuste financeiro relacionado à contestação.
  Isso não significa decisão final. O `dispute` público permanece em
  `under_review` enquanto a análise final estiver em andamento.
</Note>

## Prazos e estados

| Momento             | O que acontece                                          | O que você deve fazer                                    |
| ------------------- | ------------------------------------------------------- | -------------------------------------------------------- |
| Dia 0               | Disputa criada em `needs_response`.                     | Comece a reunir documentos imediatamente.                |
| Até 7 dias corridos | A contestação ainda pode ser enviada.                   | Faça upload do arquivo e envie para análise.             |
| Dia 8 em diante     | A disputa segue em análise quando a defesa foi enviada. | Acompanhe webhooks e reconciliação financeira.           |
| Decisão final       | O `status` muda para `won` ou `lost`.                   | Trate `charge.dispute.closed` e atualize seu backoffice. |

A decisão final pode levar semanas e, em alguns casos, até cerca de 120 dias.
Evite fazer polling agressivo: use webhooks para acompanhar a mudança de
estado.

## Requisitos do arquivo

A defesa deve ser consolidada em **um único arquivo**. A Chargefy não aceita
múltiplos anexos para a mesma submissão.

| Requisito              | Valor                            |
| ---------------------- | -------------------------------- |
| Formato                | PDF ou TIF                       |
| Tamanho máximo         | 7 MB                             |
| Quantidade de arquivos | 1 arquivo                        |
| PDF                    | Até 10 páginas                   |
| Resolução              | Até 200 DPI                      |
| Orientação             | Páginas verticais                |
| Cor                    | Preferencialmente preto e branco |

Também recomendamos:

* Não envie arquivo protegido por senha.
* Não envie páginas em branco.
* Use nomes de arquivo simples, sem caracteres especiais.
* Garanta que textos, comprovantes e datas estejam legíveis.
* Consolide prints, comprovantes, conversas e recibos no mesmo PDF/TIF.

<Warning>
  Se o arquivo estiver ilegível, exceder o limite ou for enviado fora do prazo,
  a contestação pode não ser analisada. O upload valida formato, tamanho e
  contagem de páginas do PDF; qualidade visual e conteúdo continuam sendo
  responsabilidade da organização.
</Warning>

## O que incluir na defesa

Monte o documento pensando em uma pessoa que não conhece a venda. O arquivo
precisa explicar por que a cobrança é legítima ou por que o produto/serviço foi
entregue corretamente.

### Fraude ou cobrança não reconhecida

Inclua evidências que conectem o comprador à transação:

* Recibo ou comprovante de compra.
* Dados de autenticação, login, IP, dispositivo ou aceite de termos, quando
  existirem.
* Comprovante de entrega, uso, acesso ou ativação do serviço.
* Comunicação com o comprador reconhecendo a compra.
* Em casos de fraude, inclua o vínculo com **Mensagem Emissor** quando
  aplicável.

### Produto não recebido

Inclua evidências de entrega ou disponibilização:

* Código de rastreio, comprovante de postagem ou comprovante de entrega.
* Data e endereço de entrega.
* Logs de acesso, ativação ou download em produtos digitais.
* Histórico de atendimento mostrando resolução ou tentativa de contato.

### Produto inaceitável, cancelamento ou desacordo comercial

Inclua contexto comercial:

* Descrição do produto/serviço vendido.
* Política de cancelamento, troca ou reembolso aceita pelo comprador.
* Comprovante de aceite dos termos.
* Conversas de suporte.
* Evidências de que o serviço foi prestado ou que o produto estava de acordo
  com a oferta.

### Duplicidade, crédito não processado ou assinatura cancelada

Inclua linha do tempo e conciliação:

* IDs das cobranças relacionadas.
* Comprovantes de refund, cancelamento ou ausência de refund.
* Histórico de invoices, assinaturas ou pedidos.
* Datas de cobrança, cancelamento e comunicação com o cliente.

## Enviar pelo Dashboard

Use este caminho quando a operação é feita por uma pessoa da organização.

1. Acesse o Dashboard da Chargefy.
2. Entre em **Financeiro → Disputas**.
3. Abra a disputa.
4. Confira o prazo, valor, charge e customer.
5. Faça upload do arquivo PDF/TIF.
6. Revise o checklist exibido na tela.
7. Clique em **Enviar à análise**.
8. Acompanhe o histórico de envios na própria disputa.

Se a organização decidir não defender a cobrança, use **Encerrar**. Essa ação
concede a contestação e muda o `dispute` para `lost`.

## Enviar pela API

Use este caminho quando seu sistema opera disputas server-to-server. Para
plataformas, inclua o header `Organization` com a organização conectada que
originou a disputa.

### 1. Consulte a disputa

```bash theme={}
curl -X GET "https://api.chargefy.io/v1/disputes/dp_123" \
  -H "Authorization: Bearer {{API_KEY}}"
```

Resposta resumida:

```json theme={}
{
  "id": "dp_123",
  "object": "dispute",
  "amount": 15000,
  "charge": "ch_123",
  "created_at": "2026-05-22T03:00:00Z",
  "currency": "brl",
  "evidence_details": {
    "due_by": "2026-05-29T03:00:00Z",
    "has_evidence": false,
    "past_due": false,
    "submission_count": 0
  },
  "reason": "fraudulent",
  "status": "needs_response"
}
```

Veja o contrato completo em [Consultar dispute](/api-reference/disputes/get).

### 2. Faça upload do arquivo

Envie exatamente um arquivo no campo `file`.

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/dispute-evidence-upload" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -F "dispute_id=dp_123" \
  -F "file=@/caminho/local/defesa.pdf;type=application/pdf"
```

Para API key de plataforma:

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/dispute-evidence-upload" \
  -H "Authorization: Bearer {{PLATFORM_API_KEY}}" \
  -H "Organization: org_123" \
  -F "dispute_id=dp_123" \
  -F "file=@/caminho/local/defesa.pdf;type=application/pdf"
```

Erros comuns de upload:

| Status | Quando ocorre                                                                                                          |
| ------ | ---------------------------------------------------------------------------------------------------------------------- |
| `400`  | Arquivo ausente, mais de um arquivo, MIME inválido, PDF sem contagem de páginas legível ou PDF com mais de 10 páginas. |
| `400`  | Arquivo acima de 7 MB.                                                                                                 |
| `404`  | Disputa não encontrada na organização autenticada.                                                                     |
| `409`  | Disputa já fechada.                                                                                                    |

### 3. Envie para análise

Depois do upload, envie `submit: true` no dispute.

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/disputes/dp_123" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "submit": true
  }'
```

Você também pode atualizar `metadata` e evidências textuais antes do envio:

```bash theme={}
curl -X POST "https://api.chargefy.io/v1/disputes/dp_123" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -d '{
    "evidence": {
      "customer_communication": "Conversation and receipt attached."
    },
    "metadata": {
      "case_owner": "ops"
    },
    "submit": true
  }'
```

Se o envio for aceito, o `dispute` passa para `under_review`.

<Warning>
  `POST /v1/disputes/{id}/close` não envia defesa. Essa ação concede a
  contestação e retorna o `dispute` como `lost`.
</Warning>

## Webhooks que você deve tratar

Configure seu endpoint para receber estes eventos:

| Evento                                                                     | Quando tratar                                                          |
| -------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [`charge.dispute.created`](/api-reference/webhooks/charge.dispute.created) | Abrir tarefa operacional e iniciar coleta de evidências.               |
| [`charge.dispute.updated`](/api-reference/webhooks/charge.dispute.updated) | Atualizar status interno, evidência enviada ou contagem de submissões. |
| [`charge.dispute.closed`](/api-reference/webhooks/charge.dispute.closed)   | Registrar decisão final como `won` ou `lost`.                          |

Em plataformas, use o campo top-level `organization` do webhook para identificar
a organização conectada que originou a disputa.

## Checklist operacional

Antes de clicar em **Enviar à análise** ou enviar `submit: true`, confirme:

* O prazo `evidence_details.due_by` ainda não expirou.
* O arquivo é PDF ou TIF.
* O arquivo tem no máximo 7 MB.
* O PDF tem até 10 páginas.
* O documento está legível, vertical e preferencialmente em preto e branco.
* Todas as evidências estão consolidadas em um único arquivo.
* A defesa explica o contexto da compra, entrega, uso ou cancelamento.
* Seu sistema está preparado para receber `charge.dispute.closed`.

## Erros comuns

| Situação                  | Como evitar                                                                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| Perder o prazo            | Crie automação interna no recebimento de `charge.dispute.created` e trate `due_by` como prazo fatal.                |
| Enviar vários arquivos    | Consolide tudo em um único PDF/TIF antes do upload.                                                                 |
| Arquivo ilegível          | Revise o PDF/TIF como se fosse uma impressão: texto pequeno, cortes e páginas tortas reduzem a chance de análise.   |
| Enviar defesa sem arquivo | Primeiro faça upload, depois envie `submit: true`.                                                                  |
| Conceder por engano       | Use `close` somente quando a organização decidiu aceitar a perda da contestação.                                    |
| Ignorar `closed`          | A decisão final pode chegar muito depois do envio; trate `charge.dispute.closed` para fechar o caso no seu sistema. |