# Infrações PIX e MED

Esta página descreve como acompanhar e responder contestações PIX relacionadas ao MED (Mecanismo Especial de Devolução) pela API Monetarie.

::: tip Resumo
Uma infração PIX é uma contestação aberta pela instituição do pagador. Quando ela exige análise, você recebe webhooks, pode consultar o MED e pode enviar uma defesa com justificativa e evidências dentro do prazo informado.
:::

---

## 1. Conceitos principais

| Conceito | Descrição |
|---|---|
| Infração PIX | Contestação formal relacionada a um PIX recebido |
| MED | Fluxo regulatório usado para análise e eventual devolução de valores |
| Bloqueio cautelar | Reserva temporária do valor em disputa enquanto o caso é analisado |
| Defesa | Justificativa enviada pelo cliente, acompanhada de evidências quando houver |
| Decisão | Resultado final do caso, com devolução ou liberação do valor |

O MED é uma camada regulatória do ciclo de contestação. Ele pode impactar o saldo disponível enquanto o caso está em análise.

---

## 2. Como acompanhar

Use webhooks para receber atualizações em tempo real:

| Evento | Quando usar |
|---|---|
| `pix.infraction.created` | Uma contestação foi registrada e requer acompanhamento |
| `pix.refund.requested` | Um valor entrou em disputa no fluxo MED |
| `pix.infraction.defense_submitted` | Uma defesa foi registrada |
| `pix.infraction.resolved` | A contestação foi finalizada |
| `pix.refund.completed` | A devolução foi executada |
| `pix.payout.returned` | O lançamento de devolução foi confirmado |

Veja os payloads em [Payloads de Webhook](/webhooks-payloads).

---

## 3. Consulta via API

### Listar MEDs

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

Permissão exigida: `payment:read`.

### Consultar um MED

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

Permissão exigida: `payment:read`.

Use o `id` retornado nos webhooks ou na listagem para consultar o caso e correlacionar com o `original_end_to_end_id` do PIX contestado.

---

## 4. Enviar defesa pela API

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

Permissão exigida: `payment:write`.

Este endpoint registra a defesa do MED para análise. O corpo deve ser JSON e assinado pelo mesmo padrão HMAC usado nos demais endpoints `POST` da API externa.

### Body

```json
{
  "defense_text": "Cliente confirmou a operação e enviou comprovante do atendimento.",
  "evidence": [
    {
      "type": "whatsapp",
      "url": "https://seu-dominio.example/evidencias/med-123.png",
      "description": "Print da conversa com confirmação do titular",
      "source": "whatsapp",
      "filename": "conversa-med-123.png",
      "received_at": "2026-06-02T13:30:00Z"
    }
  ]
}
```

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---:|---|
| `defense_text` | string | Sim | Texto da defesa e contexto da contestação |
| `evidence` | array | Não | Lista de evidências referenciadas por URL ou descrição |
| `evidence[].type` | string | Não | `url`, `document`, `image`, `screenshot`, `email`, `whatsapp` ou `other` |
| `evidence[].url` | string | Condicional | URL `https` ou `http` para evidência hospedada pelo cliente |
| `evidence[].description` | string | Condicional | Resumo da evidência quando não houver URL |
| `evidence[].source` | string | Não | Origem da evidência, como `email`, `whatsapp`, `support` ou `external_api` |
| `evidence[].filename` | string | Não | Nome de referência do arquivo |
| `evidence[].received_at` | string | Não | Data/hora em que a evidência foi recebida |

Cada item de `evidence` deve conter ao menos `url` ou `description`. A API aceita até 10 evidências por submissão.

::: info Evidências
A API externa registra texto e referências de evidência. Upload binário de anexos é feito pelos portais Monetarie, onde os arquivos são validados e armazenados para análise e auditoria.
:::

### Resposta

```json
{
  "worked": true,
  "status": "defense_submitted",
  "med_id": "3f1e2c41-c269-4fa8-a151-49e739f8d37d",
  "block_id": "3f1e2c41-c269-4fa8-a151-49e739f8d37d",
  "evidence_count": 1,
  "defense_submitted_at": "2026-06-02T16:30:12Z"
}
```

### Erros comuns

| Status | Motivo |
|---:|---|
| `400` | `defense_text` ausente, JSON inválido, evidência inválida ou URL fora do padrão aceito |
| `401` | API Key ou HMAC ausente/inválido |
| `403` | IP fora da whitelist ou API Key sem `payment:write` |
| `404` | MED não encontrado para a conta da API Key |
| `409` | MED não está mais em estado que permite defesa |

---

## 5. Portais e evidências externas

As mesmas defesas também podem ser tratadas nos portais Monetarie. Esse caminho permite anexar arquivos diretamente, como PDFs, imagens, prints, contratos e históricos de atendimento.

Quando evidências chegam por e-mail, WhatsApp, atendimento ou outro canal fora da API, elas podem ser registradas no caso pela operação Monetarie. As evidências ficam arquivadas para consulta, conferência futura e auditoria.

::: info Envio ao fluxo regulatório
O texto da defesa e o parecer final são usados na resposta do caso. Arquivos anexados e demais evidências permanecem armazenados na Monetarie para análise e histórico.
:::

---

## 6. Prazos

O prazo de resposta vem no campo `defense_deadline` dos webhooks relacionados à infração. Responda antes desse prazo para que a defesa possa ser analisada e encaminhada corretamente.

Recomendações:

- Monitore `pix.infraction.created` e `pix.refund.requested`.
- Consulte o MED pelo `id` recebido.
- Envie a defesa pela API ou pelo portal assim que tiver os dados do cliente.
- Guarde no seu sistema o `e2e_id`, o `med_id` e o horário da submissão.

---

## 7. Reconciliação

Use o `e2e_id` como chave de correlação entre:

- PIX original recebido.
- Webhooks de infração.
- Registro MED consultado pela API.
- Eventual devolução confirmada por `pix.refund.completed` ou `pix.payout.returned`.

Quando `pix.infraction.resolved` chegar, use `analysis_result` para atualizar o status interno do caso.

| `analysis_result` | Interpretação |
|---|---|
| `AGREED` | Contestação aceita e devolução executada |
| `DISAGREED` | Defesa aceita ou contestação rejeitada, sem devolução |
| `null` | Caso cancelado ou sem decisão aplicável |