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

# Início rápido da API do Matcher

> Coloque o Matcher em funcionamento: crie seu primeiro contexto de conciliação, envie arquivos e revise as transações correspondentes com cURL e a API do Matcher.

> [!TIP]
>
> **Este guia é para desenvolvedores.** Se você busca uma visão geral de negócio sobre o que o Matcher faz, veja [O que é o Matcher?](https://docs.lerian.studio/pt/products/matcher/what-is-matcher.md).

Este guia leva você da criação do seu primeiro contexto de conciliação até a revisão das transações correspondentes.

## Antes de começar

***

Você precisa de:

* O endereço da API do Matcher que a Lerian fornece a você
* Um token JWT válido para autenticação
* Dois arquivos de transação para conciliar (CSV, JSON ou XML)

Todos os exemplos usam `cURL`. Substitua `$TOKEN` pelo seu token JWT e `https://api.matcher.example.com` pelo endereço da API do Matcher.

## Etapa 1: Crie um contexto de conciliação

***

Um contexto define o escopo da sua conciliação: o que você compara e como.

> [!TIP]
>
> Referência da API: [Create context](https://docs.lerian.studio/pt/reference/products/matcher/create-context.md)

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Daily Bank Reconciliation",
   "type": "1:1",
   "interval": "daily"
 }'
```

O campo `type` define como o Matcher pareia as transações:

| Tipo | Descrição |
| - | - |
| `1:1` | Cada transação corresponde a exatamente uma contraparte |
| `1:N` | Uma transação pode corresponder a várias contrapartes |
| `N:M` | Várias transações podem corresponder entre os dois lados |

Salve o `id` da resposta. Você vai usá-lo em todas as etapas seguintes.

```json theme={null}
{
  "id": "019c96a0-2a10-7dfe-b5c1-8a1b2c3d4e5f",
  "name": "Daily Bank Reconciliation",
  "type": "1:1",
  "interval": "daily",
  "status": "DRAFT",
  "createdAt": "2026-03-04T12:00:00Z",
  "updatedAt": "2026-03-04T12:00:00Z"
}
```

> [!NOTE]
>
> O contexto começa no status DRAFT. Ele passa para ACTIVE quando você estiver pronto para rodar a conciliação.

## Etapa 2: Adicione fontes de dados

***

Para rodar uma correspondência, configure pelo menos duas fontes: os sistemas cujas transações você quer comparar.

> [!TIP]
>
> Referência da API: [Create source](https://docs.lerian.studio/pt/reference/products/matcher/create-source.md)

### Crie uma fonte de banco

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "Chase Bank - Account 1234",
   "type": "BANK",
   "side": "RIGHT"
 }'
```

### Crie uma fonte de ledger

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "name": "General Ledger - GL 1000",
   "type": "LEDGER",
   "side": "LEFT"
 }'
```

Salve os dois valores de `id` das fontes. Cada fonte precisa de um `side` (`LEFT` ou `RIGHT`): o contexto concilia as fontes `LEFT` com as fontes `RIGHT`.

### Tipos de fonte

| Tipo | Caso de uso |
| - | - |
| `BANK` | Extratos bancários |
| `LEDGER` | Ledger geral / exportações de ERP |
| `GATEWAY` | Dados de processadora de pagamento |
| `CUSTOM` | Qualquer outra fonte de dados |
| `FETCHER` | Dados extraídos pelo mecanismo de extração embutido |

## Etapa 3: Mapeie os campos de fonte

***

Seus arquivos de fonte provavelmente usam nomes de coluna diferentes dos que o Matcher espera. Os mapas de campo os traduzem para o schema padrão do Matcher.

> [!TIP]
>
> Referência da API: [Create field map](https://docs.lerian.studio/pt/reference/products/matcher/create-field-map.md)

### Mapeie a fonte de banco

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{bankSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Post Date",
     "description": "Description"
   }
 }'
```

### Mapeie a fonte de ledger

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{ledgerSourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "entry_id",
     "amount": "debit_credit_amount",
     "currency": "currency_code",
     "date": "posting_date",
     "description": "memo"
   }
 }'
