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

Com o envio manual de arquivos, 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, lê os schemas deles e puxa transações para o Matcher sob demanda.

Como o Discovery funciona

O Discovery roda dentro do Matcher. 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, coordena o processo de extração e entrega os resultados direto para a Ingestão. O workflow tem oito passos:

Criar uma conexão: registre um banco de dados com o endereço e o usuário dele, ou uma conexão REST com a API de um provedor.
Verificar o status: veja quantas conexões o tenant tem e quando elas sincronizaram pela última vez.
Navegar pelas conexões: veja as conexões de banco de dados do tenant.
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: sincronize de novo as conexões a partir do motor embutido.

Workflow do Discovery

Criar uma conexão

Registre uma conexão de banco de dados para o tenant.

curl -X POST "https://api.matcher.example.com/v1/discovery/connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "prod-ledger-db",
    "databaseType": "POSTGRESQL",
    "host": "db.internal.example.com",
    "port": 5432,
    "databaseName": "ledger",
    "userName": "matcher_ro",
    "password": "..."
  }'

configName, databaseType, host, port, databaseName e userName são obrigatórios. schema e password são opcionais, e o Matcher nunca devolve password. Uma criação bem-sucedida retorna 201. Atualize uma conexão com PATCH e exclua-a com DELETE em /v1/discovery/connections/{connectionId}.

Criar uma conexão REST

Crie uma conexão REST para extrair dados da API de um provedor em vez de um banco de dados.

curl -X POST "https://api.matcher.example.com/v1/discovery/rest-connections" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "configName": "stripe-main",
    "connectorType": "STRIPE",
    "apiKey": "..."
  }'

configName e connectorType são obrigatórios. connectorType é PAGBANK, STRIPE ou PIX_BCB. baseURL é opcional e define o endereço da API do provedor para esta conexão. Cada tipo de conector também exige seus próprios campos de credencial:

`connectorType`	Campos de credencial obrigatórios
`PAGBANK`	`establishmentID`, `ediToken`
`STRIPE`	`apiKey`
`PIX_BCB`	`clientID`, `clientSecret`, `clientCert`, `clientKey`

O Matcher armazena as credenciais criptografadas. Listar os tipos de conector retorna os mesmos nomes de campo em requiredFields. Uma criação bem-sucedida retorna 201, e a conexão aparece na lista de conexões como qualquer outra conexão. Em uma conexão REST, PATCH aceita apenas configName. Para mudar qualquer outra coisa, exclua a conexão e crie-a de novo.

Verificar o status do Discovery

Leia a contagem de conexões do tenant e o horário da última sincronização.

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 de banco de dados com configName, databaseType, host, banco, status e se o schema dela foi descoberto.

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 os mesmos campos 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

Obter o histórico do schema

Leia as gerações anteriores do schema de uma conexão, da mais antiga para a mais recente.

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

A resposta traz connectionId e uma lista generations. Cada geração traz archivedAt, o momento em que ela deixou de ser o schema vigente, e suas tables. Quando todas as tabelas de uma geração compartilham uma causa, a geração também traz retirementCause:

`retirementCause`	Significado
`ABSENT_FROM_CATALOG`	O catálogo da fonte deixou de listar a tabela.
`COLUMN_SET_SUPERSEDED`	O catálogo ainda listava a tabela, mas com um conjunto diferente de colunas.
`CONNECTION_RETIRED`	Alguém aposentou a conexão.
`UNKNOWN_LEGACY`	Uma versão anterior arquivou a geração e não registrou causa.

Uma conexão desconhecida retorna 404.

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"

O teste conecta ao banco de dados e faz um ping. Ele não verifica o acesso de leitura às tabelas. Um teste com falha retorna 200 com "healthy": false e um errorMessage. 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 uma conexão. A requisição não informa nenhum contexto. O Matcher ingere o resultado na fonte FETCHER vinculada à conexão.

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

Cada chave em tables precisa ser um nome de tabela exatamente como o schema da conexão o lista. 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). Uma extração falha quando o resultado dela passa de 2 GiB. 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

A atualização sincroniza de novo as conexões do tenant a partir do motor embutido. Uma conexão que o motor não informa mais vira UNREACHABLE.

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 o seu ambiente. 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 (o id do item da Pluggy ou o id do link da Belvo) é opcional. Sem ele, o Matcher cria uma conexão que aguarda consentimento. Veja Conectar uma conta por consentimento hospedado. 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",
  "awaitingConsent": false
}

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"

Use este fluxo quando você ainda não tem o id do item ou do link do fornecedor. O cliente final autoriza o acesso no próprio widget de consentimento do fornecedor.

Crie a conexão sem accountRef. A resposta traz "awaitingConsent": true.
Obtenha o id da conexão na resposta da listagem.
Solicite um token de consentimento para a conexão. A requisição não tem corpo.
Abra o widget de consentimento do fornecedor com o token da resposta.
Envie o id do item ou do link que o widget devolve como accountRef em PUT /v1/discovery/aggregator-connections/{id}. Você não precisa enviar outros campos.

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

A resposta 201 traz vendor, configName, token, expiresAt, reconsent e accountRef. Para uma conexão que já tem um accountRef, o token renova o consentimento para esse mesmo item ou link. Nesse caso, reconsent é true, e accountRef traz o id vinculado. Passe esse accountRef para o modo de atualização do widget. A resposta mostra o token de consentimento uma única vez, e o Matcher não o armazena. Use-o antes de expiresAt. Depois desse momento, o fornecedor o recusa. Um id de conexão que não é uma conexão de agregador retorna 404. Se o fornecedor não emitir um token, a chamada retorna 422 (MTCH-0212). Se o Matcher não tiver fluxo de consentimento para o fornecedor, a chamada retorna 422 (MTCH-0213).

Testar uma conexão de agregador

Rode uma verificação de conectividade ao vivo contra a credencial já selada de uma conexão existente. Envie apenas o 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 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). Nesses casos, nenhum teste roda. Cada linha da resposta da listagem traz testable, que indica se um teste pode rodar.

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. Quando o provedor tem um segredo HMAC, essa verificação é um HMAC-SHA256 válido, em hexadecimal, do corpo bruto no header X-Webhook-Signature. Nos outros casos, é 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. Uma nova entrega de um evento que o Matcher já recebeu 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 depois verifique o job de ingestão vinculado antes de começar uma execução de correspondência. Começar uma execução com dados incompletos gera exceções erradas.

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

Console

Operações

O que o Discovery resolve

Como o Discovery funciona

Workflow do Discovery

Criar uma conexão

Criar uma conexão REST

Verificar o status do Discovery

Navegar pelas conexões

Obter uma conexão

Inspecionar uma conexão

Obter o histórico do schema

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

​Criar uma conexão

​Criar uma conexão REST

​Verificar o status do Discovery

​Navegar pelas conexões

​Obter uma conexão

​Inspecionar uma conexão

​Obter o histórico do schema

​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

​Conectar uma conta por consentimento hospedado

​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

Criar uma conexão

Criar uma conexão REST

Verificar o status do Discovery

Navegar pelas conexões

Obter uma conexão

Inspecionar uma conexão

Obter o histórico do schema

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

Conectar uma conta por consentimento hospedado

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