# Detalhes MED

Consulta os detalhes completos de um processo MED (Mecanismo Especial de Devolução) específico.

## Endpoint

```
GET /api/external/med/:id
```

## 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) |

## Path Parameters

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `id` | String | Sim | Identificador do processo MED |

## Exemplo

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

## Resposta de Sucesso (200)

```json
{
  "worked": true,
  "med": {
    "id": "MED20260307001",
    "type": "REFUND_REQUEST",
    "status": "ACKNOWLEDGED",
    "amount": 50000,
    "original_end_to_end_id": "E46026562202603071530000001",
    "reason": "Fraude reportada pelo pagador",
    "created_at": "2026-03-07T18:00:00Z"
  }
}
```

::: tip Status em UPPERCASE
Valores possíveis: `ACKNOWLEDGED`, `CLOSED`, `CANCELLED`. Repassados tal como recebidos do provider PIX (PIX/BACEN) - sem normalização. Ver [med-list](/med-list#status-do-med) para detalhes.
:::

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `worked` | Boolean | `true` indica sucesso na operação |
| `med.id` | String | Identificador único do MED |
| `med.type` | String | Tipo: `REFUND_REQUEST` ou `REFUND_CANCELLED` |
| `med.status` | String | Status atual do processo (`ACKNOWLEDGED`, `CLOSED`, `CANCELLED`) |
| `med.amount` | Integer | Valor em **unidades base** (÷ 10.000 para reais). `50000` = R$ 5,00 |
| `med.original_end_to_end_id` | String | E2E da transação PIX original. Use para cruzar com `GET /transactions/ref/:external_id` |
| `med.reason` | String | Motivo informado pelo solicitante (texto livre). `null` se não disponível |
| `med.created_at` | String | Data de abertura (ISO 8601 UTC) |

::: info Campos adicionais não expostos via External API
O provedor PIX/BACEN retorna mais campos do que os expostos por este endpoint. Os campos filtrados deliberadamente no serializer incluem:

| Campo (provedor) | Descrição | Onde obter hoje |
|---|---|---|
| `analysisResult` | Decisão final: `AGREED` ou `DISAGREED` | Webhook [`pix.infraction.resolved`](/webhooks-payloads#pix-infraction-resolved) |
| `analysisDetails` | Justificativa da decisão | Webhook [`pix.infraction.resolved`](/webhooks-payloads#pix-infraction-resolved) |
| `infractionType` | `REFUND_REQUEST` ou `REFUND_CANCELLED` | Já exposto em `med.type` |
| `fraudType` | `SCAM`, `ACCOUNT_TAKEOVER`, `COERCION`, `FRAUDULENT_ACCESS`, `OTHER` | Webhook `pix.refund.requested` (campo `fraud_category`) |
| `situationType` | Tipo de situação envolvida (BACEN taxonomy) | Exibido no portal quando aplicável |
| `defenseDeadline` | Prazo BACEN para submissão de defesa | Webhook [`pix.infraction.created`](/webhooks-payloads#pix-infraction-created) |

Para integração programática, use os webhooks listados nesta página e os endpoints públicos de consulta e defesa MED.

Ver [Infrações (fluxo completo)](/infractions) para entender a relação entre MED e Infrações.
:::

::: warning Consulta e defesa
`GET /api/external/med/:id` é apenas consulta. Para enviar defesa pela API, use `POST /api/external/med/:id/defense` com permissão `payment:write` e JSON assinado por HMAC. Upload binário de anexos permanece disponível nos portais Monetarie; anexos e evidências ficam armazenados para análise e auditoria.
:::

::: warning Valor em subcentavos, não em BRL
O campo `amount` é em **subcentavos** (1 BRL = 10.000 subcentavos). Valor `50000` = R$ 5,00 - **não** R$ 50.000. Nunca multiplique por 100 nem use float.
:::

## Resposta de Erro (404)

```json
{
  "worked": false,
  "errors": {
    "not_found": "MED não encontrado"
  }
}
```

::: info Sem ambiguidade entre ausência e indisponibilidade
HTTP `404` significa que o provider respondeu explicitamente que o MED não existe
ou que o recurso não pertence à conta autenticada. Timeouts, erros de rede e
falhas operacionais retornam HTTP `502`.
:::

## 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>"
  }
}
```

::: tip Acompanhamento em tempo real (webhooks)
Os eventos de webhook `pix.refund.requested` e `pix.refund.completed` **SÃO disparados automaticamente** pelo backend a partir de abril/2026. Recomendado assinar esses webhooks para não depender de polling. Polling em `GET /med/:id` ou `GET /med` continua funcionando como alternativa.
:::