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

# Conexões de agregadores

> Provisione conexões de agregadores de dados de Open Finance (Pluggy, Belvo), teste-as, explore os tipos de conector e gere tokens de webhook para extrações de entrada.

As conexões de agregadores permitem que o Matcher extraia dados de transações de agregadores de dados de Open Finance (Pluggy, Belvo). Você cria uma conexão com uma credencial selada, gera um token de webhook vinculado a ela e, a partir daí, os webhooks do agregador impulsionam as extrações de entrada. Este guia cobre todo o ciclo de vida.

<Note>As credenciais (`clientId`/`secret`) são **somente de entrada**: elas são seladas antes da persistência e nunca são retornadas em uma resposta, um log ou um erro. Toda resposta nesta superfície é livre de segredos por construção. O tenant é sempre resolvido a partir do JWT, nunca do corpo da requisição.</Note>

## Criar uma conexão

***

```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 dos campos:

* `vendor` — `pluggy` ou `belvo`.
* `configName` — identidade de conexão única (com escopo de tenant); um duplicado retorna um `409`. **O endpoint de geração de tokens de webhook vincula um token a este nome.**
* `baseUrl` — URL base da API do fornecedor, armazenada como o host da conexão.
* `accountRef` — referência opaca de conta do fornecedor (Pluggy `itemId`, id de link do Belvo) encaminhada para a extração do webhook.
* `clientId` / `secret` — credencial da API do agregador; selada e nunca emitida.

Uma criação bem-sucedida retorna `201` com o descritor de conexão livre de segredos:

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

## Listar, obter, atualizar, excluir

***

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

### Atualizar

Edite uma conexão existente por id para que um `baseUrl` digitado incorretamente não seja permanente. O **vendor é imutável**. A credencial é opcional: forneça **ambos**, `clientId` e `secret`, para rotacionar a credencial selada, ou omita **ambos** para deixar o segredo armazenado intacto. Fornecer exatamente um retorna um `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"
  }'
```

### Excluir

```bash theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"
```

A exclusão remove a conexão de forma lógica (`204`), liberando seu nome de configuração para reutilização. Um id de conexão que não seja de agregador retorna `404` em qualquer operação por id — esta superfície nunca confirma a existência de uma linha que não seja de agregador.

## Testar uma conexão

***

Execute uma verificação de conectividade ao vivo para uma conexão existente usando sua credencial já selada, endereçada por `(vendor, configName)`. Nenhuma credencial é fornecida ou retornada.

```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>Um resultado de credenciais-que-não-funcionam é um resultado de teste **esperado**, exposto como `"healthy": false` com um `200` — não um erro. Uma conexão inexistente retorna um `404`.</Note>

## Tipos de conector

***

Liste os tipos de conector que o registro do motor de fato registrou para este deployment, cada um marcado com uma categoria derivada do backend (`database` ou `rest`). A lista reflete o registro ao vivo — apenas os conectores registrados na inicialização aparecem. Ela impulsiona o seletor de tipo do formulário de conexão.

```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" }
  ]
}
```

Os tipos de fornecedor de agregador (Pluggy/Belvo) são excluídos aqui — eles são provisionados através da superfície de conexões de agregadores acima.

## Gerar um token de webhook

***

Gere um token de webhook vinculado a uma conexão de agregador existente. O token bruto e sua URL de webhook voltada ao provedor são retornados **uma única vez** — apenas o hash SHA-256 do token é armazenado.

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

Configure a `webhookUrl` retornada no painel do agregador. Uma conexão de destino inexistente retorna um `404`.

## Códigos de resposta

***

| Status | Significado                                                       |
| ------ | ----------------------------------------------------------------- |
| `200`  | Get, list, test ou connector-types retornado                      |
| `201`  | Conexão criada / token gerado                                     |
| `204`  | Conexão excluída de forma lógica                                  |
| `400`  | Vendor inválido, par de credenciais parcial ou paginação inválida |
| `401`  | O tenant não pôde ser resolvido                                   |
| `404`  | Conexão não encontrada (ou não é um agregador)                    |
| `409`  | Já existe uma conexão com esse nome de configuração               |