# Listar MED

Lista los procesos MED (Mecanismo Especial de Devolucion) asociados a la cuenta.

El MED es un mecanismo del Banco Central para recuperacion de valores en casos de fraude o falla operacional en el sistema PIX.

## Endpoint

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

## Headers

| Header | Tipo | Obligatorio | Descripcion |
|--------|------|-------------|-------------|
| `Authorization` | String | Si | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | No | Defina como `camelCase` para recibir los campos de la respuesta en camelCase (default es snake_case) |

::: info Permisos
Este endpoint requiere el permiso `payment:read` en la API Key. Claves sin ese permiso reciben HTTP 403.
:::

## Ejemplo

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

::: warning Sin paginacion nativa
Este endpoint consulta al provider PIX/BACEN en tiempo real y **no acepta parametros de paginacion** (`page`/`per_page`/`limit`). Todos los MEDs vinculados a la entidad son retornados en una unica respuesta. Para grandes volumenes, filtre localmente en su sistema despues de recibir el array.
:::

## Respuesta de Exito (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 | Descripcion |
|-------|------|-------------|
| `worked` | Boolean | `true` indica exito en la operacion |
| `meds` | Array | Lista de procesos MED |
| `meds[].id` | String | Identificador unico del MED |
| `meds[].type` | String | Tipo del MED (vea tabla abajo) |
| `meds[].status` | String | Status actual del proceso |
| `meds[].amount` | Integer | Valor en **unidades base** (÷ 10.000 para reales). `50000` = R$ 5,00 |
| `meds[].original_end_to_end_id` | String | E2E de la transaccion PIX original |
| `meds[].created_at` | String | Fecha de apertura (ISO 8601) |

## Tipos de MED

| Tipo | Descripcion |
|------|-------------|
| `REFUND_REQUEST` | Solicitud de devolucion (fraude, estafa o acuerdo) |
| `REFUND_CANCELLED` | Cancelacion de solicitud de devolucion anterior |

## Status del MED

Valores retornados por el provider PIX (PIX/BACEN) en **UPPERCASE**. La API repasa el valor tal como recibido - no hay normalizacion.

| Status | Descripcion | Decision final |
|--------|-------------|----------------|
| `ACKNOWLEDGED` | MED recibido y reconocido por el participante, en analisis | No - aguarda defensa o plazo |
| `CLOSED` | MED finalizado por el participante | Si - vea `analysisResult` en [med-detail](/es/med-detail) para distinguir `AGREED` (devolucion ejecutada) de `DISAGREED` (defensa aceptada, sin devolucion) |
| `CANCELLED` | MED cancelado por el solicitante antes del analisis | Si - ningun valor fue bloqueado ni devuelto |

::: warning El status es uppercase
Los status del MED siempre son retornados en **MAYUSCULAS**. Si su filtro espera minusculas (`pending`/`accepted`/`closed`), el no va a encontrar ninguna fila. Esta es una diferencia consciente en relacion a los status de transaccion PIX (lowercase) - MED sigue la convencion BACEN original.
:::

::: tip Correlacion con transaccion original
Use el campo `original_end_to_end_id` para localizar la transaccion PIX original que motivo el MED. Consulte via `GET /api/external/transactions/:id` o `GET /api/external/transactions/ref/:external_id` si usted almaceno el `external_id`.
:::

::: info Retorno en ambientes dev/homologacion
Este endpoint consulta al provider PIX directamente - **no lee de tabla local**. En dev/homologacion puede retornar array vacio si el proveedor PIX no tiene MEDs de prueba para la entidad configurada. En produccion, retorna la lista real de procesos MED de su cuenta conforme repasada por el PIX/BACEN.
:::

::: warning Fallas en el proveedor retornan array vacio
Si hay indisponibilidad temporal del proveedor PIX, el endpoint retorna `{"worked": true, "meds": []}` (silenciosamente, sin 5xx). Si usted recibe array vacio de forma persistente mientras espera MEDs, consulte al soporte para verificar si hay indisponibilidad del proveedor.
:::

## Respuesta de Exito -- Sin MEDs (200)

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

## Respuesta de Error (401)

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

::: warning Valores en disputa
Cuando un MED requiere analisis, el valor disputado puede quedar temporalmente reservado y aparecer en `pending` hasta la decision final.

Cuando el MED es resuelto (`CLOSED`):
- `AnalysisResult=AGREED` indica disputa aceptada y devolucion ejecutada.
- `AnalysisResult=DISAGREED` indica disputa rechazada o defensa aceptada, sin devolucion.

Suscriba los webhooks [`pix.infraction.created`](/es/webhooks-payloads#pix-infraction-created), [`pix.refund.requested`](/es/webhooks-payloads#pix-refund-requested), [`pix.infraction.defense_submitted`](/es/webhooks-payloads#pix-infraction-defense-submitted) y [`pix.infraction.resolved`](/es/webhooks-payloads#pix-infraction-resolved). Para responder un MED por API, use `POST /api/external/med/:id/defense` con `payment:write`. Ver [Infracciones](/es/infractions).
:::