```

### Campos obrigatórios

Toda transação deve ter estes campos depois do mapeamento:

| Campo | Tipo | Descrição |
| - | - | - |
| `external_id` | String | Identificador exclusivo dentro da fonte |
| `amount` | Decimal | Valor da transação |
| `currency` | String | Código de moeda ISO 4217 (por exemplo, USD) |
| `date` | Date | Data da transação (YYYY-MM-DD) |

**Opcional:** `description`, `fee_amount`, `fee_currency` e `direction`. Cada chave do mapeamento é um campo do Matcher. Cada valor é o nome da coluna no seu arquivo, exceto para `direction`. O valor dela é um objeto `{column, debit, credit}` para um arquivo que marca cada linha como débito ou crédito em uma coluna separada. Uma linha de débito é importada com valor negativo, e uma de crédito com valor positivo.

## Etapa 4: Crie regras de correspondência

***

As regras definem como o Matcher compara transações. Comece com uma regra exact, que é a mais precisa.

> [!TIP]
>
> Referência da API: [Create match rule](https://docs.lerian.studio/pt/reference/products/matcher/create-match-rule.md)

### Crie uma regra exact

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "EXACT",
   "priority": 1,
   "config": {
     "matchAmount": true,
     "matchCurrency": true,
     "matchDate": true,
     "matchReference": true,
     "caseInsensitive": true,
     "datePrecision": "DAY"
   }
 }'
```

### Adicione uma regra tolerance como fallback

Capture pequenas diferenças, como tarifas bancárias ou arredondamento:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/rules" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "type": "TOLERANCE",
   "priority": 20,
   "config": {
     "percentTolerance": 0.01,
     "absTolerance": 5.0,
     "dateWindowDays": 2,
     "matchCurrency": true,
     "matchReference": true,
     "caseInsensitive": true
   }
 }'
```

> [!TIP]
>
> O Matcher avalia as regras por prioridade (o número mais baixo primeiro). A regra exact roda primeiro. Apenas as transações não conciliadas passam para a regra tolerance.

### Tipos de regra

| Tipo | Quando usar | Faixa de prioridade |
| - | - | - |
| `EXACT` | Os valores devem corresponder exatamente | 1-1000; exclusiva dentro do contexto |
| `TOLERANCE` | Pequenas diferenças esperadas | 1-1000; exclusiva dentro do contexto |
| `DATE_LAG` | Atrasos de data entre sistemas; sempre propostas para revisão | 1-1000; exclusiva dentro do contexto |
| `FUZZY` | Referências com pontuação de similaridade; sempre propostas para revisão | 1-1000; exclusiva dentro do contexto |

## Etapa 5: Ative o contexto

***

Mova o contexto de DRAFT para ACTIVE:

> [!TIP]
>
> Referência da API: [Update context](https://docs.lerian.studio/pt/reference/products/matcher/update-context.md)

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/contexts/{contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "status": "ACTIVE"
 }'
```

