Discovery

O Discovery automatiza a detecção de fontes de dados e a extração pelo motor de extração embutido do Matcher. Em vez de enviar arquivos manualmente, o Discovery se conecta a sistemas externos, identifica os dados disponíveis e extrai transações direto para o Matcher.

O que o Discovery resolve

O envio manual de arquivos cria atrito em cada passo. Os times exportam arquivos, transferem, monitoram falhas e reenviam quando algo dá errado. Esse processo consome tempo, é sujeito a erros e quebra quando o volume de dados cresce. O Discovery substitui o pipeline manual. Ele se conecta a sistemas externos pelo motor de extração, detecta as fontes de dados disponíveis automaticamente e puxa transações para o Matcher sob demanda. Quando uma nova fonte de dados aparece (uma nova conexão bancária, um novo processador de pagamento), o Discovery a encontra sem reconfiguração.

Como o Discovery funciona

O Discovery roda dentro do Matcher. Não existe serviço de extração separado para fazer deploy. O motor embutido gerencia as conexões com bancos de dados externos e roda as extrações localmente. O Discovery expõe essas conexões e coordena o processo de extração, entregando os resultados direto para a Ingestão. O workflow tem sete passos:

Verificar o status: confirme que o Discovery e o motor embutido dele estão disponíveis.
Navegar pelas conexões: veja todas as fontes de dados a que o motor embutido tem acesso.
Inspecionar uma conexão: revise o schema para entender quais campos estão disponíveis.
Testar uma conexão: valide a conexão antes de se comprometer com uma extração.
Criar uma extração: peça que o Matcher puxe dados de uma fonte específica.
Monitorar o progresso: acompanhe o status da extração conforme os dados chegam.
Atualizar as conexões: refaça a varredura quando novas fontes de dados aparecerem.

Workflow do Discovery

Verificar o status do Discovery

Antes de começar, verifique se o Discovery e o motor de extração embutido estão operacionais.

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

Referência da API: Obter o status do Discovery

Navegar pelas conexões

Liste todas as fontes de dados disponíveis pelo motor de extração embutido.

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

A resposta lista cada conexão com o nome, o tipo (banco de dados, API, repositório de arquivos) e o status atual.

Referência da API: Listar conexões

Obter uma conexão

Recupere uma única conexão descoberta pelo identificador interno dela:

curl -X GET "https://api.matcher.example.com/v1/discovery/connections/{connectionId}" \
  -H "Authorization: Bearer $TOKEN"

GET /v1/discovery/connections/{connectionId} retorna o ConnectionResponse completo (nome, tipo, status e metadados) de uma conexão. Use quando você já tem um connectionId, por exemplo, do trilho de consulta de um binding de fonte. Ele dá os detalhes atuais sem uma lista de todas as conexões.

Referência da API: Obter conexão do Discovery

Inspecionar uma conexão

Antes de extrair, revise o schema de uma conexão específica para entender quais campos de dados estão disponíveis.

curl -X GET "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/schema" \
  -H "Authorization: Bearer $TOKEN"

Use a inspeção de schema para confirmar que os campos obrigatórios (IDs de transação, valores, datas, referências) existem antes de montar os mapeamentos de campo.

Referência da API: Obter o schema da conexão

Testar uma conexão

Valide se o Matcher consegue alcançar e ler uma conexão antes de criar uma extração.

curl -X POST "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/test" \
  -H "Authorization: Bearer $TOKEN"

Um teste bem-sucedido confirma a conectividade e o acesso de leitura. Sempre teste antes de criar uma extração, principalmente para conexões novas ou alteradas há pouco.

Referência da API: Testar conexão

Criar uma extração

Peça que o Matcher puxe dados de transações de uma conexão específica para o contexto atual.

curl -X POST "https://api.matcher.example.com/v1/discovery/connections/{connectionId}/extractions" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": {
      "transactions": {}
    },
    "startDate": "2026-06-01",
    "endDate": "2026-06-30"
  }'

A resposta retorna um ID de extração. Use-o para monitorar o progresso.

Referência da API: Criar extração

Monitorar o progresso da extração

Acompanhe o status de uma extração ativa fazendo polling do status dela com GET.

