Defesa MED

Use este endpoint quando um MED ou infração PIX exigir resposta do cliente antes do prazo informado no webhook.

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.

O {id} é o identificador do bloqueio/caso MED retornado em GET /api/external/med, GET /api/external/med/{id} ou nos webhooks de infração. A requisição é POST, portanto deve seguir a mesma regra de HMAC-SHA512 dos demais endpoints de escrita.

Body

{
  "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	Evidências ou referências recebidas por API, e-mail, WhatsApp, suporte ou outro canal
evidence[].type	string	Não	url, document, image, screenshot, email, whatsapp ou other
evidence[].url	string	Condicional	URL http ou https para evidência hospedada pelo cliente
evidence[].description	string	Condicional	Descrição 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.

Evidências

A API externa registra o texto da defesa e referências de evidência. Upload binário de anexos fica nos portais Minha Konta, onde os arquivos são armazenados para análise, consulta e auditoria futura.

Resposta

{
  "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"
}

Webhook

Após registrar a defesa, a Minha Konta envia pix.infraction.defense_submitted para os webhooks habilitados.

O encerramento do caso chega depois em pix.infraction.resolved. Use analysis_result para saber o desfecho:

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

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á em estado que permite defesa

Veja também Infrações PIX e MED para o fluxo completo de webhooks, prazos, bloqueio cautelar e reconciliação.