> ## 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, vincula uma fonte de conciliação a ela e emite um token de webhook vinculado à conexão. Os webhooks do agregador então comandam as buscas de entrada. Este guia cobre o ciclo de vida completo. > [!NOTE] > > 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. 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 da conta no fornecedor (`itemId` da Pluggy, id do link da Belvo) repassada na busca por webhook. É opcional. Omita-a para conectar a conta por [consentimento hospedado](#bind-an-account-through-hosted-consent). * `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", "awaitingConsent": false } ``` ## Vincular uma fonte de conciliação *** O Matcher ingere os dados buscados na fonte de conciliação que nomeia a conexão. Em exatamente uma fonte, defina `config.connection_config_name` com o `configName` da conexão: ```json theme={null} { "name": "Pluggy Main Account", "type": "BANK", "side": "RIGHT", "config": { "connection_config_name": "pluggy-main" } } ``` > [!TIP] > > Referência da API: [Criar fonte](https://docs.lerian.studio/pt/reference/products/matcher/create-source.md) ## 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" ``` Cada linha da listagem traz `id`, `vendor`, `configName`, `baseUrl`, `accountRef`, `testable` e `awaitingConsent`. ### 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`. Os outros campos também são opcionais: um campo que você omite mantém o valor armazenado. ```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" }' ``` ### Vincular uma conta por consentimento hospedado Uma conexão criada sem `accountRef` aguarda consentimento: ela mostra `"awaitingConsent": true`. `POST /v1/discovery/aggregator-connections/{id}/connect-token` retorna um token para o widget de consentimento do fornecedor. Envie o id do item ou do link que o widget devolve como `accountRef` na chamada de atualização acima. O [Discovery](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-discovery.md#connect-an-account-through-hosted-consent) descreve o fluxo completo. ### 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, usando a credencial já selada dela, endereçada por `configName`. O Matcher lê o fornecedor da conexão armazenada. Esta chamada não recebe credencial e não devolve nenhuma. ```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] > > 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 retorna `404`. O Matcher não consegue testar conexões da Belvo, então uma conexão da Belvo retorna `422` (`MTCH-0210`). Uma conexão que aguarda consentimento retorna `422` (`MTCH-0211`). ## Tipos de conector *** Liste os tipos de conector que o registro do motor 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", "requiredFields": ["apiKey"] } ] } ``` Cada entrada `rest` lista em `requiredFields` os campos de credencial que uma [conexão REST](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-discovery.md#create-a-rest-connection) desse tipo exige. 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`. A emissão não deduplica novas tentativas. Reenviar a requisição, mesmo com a mesma chave `X-Idempotency`, emite outro token ativo. Leia a primeira resposta em vez de reenviá-la. ## Listar tokens de webhook *** Liste os tokens do seu tenant, ativos e revogados, do mais novo para o mais antigo. A resposta traz apenas metadados: nunca o token nem o hash dele. ```bash theme={null} curl -X GET "https://api.matcher.example.com/v1/discovery/webhooks/tokens" \ -H "Authorization: Bearer $TOKEN" ``` ```json theme={null} { "tokens": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "vendor": "pluggy", "configName": "pluggy-main", "createdAt": "2026-11-03T12:00:00Z", "revokedAt": "2026-11-03T15:30:00Z" } ] } ``` `revokedAt` não aparece enquanto o token está ativo. ## Revogar um token de webhook *** Revogue um token para que as entregas do agregador na URL dele sejam recusadas. A revogação é permanente. Os outros tokens ativos da mesma conexão continuam funcionando. ```bash theme={null} curl -X DELETE "https://api.matcher.example.com/v1/discovery/webhooks/tokens/{tokenId}" \ -H "Authorization: Bearer $TOKEN" ``` Uma revogação bem-sucedida retorna `204`. Um id de token que não corresponde a nenhum token ativo do seu tenant retorna `404`. O Matcher verifica cada entrega do fornecedor por uma assinatura HMAC-SHA256 do corpo bruto em `X-Webhook-Signature` ou pelo IP de origem. Uma entrega que falha na verificação recebe `401`. ## Códigos de resposta *** | Status | Significado | | - | - | | `200` | Obtenção, lista, teste ou tipos de conector retornados | | `201` | Conexão criada, token de webhook emitido ou token de consentimento emitido | | `204` | Conexão excluída em soft-delete ou token de webhook revogado | | `400` | Par de credencial incompleto, credencial malformada ou cursor de paginação inválido | | `401` | Não foi possível resolver o tenant | | `404` | Conexão não encontrada (ou não é de agregador), ou nenhum token de webhook ativo corresponde ao id | | `422` | A requisição falha na validação, por exemplo um campo ausente ou um fornecedor diferente de `pluggy` ou `belvo` | | `422` (`MTCH-0210`) | O Matcher não consegue testar este fornecedor (Belvo) | | `422` (`MTCH-0211`) | A conexão aguarda consentimento, então nenhum teste rodou | | `422` (`MTCH-0212`) | O fornecedor não emitiu um token de consentimento | | `422` (`MTCH-0213`) | O Matcher não tem fluxo de consentimento para este fornecedor | | `409` | Já existe uma conexão com esse nome de configuração | This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.