curl -X GET "https://api.matcher.example.com/v1/discovery/extractions/{extractionId}" \
  -H "Authorization: Bearer $TOKEN"

O status da extração passa de PENDING → SUBMITTED → EXTRACTING → COMPLETE (ou FAILED/CANCELLED). A resposta carrega o status da extração, um errorMessage quando ela falhou e o ingestionJobId vinculado assim que a extração faz a ponte para a ingestão.

Referência da API: Obter extração

Atualizar as conexões disponíveis

Quando você registrar uma nova fonte de dados no motor embutido, dispare uma atualização para o Discovery reconhecê-la.

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

Referência da API: Atualizar conexões

Listar os tipos de conector

Liste os tipos de conector (datasource) que o registro do motor registrou para este deploy. Cada entrada carrega uma category derivada do backend (database ou rest). O registro é ao vivo. Apenas os conectores registrados no boot aparecem. Esta lista não inclui os fornecedores agregadores (Pluggy/Belvo). Provisione esses pela superfície de conexões de agregador abaixo.

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

Resposta

{
  "types": [
    { "type": "POSTGRESQL", "category": "database" },
    { "type": "MYSQL", "category": "database" }
  ]
}

Conexões de agregador (Open Finance)

As conexões com agregadores de dados de Open Finance (Pluggy ou Belvo) permitem que o Matcher puxe transações de agregadores bancários. O material de credencial (clientId/secret) é selado na escrita e nunca devolvido. Cada leitura é livre de segredos por construção.

Criar uma conexão de agregador

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

Envie cinco campos obrigatórios: vendor, configName, baseUrl, clientId e secret. O campo accountRef é opcional. Omita para criar uma conexão que aguarda o consentimento do cliente final no fluxo hospedado pelo fornecedor. Depois vincule com PUT o id do item ou do link devolvido. O campo vendor é pluggy ou belvo. O campo configName é o nome no escopo do tenant a que o endpoint de emissão de token de webhook se vincula. Uma criação bem-sucedida retorna 201 com uma conexão livre de segredos.

Resposta

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

Listar, obter, atualizar e excluir

# List (cursor-paginated, secret-free)
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections" \
  -H "Authorization: Bearer $TOKEN"

# Get one by id
curl -X GET "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

# Update (PUT). vendor is immutable. Supply clientId+secret together to rotate
# the sealed credential, or omit both to keep the stored secret intact.
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"
  }'

# Delete (soft-delete; frees the config name for reuse). Returns 204.
curl -X DELETE "https://api.matcher.example.com/v1/discovery/aggregator-connections/{id}" \
  -H "Authorization: Bearer $TOKEN"

Testar uma conexão de agregador

Rode uma verificação de conectividade ao vivo contra a credencial já selada de uma conexão existente e vinculada, endereçada por configName. O Matcher lê o fornecedor da conexão armazenada. Esta chamada não recebe credencial e não devolve nenhuma. Credenciais armazenadas inválidas dão um resultado de teste esperado: 200 com "healthy": false, não um erro. Uma conexão ausente, uma conexão não vinculada ou um fornecedor existente 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.

curl -X POST "https://api.matcher.example.com/v1/discovery/aggregator-connections/test" \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "pluggy-main"
  }'

Resposta

{
  "vendor": "pluggy",
  "configName": "pluggy-main",
  "healthy": true
}

Tokens de webhook de agregador

Os agregadores enviam sinais de mudança de dados para o Matcher por webhooks. Emita um token opaco vinculado a uma conexão de agregador e depois configure a URL devolvida no dashboard do fornecedor.

Emitir um token de webhook

O Matcher devolve o token bruto e a URL voltada ao provedor exatamente 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"
  }'

Resposta

{
  "vendor": "pluggy",
  "token": "<raw-token-shown-once>",
  "webhook_url": "https://api.matcher.example.com/v1/discovery/webhooks/pluggy/<raw-token>"
}

Receber webhooks

