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, vinculas una fuente de conciliación a ella y generas un token de webhook vinculado a la conexión. Los webhooks del agregador luego disparan 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. 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 de la cuenta en el proveedor (itemId de Pluggy, id de link de Belvo) que se pasa a la obtención por webhook. Es opcional. Omítela para conectar la cuenta mediante consentimiento alojado.
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": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "awaitingConsent": false
}

Vincular una fuente de conciliación

Matcher ingiere los datos obtenidos en la fuente de conciliación que nombra la conexión. En exactamente una fuente, define config.connection_config_name con el configName de la conexión:

{
  "name": "Pluggy Main Account",
  "type": "BANK",
  "side": "RIGHT",
  "config": {
    "connection_config_name": "pluggy-main"
  }
}

Referencia de API: Crear una fuente

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"

Cada fila del listado lleva id, vendor, configName, baseUrl, accountRef, testable y awaitingConsent.

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. Los otros campos también son opcionales: un campo que omites mantiene su valor almacenado.

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

Una conexión creada sin accountRef espera el consentimiento: muestra "awaitingConsent": true. POST /v1/discovery/aggregator-connections/{id}/connect-token devuelve un token para el widget de consentimiento del proveedor. Envía el id de item o de link que devuelve el widget como accountRef en la llamada de actualización de arriba. Discovery describe el flujo completo.

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, con su credencial ya sellada, identificada por configName. Matcher lee el proveedor de la conexión almacenada. Esta llamada no toma ninguna credencial ni devuelve ninguna.

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 devuelve 404. Matcher no puede probar conexiones de Belvo, así que una conexión de Belvo devuelve 422 (MTCH-0210). Una conexión que espera el consentimiento devuelve 422 (MTCH-0211).

Tipos de conector

Lista los tipos de conector que el registro del motor tiene 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", "requiredFields": ["apiKey"] }
  ]
}

Cada entrada rest lista en requiredFields los campos de credencial que una conexión REST de ese tipo exige. 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. Matcher verifica cada entrega del proveedor mediante una firma HMAC-SHA256 del cuerpo sin procesar en X-Webhook-Signature o mediante la IP de origen. Una entrega que no supera la verificación recibe 401.

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 de webhook generado o token de consentimiento generado
`204`	Conexión eliminada de forma lógica
`400`	Par de credenciales parcial, credencial mal formada o cursor de paginación inválido
`401`	No se pudo resolver el tenant
`404`	Conexión no encontrada (o no es de agregador)
`422`	La solicitud no pasa la validación, por ejemplo un campo ausente o un proveedor distinto de `pluggy` o `belvo`
`422` (`MTCH-0210`)	Matcher no puede probar este proveedor (Belvo)
`422` (`MTCH-0211`)	La conexión espera el consentimiento, así que no se ejecutó ninguna prueba
`422` (`MTCH-0212`)	El proveedor no emitió un token de consentimiento
`422` (`MTCH-0213`)	Matcher no tiene un flujo de consentimiento para este proveedor
`409`	Ya existe una conexión con ese nombre de configuración

Resumen

Guías

Console

Operaciones

Conexiones con agregadores

Crear una conexión

Vincular una fuente de conciliación

Listar, obtener, actualizar, eliminar

Actualizar

Eliminar

Probar una conexión

Tipos de conector

Generar un token de webhook

Códigos de respuesta

​Crear una conexión

​Vincular una fuente de conciliación

​Listar, obtener, actualizar, eliminar

​Actualizar

​Vincular una cuenta mediante consentimiento alojado

​Eliminar

​Probar una conexión

​Tipos de conector

​Generar un token de webhook

​Códigos de respuesta

Crear una conexión

Vincular una fuente de conciliación

Listar, obtener, actualizar, eliminar

Actualizar

Vincular una cuenta mediante consentimiento alojado

Eliminar

Probar una conexión

Tipos de conector

Generar un token de webhook

Códigos de respuesta