Pular para o conteúdo principal
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.
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.

​
Criar uma conexão

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: 
{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "baseUrl": "https://api.pluggy.ai",
  "accountRef": "a1b2c3d4-5678-90ab-cdef-1234567890ab"
}

​
Listar, obter, atualizar, excluir

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

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. 
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" }'

{ "vendor": "pluggy", "configName": "pluggy-main", "healthy": true }
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.

​
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. 
curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"

{
  "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. 
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"
  }'

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

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