O fornecedor chama POST /v1/discovery/webhooks/{provider}/{webhookToken} (sem JWT de operador). Duas camadas autenticam a chamada: o token opaco no path mais uma verificação de origem por provedor. Essa verificação é um HMAC-SHA256 válido do corpo bruto no header X-Webhook-Signature, ou a presença na lista de IPs de origem permitidos do provedor. As duas camadas falham fechadas. Uma primeira entrega válida retorna 202 Accepted. O Matcher então puxa os dados sinalizados de forma assíncrona para o pipeline de ingestão. Um replay de um evento já processado retorna 200 OK.

Boas práticas

Sempre teste as conexões antes de extrair

Uma extração que falha no meio da execução é mais difícil de recuperar do que um teste que falha. Teste cada conexão antes de criar uma extração, principalmente ao conectar a uma fonte nova ou depois de uma rotação de credencial.

Inspecione os schemas antes de mapear campos

Os nomes de campo variam entre sistemas. Um banco pode chamar a data da transação de value_date, enquanto seu ledger usa posting_date. Confira o schema antes de configurar os mapeamentos de campo para evitar divergências silenciosas.

Monitore de perto as extrações de conjuntos de dados grandes

Extrações grandes levam tempo. Não suponha que terminaram. Faça polling do status da extração e confirme a contagem de registros antes de começar uma execução de correspondência. Começar uma execução com dados incompletos gera exceções erradas.

Atualize as conexões quando as fontes mudarem

O Discovery não procura conexões novas automaticamente. Quando você adicionar um novo processador de pagamento, ou registrar um novo banco de dados no motor embutido, dispare uma atualização. Caso contrário, o Discovery não mostra a fonte nova.

Limite as extrações ao período de conciliação

Use parâmetros de intervalo de datas para extrair apenas os dados relevantes ao período de conciliação atual. Extrair dados sem limite aumenta o tempo de processamento e pode puxar registros que pertencem a contextos já fechados.

Próximos passos

Fontes externas

Configure as fontes de dados externas a que o Discovery se conecta.

Mapeamento de campos

Mapeie campos dos dados extraídos para o modelo de transação do Matcher.

Referência da API do Discovery

Referência completa da API para os endpoints do Discovery.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

O que o Discovery resolve

Como o Discovery funciona

Workflow do Discovery

Verificar o status do Discovery

Navegar pelas conexões

Obter uma conexão

Inspecionar uma conexão

Testar uma conexão

Criar uma extração

Monitorar o progresso da extração

Atualizar as conexões disponíveis

Listar os tipos de conector

Resposta

Conexões de agregador (Open Finance)

Criar uma conexão de agregador

Resposta

Listar, obter, atualizar e excluir

Testar uma conexão de agregador

Resposta

Tokens de webhook de agregador

Emitir um token de webhook

Resposta

Receber webhooks

Boas práticas

Próximos passos

Fontes externas

Mapeamento de campos

Referência da API do Discovery

​O que o Discovery resolve

​Como o Discovery funciona

​Workflow do Discovery

​Verificar o status do Discovery

​Navegar pelas conexões

​Obter uma conexão

​Inspecionar uma conexão

​Testar uma conexão

​Criar uma extração

​Monitorar o progresso da extração

​Atualizar as conexões disponíveis

​Listar os tipos de conector

​Resposta

​Conexões de agregador (Open Finance)

​Criar uma conexão de agregador

​Resposta

​Listar, obter, atualizar e excluir

​Testar uma conexão de agregador

​Resposta

​Tokens de webhook de agregador

​Emitir um token de webhook

​Resposta

​Receber webhooks

​Boas práticas

​Próximos passos

Fontes externas

Mapeamento de campos

Referência da API do Discovery

O que o Discovery resolve

Como o Discovery funciona

Workflow do Discovery

Verificar o status do Discovery

Navegar pelas conexões

Obter uma conexão

Inspecionar uma conexão

Testar uma conexão

Criar uma extração

Monitorar o progresso da extração

Atualizar as conexões disponíveis

Listar os tipos de conector

Resposta

Conexões de agregador (Open Finance)

Criar uma conexão de agregador

Resposta

Listar, obter, atualizar e excluir

Testar uma conexão de agregador

Resposta

Tokens de webhook de agregador

Emitir um token de webhook

Resposta

Receber webhooks

Boas práticas

Próximos passos