> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # MED 2.0 — Recuperación de fondos > Ejecuta la recuperación de fondos de MED 2.0 de BACEN con el Plugin Pix Indirecto vía BTG: grafos de rastreo, análisis de informes de infracción, devoluciones y eventos de webhook. MED 2.0 (Mecanismo Especial de Devolução) es el mecanismo mejorado de BACEN para recuperar fondos en casos de fraude, estafas y errores operativos. MED 1.0 maneja disputas de una sola transacción mediante informes de infracción. **MED 2.0 introduce un flujo de recuperación de fondos** que rastrea cómo se movieron los fondos fraudulentos entre varias cuentas. El flujo coordina el bloqueo, el análisis y las devoluciones entre las instituciones participantes. El Plugin Pix Indirecto (BTG) expone el ciclo de vida completo de la recuperación de fondos como endpoints REST. También envía eventos por webhook, para que tu sistema se mantenga sincronizado con cada cambio de estado. MED 2.0 es un requisito de BACEN para los participantes de Pix. El plugin implementa el flujo de recuperación de fondos, para que puedas cumplir este requisito a través de tu conexión indirecta con BTG. # Conceptos *** | Término | Definición | | --------------------------- | --------------------------------------------------------------------------------------------------------- | | **Recuperación de fondos** | El proceso de MED 2.0 que recupera fondos entre varias cuentas después de un fraude denunciado | | **Grafo de rastreo** | Una representación de cómo fluyeron los fondos entre cuentas, personas y transacciones | | **Transacción raíz** | La transacción Pix fraudulenta original que inicia la recuperación | | **Informe de infracción** | Un informe de una transacción fraudulenta/problemática, ahora vinculado a su recuperación de fondos padre | | **Solicitud de devolución** | Una solicitud para devolver los fondos bloqueados a la víctima | # Ciclo de vida y estado *** Una recuperación de fondos pasa por los siguientes estados: Recuperación de fondos | Estado | Descripción | | ------------------- | --------------------------------------------------------------------------------- | | `CREATED` | Estado inicial después de la creación | | `TRACKED` | Grafo de rastreo generado | | `AWAITING_ANALYSIS` | Flujo de bloqueo iniciado, a la espera del análisis de los informes de infracción | | `ANALYSED` | Todos los informes de infracción analizados, listo para la devolución | | `REFUNDING` | Solicitudes de devolución iniciadas | | `COMPLETED` | Todas las devoluciones completadas | | `CANCELLED` | Recuperación cancelada (solo se permite antes de que empiece la devolución) | # Endpoints *** Todos los endpoints de recuperación de fondos viven bajo el dominio DICT y requieren el header `X-Account-Id`. | Método | Endpoint | Descripción | | ------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------- | | `POST` | [`/v1/dict/funds-recoveries`](/es/reference/interfaces/pix-btg/create-a-funds-recovery-request) | Crear una recuperación de fondos | | `GET` | [`/v1/dict/funds-recoveries/{id}`](/es/reference/interfaces/pix-btg/retrieve-funds-recovery-details) | Consultar una recuperación de fondos | | `PATCH` | [`/v1/dict/funds-recoveries/{id}`](/es/reference/interfaces/pix-btg/update-a-funds-recovery-request) | Actualizar el tipo de situación y los datos de contacto | | `POST` | [`/v1/dict/funds-recoveries/{id}/cancel`](/es/reference/interfaces/pix-btg/cancel-a-funds-recovery-request) | Cancelar (antes de que empiece la devolución) | | `GET` | [`/v1/dict/funds-recoveries/{id}/tracking-graph`](/es/reference/interfaces/pix-btg/retrieve-funds-recovery-tracking-graph) | Ver el grafo de rastreo | | `GET` | [`/v1/dict/funds-recoveries/{id}/infraction-reports`](/es/reference/interfaces/pix-btg/list-funds-recovery-infraction-reports) | Listar los informes de infracción vinculados | | `POST` | [`/v1/dict/funds-recoveries/{id}/refund`](/es/reference/interfaces/pix-btg/request-funds-recovery-refund) | Solicitar devoluciones (el estado debe ser `ANALYSED`) | | `GET` | [`/v1/dict/funds-recoveries/{id}/refunds`](/es/reference/interfaces/pix-btg/list-funds-recovery-refunds) | Listar las solicitudes de devolución | ## Crear una recuperación de fondos *** ```json theme={null} POST /v1/dict/funds-recoveries { "rootTransactionId": "E9999901012341234123412345678900", "situationType": "SCAM", "contactInformation": { "email": "fraud-ops@example.com", "phone": "+5511999999999" }, "reportDetails": "Customer reported unauthorized Pix transfer", "trackingGraphParameters": { "minTransactionAmount": "10.00", "maxTransactions": 100, "hopWindow": "PT24H", "maxHops": 5 } } ``` ### Reglas de validación | Campo | Requisito | | ---------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | `rootTransactionId` | Obligatorio, 32 caracteres alfanuméricos | | `situationType` | Obligatorio — uno de `SCAM`, `ACCOUNT_TAKEOVER`, `COERCION`, `FRAUDULENT_ACCESS`, `OTHER`, `UNKNOWN` | | `contactInformation` | Obligatorio — objeto con `email` o `phone`, o ambos | | `trackingGraphParameters.minTransactionAmount` | Opcional, decimal positivo | | `trackingGraphParameters.maxTransactions` | Opcional, 1–1000 | | `trackingGraphParameters.hopWindow` | Opcional, duración ISO 8601 (por ejemplo, `PT24H`) | | `trackingGraphParameters.maxHops` | Opcional, 1–10 | Una llamada exitosa devuelve **HTTP 201**. La respuesta contiene la nueva recuperación de fondos y los datos de su grafo de rastreo. El plugin persiste el registro localmente con el estado `CREATED`. ## Grafo de rastreo *** El plugin obtiene el grafo de rastreo actualizado desde BTG en cada llamada. El grafo no tiene estado local. Lista las personas, las cuentas y las transacciones del flujo de fraude, con el monto reembolsable de cada transacción. ``` GET /v1/dict/funds-recoveries/{id}/tracking-graph ``` La respuesta incluye: * `parameters`: los parámetros de generación del grafo * `persons[]`: las personas físicas y jurídicas involucradas * `accounts[]`: las cuentas del flujo con los ISPB de sus participantes * `transactions[]`: las transacciones Pix con sus montos y montos reembolsables ## Solicitar devoluciones *** Una vez que la recuperación llega a `ANALYSED`, solicita la devolución de los fondos bloqueados: ``` POST /v1/dict/funds-recoveries/{id}/refund ``` El plugin llama a BTG, hace la transición de la recuperación a `REFUNDING` y devuelve **HTTP 200**. Sigue el estado de cada devolución con [Listar devoluciones](/es/reference/interfaces/pix-btg/list-funds-recovery-refunds). # Header X-Purpose (transferencias MED 2.0) *** Las transferencias de devolución de MED 2.0 deben llevar un propósito de transacción. El endpoint de cashout acepta un header `X-Purpose` opcional que el plugin mapea al `transactionType` de BTG. ``` POST /v1/transfers/cashout/process X-Purpose: INSTANT_PAYMENT_REFUND ``` | Valor | Descripción | `transactionType` de BTG | | ------------------------ | --------------------------------------------------------------------- | ------------------------ | | `TRANSFER` | Transferencia Pix estándar (predeterminado cuando se omite el header) | `TRANSFER` | | `INSTANT_PAYMENT_REFUND` | Transferencia de devolución de MED 2.0 | `INSTANT_PAYMENT_REFUND` | Actualmente solo se admiten `TRANSFER` e `INSTANT_PAYMENT_REFUND`. Los valores `CHANGE`, `WITHDRAWAL`, `REFUND_AUTOMATIC_PIX` e `INSTALLMENT_PIX` devuelven **HTTP 400** con el error `PIX-0429` (Unsupported Purpose). Las respuestas de transferencia también incluyen el valor `purpose` ([Consultar una transferencia Pix](/es/reference/interfaces/pix-btg/retrieve-a-pix-transfer) y los endpoints de listado). Los registros existentes tienen `TRANSFER` como valor predeterminado. # Campos de correlación *** Dos entidades existentes ahora llevan un campo `fundsRecoveryId` que vincula una disputa con su recuperación padre: * **Informes de infracción**: [Consultar un informe de infracción](/es/reference/interfaces/pix-btg/retrieve-an-infraction-report) y [el endpoint de listado](/es/reference/interfaces/pix-btg/list-infraction-reports) * **Solicitudes de devolución**: [Consultar una solicitud de devolución](/es/reference/interfaces/pix-btg/retrieve-a-refund-request) y [el endpoint de listado](/es/reference/interfaces/pix-btg/list-refund-requests) Los registros creados fuera del flujo de MED 2.0 no llevan este campo. # Webhooks *** Dos webhooks entrantes de BTG impulsan el flujo de recuperación de fondos. Cada uno produce un evento saliente correspondiente hacia tu sistema: | `entityType` saliente | Disparador | Comportamiento | | ----------------------- | -------------------------------------- | ------------------------------------------------------------------------------------------- | | `FUNDS_RECOVERY` | Webhook `FUNDS_RECOVERY` de BTG | El plugin actualiza el registro local y luego notifica a tu sistema con la entidad completa | | `FUNDS_RECOVERY_EVENTS` | Webhook `FUNDS_RECOVERY_EVENTS` de BTG | Evento de ciclo de vida de paso — sin actualización en la base de datos | Ambos usan `flowType: DICT`. Consulta la [guía de Webhooks](/es/interfaces/pix-btg/indirect-pix-webhooks) para el formato del envelope, los reintentos y el enrutamiento. **Evento de entidad de recuperación de fondos:** ```json theme={null} { "entityType": "FUNDS_RECOVERY", "flowType": "DICT", "payload": { "id": "91d65e98-97c0-4b0f-b577-73625da1f9fc", "externalId": "ca1b9c01-ff9e-4a58-90ab-d31512e15ce0", "accountId": "01989f9e-6508-79f8-9540-835be49fbd0d", "status": "CREATED", "rootTransactionId": "E9999901012341234123412345678900", "situationType": "SCAM", "reporterParticipant": "99999010", "contactInformation": {}, "reportDetails": "Details to help receiving participants", "createdAt": "2020-01-17T10:00:00.000Z", "updatedAt": "2020-01-17T10:00:00.000Z" } } ``` **Evento de ciclo de vida (de paso):** ```json theme={null} { "entityType": "FUNDS_RECOVERY_EVENTS", "flowType": "DICT", "payload": { "id": "10001", "event": "FUNDS_RECOVERY_COMPLETED", "entityType": "FUNDS_RECOVERY", "entityId": "527179ce-b991-4add-a70f-e0fdbb98e6da", "timestamp": "2025-01-11T10:00:00.000Z" } } ``` Valores de `event` del ciclo de vida: `FUNDS_RECOVERY_ANALYSED`, `FUNDS_RECOVERY_COMPLETED`, `FUNDS_RECOVERY_INFORMATION_UPDATED`, `FUNDS_RECOVERY_CANCELLED`. # Aviso de deprecación *** No uses [Crear un informe de infracción](/es/reference/interfaces/pix-btg/create-an-infraction-report) para integraciones nuevas. MED 2.0 deprecia este endpoint y crea los informes de infracción automáticamente mediante el flujo de recuperación de fondos. El endpoint sigue funcionando por compatibilidad con versiones anteriores. Las integraciones nuevas deben usar las APIs de recuperación de fondos. # Próximos pasos *** * [Operaciones de devolución](/es/interfaces/pix-btg/indirect-pix-refund-operations): Devoluciones parciales distribuidas y desbloqueo de devoluciones atascadas * [Webhooks](/es/interfaces/pix-btg/indirect-pix-webhooks): Envelope del evento, reintentos y enrutamiento * [Dominios principales: MED](/es/interfaces/pix/main-domains-med): Conceptos de disputas y devoluciones de MED * [Referencia de API](/es/reference/interfaces/pix-btg/create-entry): Documentación completa de la API