Se o contexto não estiver pronto, o Matcher recusa a atualização com `409 Conflict` e o código `MTCH-0103`. O array `errors` da resposta lista cada requisito ausente. O [Progresso da configuração](https://docs.lerian.studio/pt/products/matcher/getting-started/matcher-setup-progress.md) lista os requisitos ausentes e a próxima chamada a fazer.

## Etapa 6: Envie os arquivos de transação

***

Envie um arquivo por fonte. O Matcher aceita os formatos CSV, JSON e XML por upload multipart form.

> [!TIP]
>
> * Referência da API: [Upload transaction file](https://docs.lerian.studio/pt/reference/products/matcher/upload-transaction-file.md)
> * [List ingestion jobs](https://docs.lerian.studio/pt/reference/products/matcher/list-ingestion-jobs.md)

### Envie as transações do banco

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{bankSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@bank_transactions.csv"
```

### Envie as transações do ledger

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/imports/contexts/{contextId}/sources/{ledgerSourceId}/upload" \
 -H "Authorization: Bearer $TOKEN" \
 -F "format=csv" \
 -F "file=@ledger_entries.csv"
```

Cada upload cria um job de ingestão. Verifique o status do job:

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/imports/contexts/{contextId}/jobs" \
 -H "Authorization: Bearer $TOKEN"
```

Aguarde os dois jobs atingirem o status `COMPLETED` antes de rodar a correspondência.

## Etapa 7: Rode a correspondência

***

Comece com uma execução dry run para pré-visualizar os resultados sem persistir:

> [!TIP]
>
> Referência da API: [Run match](https://docs.lerian.studio/pt/reference/products/matcher/run-match.md)

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "DRY_RUN"
 }'
```

A resposta inclui um `runId`. Um dry run não salva grupos de correspondência. Para revisar os resultados, leia as estatísticas agregadas da execução com [Get match run](https://docs.lerian.studio/pt/reference/products/matcher/retrieve-match-run.md).

Quando estiver satisfeito, rode com COMMIT para persistir as correspondências:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/contexts/{contextId}/run" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mode": "COMMIT"
 }'
```

Salve o `runId` da resposta do COMMIT. Você vai usá-lo na Etapa 8.

## Etapa 8: Revise os resultados

***

> [!TIP]
>
> * Referência da API: [List match run groups](https://docs.lerian.studio/pt/reference/products/matcher/list-match-run-groups.md)
> * [Unmatch group](https://docs.lerian.studio/pt/reference/products/matcher/unmatch-group.md)
> * [Confirm match group](https://docs.lerian.studio/pt/reference/products/matcher/confirm-match-group.md)

### Veja os grupos de correspondência

```bash cURL theme={null}
curl -X GET "https://api.matcher.example.com/v1/matching/runs/{runId}/groups?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"
```

Cada grupo de correspondência contém transações pareadas e uma pontuação de confiança (0-100):

| Pontuação | O que acontece |
| - | - |
| 90-100 | Confirmado automaticamente para correspondências EXACT e TOLERANCE. As correspondências FUZZY e DATE\_LAG precisam de revisão manual |
| 60-89 | Precisa de revisão manual |

### Confirme uma correspondência proposta

Use o endpoint confirm para aprovar um grupo de correspondência `PROPOSED`. O grupo vira `CONFIRMED` e as transações dele viram `MATCHED`. Apenas os papéis `operator` e `admin` podem confirmar.

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}/confirm?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN"
```

### Desfaça uma correspondência incorreta

Use o endpoint unmatch para rejeitar um grupo de correspondência `PROPOSED` ou revogar um `CONFIRMED`. O Matcher devolve as transações do grupo ao pool de não conciliadas para a próxima execução. Quando você rejeita um grupo `PROPOSED`, uma transação que você correspondeu à força separadamente continua `MATCHED`:

```bash cURL theme={null}
curl -X DELETE "https://api.matcher.example.com/v1/matching/groups/{matchGroupId}?contextId={contextId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "reason": "Transactions belong to different records"
 }'
```

## Etapa 9: Trate as exceções

***

Exceções são transações que o Matcher não conseguiu corresponder automaticamente. O Matcher classifica cada exceção por severidade:

> [!TIP]
>
> Referência da API: [List exceptions](https://docs.lerian.studio/pt/reference/products/matcher/list-exceptions.md)

| Severidade | Critério |
| - | - |
| `CRITICAL` | Valor >= 100.000 ou idade >= 120h |
| `HIGH` | Valor >= 10.000 ou idade >= 72h |
| `MEDIUM` | Valor >= 1.000 ou idade >= 24h |
| `LOW` | Todos os outros |

### Liste as exceções

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

Resolva exceções diretamente, aplicando correspondência forçada ou criando lançamentos de ajuste.

## Próximos passos

***

> [card] [Contextos e fontes](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-contexts-and-sources.md)
>
> Guia completo de configuração de contexto e fonte.

> [card] [Regras de correspondência](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-match-rules.md)
>
> Todos os tipos de regra e opções de configuração em detalhe.

> [card] [Pontuação de confiança](https://docs.lerian.studio/pt/products/matcher/reference/matcher-confidence-scoring.md)
>
> Como o Matcher calcula as pontuações e o que elas significam.

> [card] [Resolução de exceções](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-resolving-exceptions.md)
>
> Trate transações não conciliadas.


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