> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Discovery

> Use o Discovery para detectar fontes de dados externas, inspecionar os schemas delas e puxar transações para o Matcher automaticamente.

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:

1. **Verificar o status**: confirme que o Discovery e o motor embutido dele estão disponíveis.
2. **Navegar pelas conexões**: veja todas as fontes de dados a que o motor embutido tem acesso.
3. **Inspecionar uma conexão**: revise o schema para entender quais campos estão disponíveis.
4. **Testar uma conexão**: valide a conexão antes de se comprometer com uma extração.
5. **Criar uma extração**: peça que o Matcher puxe dados de uma fonte específica.
6. **Monitorar o progresso**: acompanhe o status da extração conforme os dados chegam.
7. **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.

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/status" \
  -H "Authorization: Bearer $TOKEN"
```

<Tip>
  Referência da API: [Obter o status do Discovery](/pt/reference/products/matcher/discovery-status)
</Tip>

### Navegar pelas conexões

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

```bash theme={null}
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.

<Tip>
  Referência da API: [Listar conexões](/pt/reference/products/matcher/list-discovery-connections)
</Tip>

### Obter uma conexão

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

```bash theme={null}
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.

<Tip>
  Referência da API: [Obter conexão do Discovery](/pt/reference/products/matcher/retrieve-discovery-connection)
</Tip>

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

```bash theme={null}
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.

<Tip>
  Referência da API: [Obter o schema da conexão](/pt/reference/products/matcher/get-connection-schema)
</Tip>

### Testar uma conexão

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

```bash theme={null}
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.

<Tip>
  Referência da API: [Testar conexão](/pt/reference/products/matcher/test-discovery-connection)
</Tip>

### Criar uma extração

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

```bash theme={null}
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.

<Tip>
  Referência da API: [Criar extração](/pt/reference/products/matcher/create-extraction)
</Tip>

### Monitorar o progresso da extração

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

```bash theme={null}
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.

<Tip>
  Referência da API: [Obter extração](/pt/reference/products/matcher/retrieve-extraction)
</Tip>

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

```bash theme={null}
curl -X POST "https://api.matcher.example.com/v1/discovery/refresh" \
  -H "Authorization: Bearer $TOKEN"
```

<Tip>
  Referência da API: [Atualizar conexões](/pt/reference/products/matcher/refresh-discovery)
</Tip>

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

```bash theme={null}
curl -X GET "https://api.matcher.example.com/v1/discovery/connector-types" \
  -H "Authorization: Bearer $TOKEN"
```

#### Resposta

```json theme={null}
{
  "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

```bash theme={null}
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

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

### Listar, obter, atualizar e excluir

```bash theme={null}
# 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.

```bash theme={null}
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

```json theme={null}
{
  "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.

```bash theme={null}
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

```json theme={null}
{
  "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

***

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Próximos passos

***

<Card title="Fontes externas" icon="building-columns" href="/pt/products/matcher/integrations/matcher-external-sources" horizontal>
  Configure as fontes de dados externas a que o Discovery se conecta.
</Card>

<Card title="Mapeamento de campos" icon="arrows-left-right" href="/pt/products/matcher/configuration/matcher-field-mapping" horizontal>
  Mapeie campos dos dados extraídos para o modelo de transação do Matcher.
</Card>

<Card title="Referência da API do Discovery" icon="code" href="/pt/reference/products/matcher/discovery-status" horizontal>
  Referência completa da API para os endpoints do Discovery.
</Card>