Conexiones con agregadores

Las conexiones con agregadores permiten que Matcher traiga datos de transacciones desde agregadores de datos de Open Finance (Pluggy, Belvo). Creas una conexión con una credencial sellada, usas el flujo de consentimiento alojado del proveedor para vincular una cuenta cuando hace falta, generas un token de webhook vinculado a la conexión, y los webhooks del agregador impulsan las obtenciones entrantes. Esta guía cubre el ciclo de vida completo.

Las credenciales (clientId/secret) son solo de entrada: Matcher las sella antes de persistirlas y nunca las devuelve en una respuesta, un log o un error. Cada respuesta de esta superficie está libre de secretos por construcción. El tenant siempre viene del JWT, nunca del cuerpo de la solicitud.

Crear una conexión

curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
    "clientId": "...",
    "secret": "..."
  }'

Valores de los campos:

vendor: pluggy o belvo.
configName: identidad única de la conexión (con alcance de tenant). Un duplicado es un 409. El endpoint que genera tokens de webhook vincula un token a este nombre.
baseUrl: URL base de la API del proveedor, almacenada como el host de la conexión.
accountRef: referencia opaca opcional de la cuenta en el proveedor (itemId de Pluggy, id de link de Belvo) que se pasa a la obtención por webhook. Omítela para crear una conexión a la espera del consentimiento del cliente final. Vincula después con PUT la referencia devuelta por el proveedor.
clientId / secret: credencial de la API del agregador, sellada y nunca emitida.

Una creación exitosa devuelve 201 con el descriptor de conexión libre de secretos:

{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "baseUrl": "https://api.pluggy.ai",
  "accountRef": "",
  "awaitingConsent": true
}

Listar, obtener, actualizar, eliminar

# List (cursor-paginated, secret-free)
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections?limit=20" \
  -H "Authorization: Bearer $TOKEN"

# Get by opaque id
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

Actualizar

Edita una conexión existente por id para que un baseUrl mal escrito no sea permanente. El proveedor es inmutable. La credencial es opcional: entrega ambos, clientId y secret, para rotar la credencial sellada, u omite ambos para dejar intacto el secreto almacenado. Entregar exactamente uno es un 400.

curl -X PUT "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "pluggy-main",
    "baseUrl": "https://api.pluggy.ai",
    "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
  }'

Eliminar

curl -X DELETE "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

La eliminación borra la conexión de forma lógica (204) y libera su nombre de configuración para reutilizarlo. El id de una conexión que no es de agregador devuelve 404 en cualquier operación por id. Esta superficie nunca confirma la existencia de una fila que no sea de agregador.

Probar una conexión

Ejecuta una verificación de conectividad en vivo para una conexión existente y vinculada, con su credencial ya sellada, identificada por configName. El proveedor viene de la conexión almacenada. Esta llamada no toma ninguna credencial ni devuelve ninguna. Una conexión a la espera de consentimiento no se puede probar hasta que se vincule su referencia de cuenta en el proveedor.

curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "configName": "pluggy-main" }'

{ "vendor": "pluggy", "configName": "pluggy-main", "healthy": true }

Un resultado de credenciales que no funcionan es un resultado de prueba esperado, expuesto como "healthy": false con un 200, no un error. Una conexión ausente o un proveedor almacenado sin ruta de prueba de conectividad (hoy Belvo) se expone mediante la respuesta de error estándar. No se ejecuta ninguna prueba. Usa el campo testable de la respuesta de la lista antes de ofrecer la acción.

Conectar una conexión a la espera de consentimiento

Para una conexión creada sin accountRef, genera un token de consentimiento de corta duración y abre el widget de consentimiento del propio proveedor en el navegador del cliente final. La respuesta lleva el token una vez. Matcher nunca lo persiste ni lo registra en logs. Cuando el widget devuelve el id de item o de link del proveedor, vincúlalo con PUT /v1/discovery/aggregator-connections/{id} y un cuerpo con accountRef. No necesitas entregar la credencial de nuevo.

curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}/connect-token" \
  -H "Authorization: Bearer ***"

Para una conexión ya vinculada, el mismo endpoint empieza el reconsentimiento y devuelve reconsent: true con el accountRef vinculado exacto. Usa ese valor devuelto con el widget del proveedor en lugar de una referencia guardada localmente. Un despliegue sin ruta de consentimiento para el proveedor devuelve 422.

Tipos de conector

Lista los tipos de conector que el registro del motor tiene efectivamente registrados para este despliegue, cada uno etiquetado con una categoría derivada del backend (database o rest). La lista refleja el registro en vivo. Solo aparecen los conectores registrados en el arranque. Alimenta el selector de tipo del formulario de conexión.

curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"

{
  "types": [
    { "type": "POSTGRESQL", "category": "database" },
    { "type": "STRIPE", "category": "rest" }
  ]
}

Esta lista excluye los tipos de proveedor de agregador (Pluggy/Belvo). La superficie de conexiones con agregadores de arriba los aprovisiona.

Generar un token de webhook

Genera un token de webhook vinculado a una conexión de agregador existente. La respuesta lleva el token en crudo y su URL de webhook expuesta al proveedor una sola vez. Matcher almacena solo el hash SHA-256 del token.

curl -X POST "https://api.matcher.example.com/v1/discovery/webhooks/tokens" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor": "pluggy",
    "connection_config_name": "pluggy-main"
  }'

{
  "token": "<raw-token-shown-once>",
  "webhook_url": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/<raw-token>",
  "vendor": "pluggy"
}

Configura el webhook_url devuelto en el dashboard del agregador. Una conexión de destino ausente devuelve 404.

Códigos de respuesta

Estado	Significado
`200`	Se devolvió la obtención, la lista, la prueba o los tipos de conector
`201`	Conexión creada / token generado
`204`	Conexión eliminada de forma lógica
`400`	Proveedor inválido, par de credenciales parcial o paginación inválida
`401`	No se pudo resolver el tenant
`404`	Conexión no encontrada (o no es de agregador)
`422`	El proveedor existente no admite prueba de conectividad, o el despliegue no tiene ruta de consentimiento alojado para ese proveedor
`409`	Ya existe una conexión con ese nombre de configuración

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Conexiones con agregadores

Crear una conexión

Listar, obtener, actualizar, eliminar

Actualizar

Eliminar

Probar una conexión

Conectar una conexión a la espera de consentimiento

Tipos de conector

Generar un token de webhook

Códigos de respuesta

​Crear una conexión

​Listar, obtener, actualizar, eliminar

​Actualizar

​Eliminar

​Probar una conexión

​Conectar una conexión a la espera de consentimiento

​Tipos de conector

​Generar un token de webhook

​Códigos de respuesta

Crear una conexión

Listar, obtener, actualizar, eliminar

Actualizar

Eliminar

Probar una conexión

Conectar una conexión a la espera de consentimiento

Tipos de conector

Generar un token de webhook

Códigos de respuesta