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

<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 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:

```json theme={null}
{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "baseUrl": "https://api.pluggy.ai",
  "accountRef": "",
  "awaitingConsent": true
}
```

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

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

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

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

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

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