> ## 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 agregador > Provisione conexões com agregadores de dados de Open Finance (Pluggy, Belvo), teste-as, veja os tipos de conector e emita tokens de webhook para as buscas de entrada. As conexões de agregador permitem que o Matcher puxe dados de transações de agregadores de dados de Open Finance (Pluggy, Belvo). Você cria uma conexão com uma credencial selada, usa o fluxo de consentimento hospedado do fornecedor para vincular uma conta quando preciso, emite um token de webhook vinculado à conexão, e então os webhooks do agregador comandam as buscas de entrada. Este guia cobre o ciclo de vida completo. As credenciais (`clientId`/`secret`) são **apenas de entrada**: o Matcher as sela antes de persistir e nunca as devolve em uma resposta, em um log ou em um erro. Cada resposta desta superfície é livre de segredos por construção. O tenant sempre vem do JWT, nunca do corpo da requisição. ## 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 única da conexão (no escopo do tenant). Uma duplicata é um `409`. **O endpoint de emissão de token de webhook vincula um token a este nome.** * `baseUrl`: URL base da API do fornecedor, armazenada como host da conexão. * `accountRef`: referência opaca e opcional da conta no fornecedor (`itemId` da Pluggy, id do link da Belvo) repassada na busca por webhook. Omita para criar uma conexão que aguarda o consentimento do cliente final. Vincule depois com `PUT` a referência devolvida pelo fornecedor. * `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": "", "awaitingConsent": true } ``` ## 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 uma `baseUrl` digitada errado não fique permanente. O **fornecedor é imutável**. A credencial é opcional: informe **os dois**, `clientId` e `secret`, para rotacionar a credencial selada, ou omita **os dois** para manter intacto o segredo armazenado. Informar exatamente um é 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" ``` O delete exclui a conexão em soft-delete (`204`), liberando o nome de configuração dela para reuso. Um id de conexão que não é de agregador retorna `404` em qualquer operação por id. Esta superfície nunca confirma a existência de uma linha que não é de agregador. ## Testar uma conexão *** Rode uma verificação de conectividade ao vivo para uma conexão existente e vinculada, usando a credencial já selada dela, endereçada por `configName`. O fornecedor vem da conexão armazenada. Esta chamada não recebe credencial e não devolve nenhuma. Uma conexão que aguarda consentimento não é testável até a referência de conta no fornecedor estar vinculada. ```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 } ``` Um resultado de credenciais que não funcionam é um resultado de teste **esperado**, mostrado como `"healthy": false` com `200`, não como erro. Uma conexão ausente ou um fornecedor armazenado sem caminho de teste de conectividade (hoje, a Belvo) aparece pela resposta de erro padrão. Nenhum teste roda. Use o campo `testable` da resposta da lista antes de oferecer a ação. ## Conectar uma conexão que aguarda consentimento *** Para uma conexão criada sem `accountRef`, emita um token de consentimento de vida curta e abra o widget de consentimento do próprio fornecedor no navegador do cliente final. A resposta carrega o token uma vez. O Matcher nunca o persiste e nunca o registra em log. Quando o widget devolve o id do item ou do link no fornecedor, vincule-o com `PUT /v1/discovery/aggregator-connections/{id}` e um corpo com `accountRef`. Você não precisa informar a credencial de novo. ```bash theme={null} curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}/connect-token" \ -H "Authorization: Bearer ***" ``` Para uma conexão já vinculada, o mesmo endpoint começa o novo consentimento e retorna `reconsent: true` com o `accountRef` vinculado exato. Use esse valor devolvido no widget do fornecedor, em vez de uma referência em cache local. Um deploy sem caminho de consentimento para o fornecedor retorna `422`. ## Tipos de conector *** Liste os tipos de conector que o registro do motor de fato registrou para este deploy, cada um marcado com uma categoria derivada do backend (`database` ou `rest`). A lista reflete o registro ao vivo. Apenas os conectores registrados no boot aparecem. Ela alimenta 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": "POSTGRESQL", "category": "database" }, { "type": "STRIPE", "category": "rest" } ] } ``` Esta lista não inclui os tipos de fornecedor agregador (Pluggy/Belvo). A superfície de conexões de agregador acima provisiona esses tipos. ## Emitir um token de webhook *** Emita um token de webhook vinculado a uma conexão de agregador existente. A resposta carrega o token bruto e a URL de webhook voltada ao provedor **uma vez**. O Matcher armazena apenas o hash SHA-256 do 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": "", "webhook_url": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/", "vendor": "pluggy" } ``` Configure a `webhook_url` devolvida no dashboard do agregador. Uma conexão de destino ausente retorna `404`. ## Códigos de resposta *** | Status | Significado | | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | Obtenção, lista, teste ou tipos de conector retornados | | `201` | Conexão criada / token emitido | | `204` | Conexão excluída em soft-delete | | `400` | Fornecedor inválido, par de credencial incompleto ou paginação inválida | | `401` | Não foi possível resolver o tenant | | `404` | Conexão não encontrada (ou não é de agregador) | | `422` | O fornecedor existente não pode passar por teste de conectividade, ou o deploy não tem caminho de consentimento hospedado para esse fornecedor | | `409` | Já existe uma conexão com esse nome de configuração |