Conexões de agregador

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.

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

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.
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",
  "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:

{
  "name": "Pluggy Main Account",
  "type": "BANK",
  "side": "RIGHT",
  "config": {
    "connection_config_name": "pluggy-main"
  }
}

Referência da API: Criar fonte

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"

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.

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

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 descreve o fluxo completo.

Excluir

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.

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

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

curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"

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

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>",
  "webhook_url": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/<raw-token>",
  "vendor": "pluggy"
}

Configure a webhook_url devolvida no dashboard do agregador. Uma conexão de destino ausente 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
`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)
`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

Visão geral

Guias

Console

Operações

Conexões de agregador

Criar uma conexão

Vincular uma fonte de conciliação

Listar, obter, atualizar, excluir

Atualizar

Excluir

Testar uma conexão

Tipos de conector

Emitir um token de webhook

Códigos de resposta

​Criar uma conexão

​Vincular uma fonte de conciliação

​Listar, obter, atualizar, excluir

​Atualizar

​Vincular uma conta por consentimento hospedado

​Excluir

​Testar uma conexão

​Tipos de conector

​Emitir um token de webhook

​Códigos de resposta

Criar uma conexão

Vincular uma fonte de conciliação

Listar, obter, atualizar, excluir

Atualizar

Vincular uma conta por consentimento hospedado

Excluir

Testar uma conexão

Tipos de conector

Emitir um token de webhook

Códigos de resposta