> ## 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 de agregadores

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

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.

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

```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 **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`.

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

```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 inexistente devuelve un `404`.</Note>

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

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

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

```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>",
  "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

***

| Estado | Significado                                                        |
| ------ | ------------------------------------------------------------------ |
| `200`  | Get, list, test o connector-types devuelto                         |
| `201`  | Conexión creada / token generado                                   |
| `204`  | Conexión eliminada de forma lógica                                 |
| `400`  | Vendor 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 un agregador)                      |
| `409`  | Ya existe una conexión con ese nombre de configuración             |