# Listar MED

Lista os processos MED (Mecanismo Especial de Devolução) associados à conta.

O MED é um mecanismo do Banco Central para recuperação de valores em casos de fraude ou falha operacional no sistema PIX.

## Endpoint

```
GET /api/external/med
```

## Headers

| Header | Tipo | Obrigatório | Descrição |
|--------|------|-------------|-----------|
| `Authorization` | String | Sim | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | Não | Defina como `camelCase` para receber os campos da resposta em camelCase (padrão é snake_case) |

::: info Permissões
Este endpoint requer a permissão `payment:read` na API Key. Chaves sem essa permissão recebem HTTP 403.
:::

## Exemplo

```bash
curl -X GET https://api.monetarie.com/api/external/med \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

::: warning Sem paginação nativa
Este endpoint consulta o provider PIX/BACEN em tempo real e **não aceita parâmetros de paginação** (`page`/`per_page`/`limit`). Todos os MEDs vinculados à entidade são retornados em uma única resposta. Para grandes volumes, filtre localmente no seu sistema após receber o array.
:::

## Resposta de Sucesso (200)

```json
{
  "worked": true,
  "meds": [
    {
      "id": "MED20260307001",
      "type": "REFUND_REQUEST",
      "status": "ACKNOWLEDGED",
      "amount": 50000,
      "original_end_to_end_id": "E46026562202603071530000001",
      "created_at": "2026-03-07T18:00:00Z"
    },
    {
      "id": "MED20260305002",
      "type": "REFUND_CANCELLED",
      "status": "CLOSED",
      "amount": 15000,
      "original_end_to_end_id": "E46026562202603051200000003",
      "created_at": "2026-03-05T14:30:00Z"
    }
  ]
}
```

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `worked` | Boolean | `true` indica sucesso na operação |
| `meds` | Array | Lista de processos MED |
| `meds[].id` | String | Identificador único do MED |
| `meds[].type` | String | Tipo do MED (veja tabela abaixo) |
| `meds[].status` | String | Status atual do processo |
| `meds[].amount` | Integer | Valor em **unidades base** (÷ 10.000 para reais). `50000` = R$ 5,00 |
| `meds[].original_end_to_end_id` | String | E2E da transação PIX original |
| `meds[].created_at` | String | Data de abertura (ISO 8601) |

## Tipos de MED

| Tipo | Descrição |
|------|-----------|
| `REFUND_REQUEST` | Solicitação de devolução (fraude, golpe ou acordo) |
| `REFUND_CANCELLED` | Cancelamento de solicitação de devolução anterior |

## Status do MED

Valores retornados pelo provider PIX (PIX/BACEN) em **UPPERCASE**. A API repassa o valor tal como recebido - não há normalização.

| Status | Descrição | Decisão final |
|--------|-----------|---------------|
| `ACKNOWLEDGED` | MED recebido e reconhecido pelo participante, em análise | Não - aguarda defesa ou prazo |
| `CLOSED` | MED finalizado pelo participante | Sim - veja `analysisResult` em [med-detail](/med-detail) para distinguir `AGREED` (devolução executada) de `DISAGREED` (defesa aceita, sem devolução) |
| `CANCELLED` | MED cancelado pelo solicitante antes da análise | Sim - nenhum valor foi bloqueado nem devolvido |

::: warning Status é uppercase
Os status do MED são sempre retornados em **MAIÚSCULAS**. Se o seu filtro espera minúsculas (`pending`/`accepted`/`closed`), ele não vai encontrar nenhuma linha. Esta é uma diferença consciente em relação aos status de transação PIX (lowercase) - MED segue a convenção BACEN original.
:::

::: tip Correlação com transação original
Use o campo `original_end_to_end_id` para localizar a transação PIX original que motivou o MED. Consulte via `GET /api/external/transactions/:id` ou `GET /api/external/transactions/ref/:external_id` se você armazenou o `external_id`.
:::

::: info Retorno em ambientes dev/homologação
Este endpoint consulta o provider PIX diretamente - **não lê de tabela local**. Em dev/homologação pode retornar array vazio se o provedor PIX não tiver MEDs de teste para a entidade configurada. Em produção, retorna a lista real de processos MED da sua conta conforme repassada pelo PIX/BACEN.
:::

::: warning Falhas no provedor são explícitas
Se houver indisponibilidade temporária do provedor PIX, o endpoint retorna HTTP
`502` com `worked: false`. Um array vazio com HTTP `200` significa que a consulta
foi concluída e não encontrou MEDs; ele nunca representa silenciosamente um timeout.
:::

## Resposta de Sucesso -- Sem MEDs (200)

```json
{
  "worked": true,
  "meds": []
}
```

## Resposta de Erro -- Provedor indisponível (502)

```json
{
  "worked": false,
  "errors": {
    "bad_gateway": "serviço MED temporariamente indisponível"
  }
}
```

## Resposta de Erro (401)

```json
{
  "worked": false,
  "errors": {
    "unauthorized": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}
```

::: warning Valores em disputa
Quando um MED exige análise, o valor disputado pode ficar temporariamente reservado e aparecer em `pending` até a decisão final.

Quando o MED é resolvido (`CLOSED`):
- `AnalysisResult=AGREED` indica contestação aceita e devolução executada.
- `AnalysisResult=DISAGREED` indica contestação rejeitada ou defesa aceita, sem devolução.

Assine os webhooks [`pix.infraction.created`](/webhooks-payloads#pix-infraction-created), [`pix.refund.requested`](/webhooks-payloads#pix-refund-requested), [`pix.infraction.defense_submitted`](/webhooks-payloads#pix-infraction-defense-submitted) e [`pix.infraction.resolved`](/webhooks-payloads#pix-infraction-resolved) para acompanhar cada etapa. Para responder um MED pela API, use `POST /api/external/med/:id/defense` com permissão `payment:write`. Ver [Infrações](/infractions).
:::