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

# Reembolsos

> Leia a fila de pedidos de reembolso, aprove ou recuse com motivo, exporte o histórico e acompanhe contestações de cartão.

Quando o comprador pede o dinheiro de volta pelo formulário da Ephra, nasce uma **solicitação de reembolso** — e ela espera a sua decisão. Este domínio tem 7 operações: a fila, as duas decisões, a exportação, o quiz de retenção e as contestações de cartão.

<Info>
  Se a decisão já foi tomada fora da Ephra e você só quer devolver o dinheiro, o caminho é outro: `POST /v1/transactions/{transactionId}/refund`, em [Vendas](/guias/vendas).
</Info>

## 1. Leia a fila

```bash theme={null}
curl -s "https://api.ephra.io/v1/refund-requests?page=1&pageSize=5&status=pending" \
  -H "Authorization: Bearer $TOKEN"
```

Fila vazia é uma resposta bem-sucedida com `data` vazio:

```json theme={null}
{
  "success": true,
  "data": [],
  "pagination": { "page": 1, "pageSize": 5, "total": 0, "totalPages": 0 }
}
```

Sem o filtro, você vê o histórico inteiro:

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": 13,
      "transactionId": "cmtxyt3710000eag1smxe72ee",
      "status": "approved",
      "reason": "Comprador desistiu dentro do prazo de garantia de 7 dias.",
      "reasonType": "manual",
      "requestedBy": "gateway:webhook",
      "rejectionReason": null,
      "approvalReason": null,
      "reviewedAt": "2026-09-12T05:50:11.786Z",
      "autoApproveAt": null,
      "amount": 49900,
      "paymentMethod": "pix",
      "refundChannel": null,
      "customer": {
        "name": "Mariana Ribeiro Alves",
        "email": "mariana.alves@empresadela.com.br",
        "document": "39053344705",
        "phone": "+5521997766554"
      },
      "items": [
        { "id": 32, "name": "Curso de Tráfego Pago", "quantity": 1, "unitPrice": 49900 }
      ],
      "createdAt": "2026-09-12T05:50:09.016Z",
      "updatedAt": "2026-09-12T05:50:11.788Z"
    }
  ],
  "pagination": { "page": 1, "pageSize": 5, "total": 1, "totalPages": 1 }
}
```

Os campos que decidem o seu fluxo:

| Campo           | Para quê                                                                        |
| --------------- | ------------------------------------------------------------------------------- |
| `status`        | `pending` espera decisão; `approved` e `rejected` já foram resolvidos           |
| `autoApproveAt` | Quando a Ephra aprova sozinha se você não responder. `null` significa sem prazo |
| `requestedBy`   | Quem abriu: o comprador, o painel, ou um webhook do adquirente                  |
| `reasonType`    | Se o motivo veio de um formulário livre (`manual`) ou de uma opção do quiz      |
| `amount`        | Valor em centavos que volta ao comprador                                        |

<Warning>
  `autoApproveAt` é o relógio correndo contra você. Se a sua integração só varre a fila uma vez por dia, pedidos com prazo curto serão aprovados automaticamente antes de você olhar. Ordene por `autoApproveAt` e trate os mais próximos primeiro.
</Warning>

Filtros disponíveis: `status`, `refundChannel`, `startDate`, `endDate` e `search` (nome, e-mail ou documento do comprador).

## 2. Aprove

```bash theme={null}
curl -s -X POST https://api.ephra.io/v1/refund-requests/48127/approve \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Comprador relatou falha de acesso à área de membros."}'
```

```json theme={null}
{
  "success": true,
  "data": {
    "id": 48127,
    "status": "approved",
    "refundChannel": "api",
    "message": "Reembolso aprovado e processado no gateway com sucesso."
  }
}
```

`refundChannel: "api"` confirma que o estorno saiu pelo adquirente na hora. Leia esse campo: se ele voltar diferente, o dinheiro ainda não saiu e o caso precisa de acompanhamento manual.

<Warning>
  Aprovar é **irreversível** e tira dinheiro do seu saldo imediatamente. Não há rota de desfazer.
</Warning>

## 3. Recuse

```bash theme={null}
curl -s -X POST https://api.ephra.io/v1/refund-requests/48127/reject \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Prazo de garantia de 7 dias encerrado e o curso foi assistido por completo."}'
```

```json theme={null}
{
  "success": true,
  "data": {
    "id": 48127,
    "status": "rejected",
    "message": "Solicitação de reembolso rejeitada."
  }
}
```

A `reason` da recusa vai para o comprador. Escreva uma frase que você defenderia numa reclamação — ela é o seu argumento se o caso virar contestação de cartão.

Um id que não existe (ou que é de outra empresa) responde `404`:

```json theme={null}
{ "success": false, "message": "Solicitação de reembolso não encontrada." }
```

## 4. Exporte o histórico

```bash theme={null}
curl -s "https://api.ephra.io/v1/refund-requests/export?status=approved&startDate=2026-08-01T00:00:00.000Z&endDate=2026-08-31T23:59:59.000Z" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": {
    "filename": "reembolsos-2026-09-12.xlsx",
    "base64": "UEsDBAoAAAAIAIMzLF2R28AJWQEAAPAEAAATAAAAW0NvbnRlbnRfVHlwZXNdLnhtbK2U...",
    "total": 0,
    "truncated": false
  }
}
```

Diferente da exportação de vendas, aqui o arquivo é **XLSX em base64** — decodifique antes de gravar:

```bash theme={null}
curl -s "https://api.ephra.io/v1/refund-requests/export?status=approved" \
  -H "Authorization: Bearer $TOKEN" \
  | jq -r '.data.base64' | base64 -d > reembolsos.xlsx
