Discovery

O Discovery automatiza a detecção e extração de fontes de dados através do Fetcher. Em vez de carregar arquivos manualmente, o Discovery se conecta a sistemas externos, identifica os dados disponíveis e extrai transações diretamente no Matcher.

O que o Discovery resolve

O upload manual de arquivos gera atrito em cada etapa. As equipes exportam arquivos, os transferem, monitoram falhas e reenviam quando algo dá errado. Esse processo é demorado, propenso a erros e se quebra quando o volume de dados cresce. O Discovery substitui o pipeline manual. Ele se conecta a sistemas externos através do Fetcher, detecta fontes de dados disponíveis automaticamente e traz transações para o Matcher sob demanda. Quando uma nova fonte de dados aparece — uma nova conexão bancária, um novo processador de pagamentos — o Discovery a encontra sem reconfiguração.

Como o Discovery funciona

O Discovery opera sobre o motor de extração do Fetcher, que o Matcher hospeda no mesmo processo; o Fetcher não é um serviço remoto. O motor embutido gerencia as conexões com bancos de dados externos e executa as extrações localmente. O Discovery expõe essas conexões, coordena o processo de extração e entrega os resultados diretamente à Ingestion. O fluxo de trabalho tem sete passos:

Verificar status — Confirmar que o Discovery e seu motor embutido estão disponíveis.
Explorar conexões — Ver todas as fontes de dados às quais o motor embutido tem acesso.
Inspecionar uma conexão — Revisar o schema para entender quais campos estão disponíveis.
Testar uma conexão — Validar a conexão antes de se comprometer com uma extração.
Criar uma extração — Solicitar que o Matcher obtenha dados de uma fonte específica.
Monitorar progresso — Acompanhar o status da extração enquanto os dados fluem.
Atualizar conexões — Reescanear quando novas fontes de dados são adicionadas.

Fluxo de trabalho do Discovery

Verificar status do Discovery

Verifique se o Discovery e o motor embutido do Fetcher estão operacionais antes de começar.

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

Referência API: Obter status do Discovery

Explorar conexões

Liste todas as fontes de dados disponíveis através do motor embutido do Fetcher.

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

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

Referência API: Listar conexões

Obter uma conexão

Recupere uma única conexão Fetcher descoberta por seu identificador interno:

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 — útil quando você já possui um connectionId (por exemplo, do query rail de um binding de fonte) e quer seus detalhes atuais sem listar todas as conexões.

Referência API: Obter conexão do discovery

Inspecionar uma conexão

Revise o schema de uma conexão específica para entender quais campos de dados estão disponíveis antes de extrair.

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 necessários — IDs de transação, valores, datas, referências — existem antes de configurar os mapeamentos de campos.

Referência API: Obter schema da conexão

Testar uma conexão

Valide que o Matcher consegue alcançar e ler de 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 conectividade e acesso de leitura. Sempre teste antes de criar uma extração — especialmente para conexões novas ou modificadas recentemente.

Referência API: Testar conexão

Criar uma extração

Solicite que o Matcher obtenha dados de transações de uma conexão específica no 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 API: Criar extração

Monitorar progresso da extração

Acompanhe o status de uma extração ativa consultando seu status com GET.

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

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

Referência API: Obter extração

Atualizar conexões disponíveis

Quando novas fontes de dados são registradas no motor embutido, acione uma atualização para que o Discovery as detecte.

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

Referência API: Atualizar conexões

Listar tipos de conectores

Liste os tipos de conector (fonte de dados) que o registro do motor registrou para esta implantação. Cada entrada carrega uma category derivada do backend (database ou rest). O registro é ao vivo—apenas os conectores registrados na inicialização aparecem. Fornecedores agregadores (Pluggy/Belvo) são excluídos; provisione-os através da superfície de aggregator-connections descrita 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 de agregador de dados do Open Finance (Pluggy ou Belvo) permitem que o Matcher obtenha transações de agregadores bancários. O material de credenciais (clientId/secret) é selado na gravação e nunca retornado—toda 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": "..."
  }'

