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

***

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:

1. **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.
2. **Verificar o status**: veja quantas conexões o tenant tem e quando elas sincronizaram pela última vez.
3. **Navegar pelas conexões**: veja as conexões de banco de dados do tenant.
4. **Inspecionar uma conexão**: revise o schema para entender quais campos estão disponíveis.
5. **Testar uma conexão**: valide a conexão antes de se comprometer com uma extração.
6. **Criar uma extração**: peça que o Matcher puxe dados de uma fonte específica.
7. **Monitorar o progresso**: acompanhe o status da extração conforme os dados chegam.
8. **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.

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

```bash theme={null}
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](#list-connector-types) 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.

```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](https://docs.lerian.studio/pt/reference/products/matcher/discovery-status.md)

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

> [!TIP]
>
> Referência da API: [Listar conexões](https://docs.lerian.studio/pt/reference/products/matcher/list-discovery-connections.md)

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

> [!TIP]
>
> Referência da API: [Obter conexão do Discovery](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-discovery-connection.md)

### 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](https://docs.lerian.studio/pt/reference/products/matcher/get-connection-schema.md)

### Obter o histórico do schema

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

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

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

> [!TIP]
>
> Referência da API: [Testar conexão](https://docs.lerian.studio/pt/reference/products/matcher/test-discovery-connection.md)

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

```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": {
      "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.

> [!TIP]
>
> Referência da API: [Criar extração](https://docs.lerian.studio/pt/reference/products/matcher/create-extraction.md)

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

> [!TIP]
>
> Referência da API: [Obter extração](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-extraction.md)

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

```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](https://docs.lerian.studio/pt/reference/products/matcher/refresh-discovery.md)

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

```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` (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](#connect-an-account-through-hosted-consent).

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",
  "awaitingConsent": false
}
```

### 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"
```

### Conectar uma conta por consentimento hospedado

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.

1. Crie a conexão sem `accountRef`. A resposta traz `"awaitingConsent": true`.
2. Obtenha o `id` da conexão na resposta da listagem.
3. Solicite um token de consentimento para a conexão. A requisição não tem corpo.
4. Abra o widget de consentimento do fornecedor com o `token` da resposta.
5. 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.

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

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

***

> [accordion] 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] 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] 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

***

> [card] [Fontes externas](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-external-sources.md)
>
> Configure as fontes de dados externas a que o Discovery se conecta.

> [card] [Mapeamento de campos](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-field-mapping.md)
>
> Mapeie campos dos dados extraídos para o modelo de transação do Matcher.

> [card] [Referência da API do Discovery](https://docs.lerian.studio/pt/reference/products/matcher/discovery-status.md)
>
> Referência completa da API para os endpoints do Discovery.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.