Saltar al contenido principal
Las conexiones de agregadores permiten que Matcher extraiga datos de transacciones de agregadores de datos de Open Finance (Pluggy, Belvo). Creas una conexión con una credencial sellada, generas un token de webhook vinculado a ella y, a partir de ese momento, los webhooks del agregador impulsan las extracciones entrantes. Esta guía cubre todo el ciclo de vida.
Las credenciales (clientId/secret) son solo de entrada: se sellan antes de persistirlas y nunca se devuelven en una respuesta, un log ni un error. Toda respuesta en esta superficie está libre de secretos por diseño. El tenant siempre se resuelve desde el JWT, nunca desde el 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 de conexión única (con alcance de tenant); un duplicado devuelve un 409. El endpoint de generación de 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 de cuenta del proveedor (Pluggy itemId, id de link de Belvo) que se pasa a la extracción del webhook.
  • clientId / secret — credencial de la API del agregador; se sella y nunca se emite.
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": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

​
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 vendor es inmutable. La credencial es opcional: proporciona ambos, clientId y secret, para rotar la credencial sellada, u omite ambos para dejar intacto el secreto almacenado. Proporcionar exactamente uno devuelve 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), liberando su nombre de configuración para reutilizarlo. Un id de conexión que no sea 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 usando su credencial ya sellada, direccionada por (vendor, configName). No se proporciona ni se devuelve ninguna credencial. 
curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/test" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "vendor": "pluggy", "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 inexistente devuelve un 404.

​
Tipos de conector

Lista los tipos de conector que el registro del motor ha registrado realmente 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 al arranque. Impulsa 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": "postgres", "category": "database" },
    { "type": "rest-generic", "category": "rest" }
  ]
}
Los tipos de proveedor de agregador (Pluggy/Belvo) se excluyen aquí: se provisionan a través de la superficie de conexiones de agregadores anterior.

​
Generar un token de webhook

Genera un token de webhook vinculado a una conexión de agregador existente. El token en bruto y su URL de webhook orientada al proveedor se devuelven una sola vez; solo se almacena 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>",
  "webhookUrl": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/<raw-token>",
  "vendor": "pluggy"
}
Configura la webhookUrl devuelta en el panel del agregador. Una conexión de destino inexistente devuelve un 404.

​
Códigos de respuesta

EstadoSignificado
200Get, list, test o connector-types devuelto
201Conexión creada / token generado
204Conexión eliminada de forma lógica
400Vendor inválido, par de credenciales parcial o paginación inválida
401No se pudo resolver el tenant
404Conexión no encontrada (o no es un agregador)
409Ya existe una conexión con ese nombre de configuración