Todos os seis campos são obrigatórios. vendor é um de pluggy ou belvo. configName é o nome com escopo de tenant ao qual o endpoint de emissão de tokens do webhook se vincula. 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

Execute uma verificação de conectividade ao vivo contra a credencial já selada de uma conexão existente, endereçada por (vendor, configName). Nenhuma credencial é fornecida ou retornada—o resultado é um estado de saúde booleano livre de segredos.

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

Resposta

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

Tokens de webhook de agregador

Os agregadores enviam sinais de mudança de dados ao Matcher via webhooks. Emita um token opaco vinculado a uma conexão de agregador e depois configure a URL retornada no painel do fornecedor.

Emitir um token de webhook

O token bruto e sua URL voltada ao provedor são retornados exatamente uma 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"
  }'

Resposta

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

Recebimento de webhooks

O fornecedor chama POST /v1/discovery/webhooks/{provider}/{webhookToken} (sem JWT de operador). É autenticado pelo token opaco do caminho mais uma verificação de origem por provedor: um HMAC-SHA256 válido do corpo bruto no cabeçalho X-Webhook-Signature, ou a associação à lista de IPs de origem permitidas do provedor. Ambas as camadas falham de forma fechada. Uma primeira entrega válida retorna 202 Accepted e os dados sinalizados são obtidos de forma assíncrona para o pipeline de ingestão; uma repetição de um evento já processado retorna 200 OK.

Melhores 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 — especialmente ao conectar a uma fonte nova ou após uma rotação de credenciais.

Inspecione schemas antes de mapear campos

Os nomes dos campos variam entre sistemas. Um banco pode chamar a data da transação de value_date enquanto seu ledger usa posting_date. Verifique o schema antes de configurar mapeamentos de campos para evitar discrepâncias silenciosas.

Monitore extrações ativamente para conjuntos de dados grandes

Extrações grandes levam tempo. Não assuma que foram concluídas — consulte o status da extração e confirme a contagem de registros antes de iniciar uma execução de conciliação. Iniciar uma execução com dados incompletos gera exceções incorretas.

Atualize conexões quando as fontes mudarem

O Discovery não escaneia novas conexões automaticamente. Quando um novo processador de pagamentos é adicionado ou um novo banco de dados é registrado no motor embutido, acione uma atualização. Caso contrário, o Discovery não mostrará a nova fonte.

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

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

Próximos passos

Fontes externas

Configure as fontes de dados externas às quais o Discovery se conecta.

Mapeamento de campos

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

Referência 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

Fluxo de trabalho do Discovery

Verificar status do Discovery

Explorar conexões

Obter uma conexão

Inspecionar uma conexão

Testar uma conexão

Criar uma extração

Monitorar progresso da extração

Atualizar conexões disponíveis

Listar tipos de conectores

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

Recebimento de webhooks

Melhores práticas

Próximos passos

Fontes externas

Mapeamento de campos

Referência API do Discovery

​O que o Discovery resolve

​Como o Discovery funciona

​Fluxo de trabalho do Discovery

​Verificar status do Discovery

​Explorar conexões

​Obter uma conexão

​Inspecionar uma conexão

​Testar uma conexão

​Criar uma extração

​Monitorar progresso da extração

​Atualizar conexões disponíveis

​Listar tipos de conectores

​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

​Recebimento de webhooks

​Melhores práticas

​Próximos passos

Fontes externas

Mapeamento de campos

Referência API do Discovery

O que o Discovery resolve

Como o Discovery funciona

Fluxo de trabalho do Discovery

Verificar status do Discovery

Explorar conexões

Obter uma conexão

Inspecionar uma conexão

Testar uma conexão

Criar uma extração

Monitorar progresso da extração

Atualizar conexões disponíveis

Listar tipos de conectores

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

Recebimento de webhooks

Melhores práticas

Próximos passos