> ## 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.

# Conexiones con agregadores

> Aprovisiona conexiones con agregadores de datos de Open Finance (Pluggy, Belvo), pruébalas, explora los tipos de conector y genera tokens de webhook para las obtenciones entrantes.

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, 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.

<Note>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.</Note>

## Crear una conexión

***

```bash theme={null}
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.
* `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:

```json theme={null}
{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "baseUrl": "https://api.pluggy.ai",
  "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}
```

## Listar, obtener, actualizar, eliminar

***

```bash theme={null}
# 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`.

```bash theme={null}
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

```bash theme={null}
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 `vendor` y `configName`. Esta llamada no toma ninguna credencial ni devuelve ninguna.

```bash theme={null}
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" }'
```

```json theme={null}
{ "vendor": "pluggy", "configName": "pluggy-main", "healthy": true }
```

<Note>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`.</Note>

## 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.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"
```

```json theme={null}
{
  "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.

```bash theme={null}
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"
  }'
```

```json theme={null}
{
  "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 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` |
| `409` | Ya existe una conexión con ese nombre de configuración |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.