# Infracciones PIX y MED

Esta pagina explica como acompanar y responder disputas PIX relacionadas al MED por la API Monetarie.

::: tip Resumen
Una infraccion PIX es una disputa abierta por la institucion del pagador. Cuando requiere analisis, recibes webhooks, puedes consultar el MED y puedes enviar una defensa con contexto y evidencias dentro del plazo informado.
:::

---

## 1. Conceptos Principales

| Concepto | Descripcion |
|---|---|
| Infraccion PIX | Disputa formal relacionada a un PIX recibido |
| MED | Flujo regulatorio usado para analisis y eventual devolucion |
| Bloqueo cautelar | Reserva temporal del valor disputado mientras el caso es analizado |
| Defensa | Justificativa enviada por el cliente, con evidencias cuando existan |
| Decision | Resultado final del caso, con devolucion o liberacion del valor |

El MED es parte del ciclo regulatorio de disputas. Puede impactar el saldo disponible mientras el caso esta en analisis.

---

## 2. Como Acompanhar

Usa webhooks para recibir actualizaciones en tiempo real:

| Evento | Cuando usar |
|---|---|
| `pix.infraction.created` | Una disputa fue registrada y requiere seguimiento |
| `pix.refund.requested` | Un valor entro en disputa MED |
| `pix.infraction.defense_submitted` | Una defensa fue registrada |
| `pix.infraction.resolved` | La disputa fue finalizada |
| `pix.refund.completed` | La devolucion fue ejecutada |
| `pix.payout.returned` | El lanzamiento de devolucion fue confirmado |

Consulta ejemplos en [Payloads de Webhook](/es/webhooks-payloads).

---

## 3. Consulta via API

```http
GET /api/external/med
GET /api/external/med/{id}
```

Permiso requerido: `payment:read`.

Usa el `id` retornado por webhooks o por la lista para consultar el caso y correlacionarlo con el `original_end_to_end_id` del PIX disputado.

---

## 4. Enviar Defensa via API

```http
POST /api/external/med/{id}/defense
Content-Type: application/json
Authorization: ApiKey {client_id}:{client_secret}
hmac: {firma_hmac_sha512}
```

Permiso requerido: `payment:write`.

El body debe ser JSON y firmado con el mismo patron HMAC usado en los demas endpoints `POST` de la API externa.

```json
{
  "defense_text": "Cliente confirmo la operacion y envio evidencia del atendimento.",
  "evidence": [
    {
      "type": "whatsapp",
      "url": "https://su-dominio.example/evidencias/med-123.png",
      "description": "Captura de conversacion con confirmacion del titular",
      "source": "whatsapp",
      "filename": "conversacion-med-123.png",
      "received_at": "2026-06-02T13:30:00Z"
    }
  ]
}
```

| Campo | Tipo | Obligatorio | Descripcion |
|---|---|---:|---|
| `defense_text` | string | Si | Texto de la defensa y contexto de la disputa |
| `evidence` | array | No | Lista de evidencias referenciadas por URL o descripcion |
| `evidence[].type` | string | No | `url`, `document`, `image`, `screenshot`, `email`, `whatsapp` u `other` |
| `evidence[].url` | string | Condicional | URL `https` o `http` de evidencia hospedada por el cliente |
| `evidence[].description` | string | Condicional | Resumen de la evidencia cuando no haya URL |

Cada item de `evidence` debe contener al menos `url` o `description`. La API acepta hasta 10 evidencias por envio.

::: info Evidencias
La API externa registra texto y referencias de evidencia. Upload binario de anexos esta disponible en los portales Monetarie, donde los archivos son validados y almacenados para analisis y auditoria.
:::

---

## 5. Portales y Evidencias Externas

Las defensas tambien pueden ser tratadas en los portales Monetarie. Ese camino permite anexar archivos directamente, como PDFs, imagenes, capturas, contratos e historiales de atencion.

Cuando evidencias llegan por e-mail, WhatsApp, soporte u otro canal fuera de la API, la operacion Monetarie puede registrarlas en el caso. Las evidencias quedan archivadas para consulta, revision futura y auditoria.

---

## 6. Plazos

El plazo de respuesta viene en `defense_deadline` en los webhooks relacionados a la infraccion. Responde antes de ese plazo para que la defensa pueda ser analizada y enviada correctamente.

Recomendaciones:

- Monitorea `pix.infraction.created` y `pix.refund.requested`.
- Consulta el MED por el `id` recibido.
- Envia la defensa por API o portal tan pronto tengas la informacion del cliente.
- Guarda `e2e_id`, `med_id` y horario de envio.

---

## 7. Reconciliacion

Usa `e2e_id` como llave de correlacion entre el PIX original, webhooks de infraccion, registro MED y eventual devolucion.

| `analysis_result` | Interpretacion |
|---|---|
| `AGREED` | Disputa aceptada y devolucion ejecutada |
| `DISAGREED` | Defensa aceptada o disputa rechazada, sin devolucion |
| `null` | Caso cancelado o sin decision aplicable |