> ## 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 Discovery e Fetcher para detectar fontes de dados externas, inspecionar seus esquemas e trazer transações para o Matcher de forma automática.

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 através do Fetcher, o serviço interno de extração de dados da Lerian. O Fetcher gerencia as conexões com bancos de dados externos e extrai dados deles em nome dos produtos Lerian. O Discovery expõe essas conexões ao Matcher e coordena o processo de extração.

O fluxo de trabalho tem sete passos:

1. **Verificar status** — Confirmar que o Fetcher está conectado e o Discovery está disponível.
2. **Explorar conexões** — Ver todas as fontes de dados que o Fetcher tem acesso.
3. **Inspecionar uma conexão** — Revisar o schema para entender quais campos estão disponíveis.
4. **Testar uma conexão** — Validar a conexão antes de iniciar uma extração.
5. **Criar uma extração** — Solicitar que o Matcher obtenha dados de uma fonte específica.
6. **Monitorar progresso** — Acompanhar o status da extração enquanto os dados fluem.
7. **Atualizar conexões** — Reescanear quando novas fontes de dados são adicionadas.

## Fluxo de trabalho do Discovery

***

### Verificar status do Discovery

Verifique se o Fetcher está conectado e o Discovery está operacional antes de começar.

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

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

### Explorar conexões

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

```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 seu nome, tipo (banco de dados, API, armazenamento de arquivos) e status atual.

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

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

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

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

### Testar uma conexão

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

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

### Criar uma extração

Solicite que o Matcher obtenha dados de transações de uma conexão específica no 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 '{
    "contextId": "ctx_abc123",
    "dateRange": {
      "from": "2024-01-01",
      "to": "2024-01-31"
    }
  }'
```

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

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

### Monitorar progresso da extração

Acompanhe o status de uma extração ativa. Para conjuntos de dados grandes, use o endpoint de polling para verificar o progresso incrementalmente.

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

# Consultar atualizações
curl -X POST "https://api.matcher.example.com/v1/discovery/extractions/{extractionId}/poll" \
  -H "Authorization: Bearer $TOKEN"
```

O status da extração transiciona de `pending` → `running` → `completed` (ou `failed`). A resposta inclui a contagem de registros extraídos e quaisquer erros encontrados.

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

### Atualizar conexões disponíveis

Quando novas fontes de dados são adicionadas ao Fetcher, acione uma atualização para que o Discovery as detecte.

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

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

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

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

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

  <Accordion title="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 é incorporado ao Fetcher, acione uma atualização. Caso contrário, o Discovery não mostrará a nova fonte.
  </Accordion>

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

<Note>
  No modo multi-tenant, o Matcher se autentica com o Fetcher usando credenciais machine-to-machine (M2M) por tenant. Essas credenciais são gerenciadas pelo AWS Secrets Manager e cacheadas automaticamente. Veja [Modo Multi-Tenant](/pt/matcher/configuration/matcher-multi-tenant#m2m-credentials-fetcher-integration) para detalhes de configuração.
</Note>

## Próximos passos

***

<CardGroup cols={2}>
  <Card title="Fontes externas" icon="building-columns" href="/pt/matcher/integrations/matcher-external-sources">
    Configure as fontes de dados externas às quais o Discovery se conecta.
  </Card>

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

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