Detalles MED

Consulta los detalles completos de un proceso MED (Mecanismo Especial de Devolucion) especifico.

Endpoint

GET /api/external/med/:id

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)

Path Parameters

Parametro	Tipo	Obligatorio	Descripcion
id	String	Si	Identificador del proceso MED

Ejemplo

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

Respuesta de Exito (200)

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

Status en UPPERCASE

Valores posibles: ACKNOWLEDGED, CLOSED, CANCELLED. Repasados tal como recibidos del provider PIX (OnZ/BACEN) — sin normalizacion. Ver med-list para detalles.

Campo	Tipo	Descripcion
worked	Boolean	true indica exito en la operacion
med.id	String	Identificador unico del MED
med.type	String	Tipo: REFUND_REQUEST o REFUND_CANCELLED
med.status	String	Status actual del proceso (ACKNOWLEDGED, CLOSED, CANCELLED)
med.amount	Integer	Valor en unidades base (÷ 10.000 para reales). 50000 = R$ 5,00
med.original_end_to_end_id	String	E2E de la transaccion PIX original. Use para cruzar con GET /transactions/ref/:external_id
med.reason	String	Motivo informado por el solicitante (texto libre). null si no disponible
med.created_at	String	Fecha de apertura (ISO 8601 UTC)

Campos adicionales no expuestos via External API

El proveedor OnZ/BACEN retorna mas campos que los expuestos por este endpoint. Los campos filtrados deliberadamente en el serializer incluyen:

Campo (OnZ)	Descripcion	Donde obtener hoy
analysisResult	Decision final: AGREED o DISAGREED	Webhook pix.infraction.resolved
analysisDetails	Justificativa de la decision	Webhook pix.infraction.resolved
infractionType	REFUND_REQUEST o REFUND_CANCELLED	Ya expuesto en med.type
fraudType	SCAM, ACCOUNT_TAKEOVER, COERCION, FRAUDULENT_ACCESS, OTHER	Webhook pix.refund.requested (campo fraud_category)
situationType	Tipo de situacion involucrada (BACEN taxonomy)	Merchant portal (/compliance) — no disponible via External API
defenseDeadline	Plazo BACEN para envio de defensa	Webhook pix.infraction.created

Esta omision es deliberada (gap conocido). Si usted necesita consumir esos campos programaticamente, contacte compliance@owem.com.br — o use los webhooks listados, que siempre traen los campos relevantes en el momento del evento.

Ver Infracciones (flujo completo) para entender la relacion entre MED e Infracciones.

Valor en subcentavos, no en BRL

El campo amount es en subcentavos (1 BRL = 10.000 subcentavos). Valor 50000 = R$ 5,00 — no R$ 50.000. Nunca multiplique por 100 ni use float.

Respuesta de Error (404)

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

404 puede indicar error transitorio

Si el MED existe en otro canal (webhook, listado anterior) pero retorna 404 en esta consulta, puede ser falla transitoria del proveedor OnZ. Intente nuevamente en algunos segundos. Si persiste despues de 5 min, contacte al soporte.

El backend convierte todos los errores del proveedor (incluyendo timeouts y errores de red) en HTTP 404 con detail: "MED nao encontrado". Para distinguir "no existe" de "falla transitoria", consulte primero el endpoint Listar MED — si el ID aparece en el listado pero el detail retorna 404, es transitorio.

Respuesta de Error (401)

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

Acompanamiento en tiempo real (webhooks)

Los eventos de webhook pix.refund.requested y pix.refund.completed SON disparados automaticamente por el backend a partir de abril/2026. Recomendado suscribir esos webhooks para no depender de polling. Polling en GET /med/:id o GET /med continua funcionando como alternativa.