```

`truncated: true` avisa que o recorte estourou o limite do arquivo: aperte o intervalo de datas e exporte em partes.

## 5. Entenda por que pediram

Antes de abrir a solicitação, o comprador responde um quiz de retenção. As respostas dizem se o problema é o produto, a entrega ou a expectativa de venda.

```bash theme={null}
curl -s "https://api.ephra.io/v1/refund-quiz-attempts?page=1&pageSize=5&onlyCompleted=true" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": [],
  "pagination": { "page": 1, "pageSize": 5, "total": 0, "totalPages": 0 }
}
```

`onlyCompleted=true` descarta quem abandonou o quiz no meio — normalmente quem desistiu de pedir o reembolso.

## 6. Acompanhe as contestações

Contestação (chargeback ou MED do Pix) é diferente de reembolso: quem abre é o banco do comprador, e o dinheiro sai com ou sem a sua concordância.

```bash theme={null}
curl -s "https://api.ephra.io/v1/infractions?page=1&pageSize=5" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "success": true,
  "data": [],
  "pagination": { "page": 1, "pageSize": 5, "total": 0, "totalPages": 0 }
}
```

O evento em tempo real equivalente é [`infraction`](/webhooks/eventos/infracoes). Aprovar um reembolso antes que a contestação avance costuma sair mais barato do que perdê-la.

## Todas as operações do domínio

<CardGroup cols={2}>
  <Card title="Solicitações" icon="inbox" href="/api-reference/reembolsos/listar-solicitações-de-reembolso">
    A fila, com todos os filtros.
  </Card>

  <Card title="Aprovar e recusar" icon="gavel" href="/api-reference/reembolsos/aprovar-reembolso">
    As duas decisões, cada uma com o seu motivo.
  </Card>

  <Card title="Quiz de retenção" icon="clipboard-question" href="/api-reference/reembolsos/listar-respostas-do-quiz-de-reembolso">
    O que o comprador respondeu antes de pedir.
  </Card>

  <Card title="Contestações" icon="scale-balanced" href="/api-reference/reembolsos/listar-infrações-e-disputas">
    Chargebacks e MEDs abertos contra a empresa.
  </Card>
</CardGroup>