> ## 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?](/pt/products/matcher/what-is-matcher).
</Tip>

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:

* Uma instância do Matcher em execução
* 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` pela URL do seu 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](/pt/reference/products/matcher/create-context)
</Tip>

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

<Info>
  O contexto começa no status DRAFT. Ele passa para ACTIVE quando você estiver pronto para rodar a conciliação.
</Info>

## 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](/pt/reference/products/matcher/create-source)
</Tip>

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

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

Salve os dois valores de `id` das fontes.

### 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](/pt/reference/products/matcher/create-field-map)
</Tip>

### 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": {
     "Transaction ID": "transaction_id",
     "Amount": "amount",
     "Currency": "currency",
     "Post Date": "date",
     "Description": "reference"
   }
 }'
```

### 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": {
     "entry_id": "transaction_id",
     "debit_credit_amount": "amount",
     "currency_code": "currency",
     "posting_date": "date",
     "memo": "reference"
   }
 }'
```

### Campos obrigatórios

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

| Campo            | Tipo    | Descrição                                   |
| ---------------- | ------- | ------------------------------------------- |
| `transaction_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, mas recomendado:** `reference` (referência externa ou descrição).

## 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](/pt/reference/products/matcher/create-match-rule)
</Tip>

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

### 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                                           | 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](/pt/reference/products/matcher/update-context)
</Tip>

```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"
 }'
```

## 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](/pt/reference/products/matcher/upload-transaction-file)
  * [List ingestion jobs](/pt/reference/products/matcher/list-ingestion-jobs)
</Tip>

### 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 "file=@bank_transactions.csv" \
 -F "format=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 "file=@ledger_entries.csv" \
 -F "format=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](/pt/reference/products/matcher/run-match)
</Tip>

```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"
 }'
```

As duas respostas incluem um `runId`. Salve-o para a Etapa 8.

Revise os resultados do dry run. 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"
 }'
```

## Etapa 8: Revise os resultados

***

<Tip>
  * Referência da API: [List match run groups](/pt/reference/products/matcher/list-match-run-groups)
  * [Unmatch group](/pt/reference/products/matcher/unmatch-group)
</Tip>

### 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, nenhuma ação necessária  |
| 60-89        | Precisa de revisão manual                            |
| Abaixo de 60 | Nenhuma correspondência criada, torna-se uma exceção |

### Desfaça uma correspondência incorreta

Use o endpoint unmatch para rejeitar um grupo de correspondência `PROPOSED` e devolver suas transações ao pool de não conciliadas. Para um grupo `CONFIRMED`, o Matcher primeiro verifica se consegue reverter os efeitos residuais/de item em aberto dessa confirmação. Um unmatch bem-sucedido reverte esses efeitos de forma atômica, junto com a revogação do grupo e a devolução das suas transações:

```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"
 }'
```

Se a reversão do grupo confirmado remove a última contribuição ativa por trás de uma obrigação, o item em aberto se torna terminal `WITHDRAWN`: ele permanece como histórico, mas não é compensável nem é levado para outra execução. Se um lançamento ativo posterior ainda sustenta o residual, ou se uma nova obrigação ativa entraria em conflito com a restauração de um item terminal na mesma identidade, o Matcher retorna `409 Conflict` antes de alterar o grupo, as transações ou os itens em aberto. Depois de um unmatch bem-sucedido, as transações voltam ao pool de não conciliadas para a próxima execução.

## 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](/pt/reference/products/matcher/list-exceptions)
</Tip>

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

### 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 aplicando correspondência forçada, criando ajustes ou despachando para sistemas externos configurados, como JIRA, ServiceNow ou um webhook HTTP.

## Próximos passos

***

<CardGroup cols={2}>
  <Card title="Contextos e fontes" icon="database" href="/pt/products/matcher/configuration/matcher-contexts-and-sources">
    Guia completo de configuração de contexto e fonte.
  </Card>

  <Card title="Regras de correspondência" icon="scale-balanced" href="/pt/products/matcher/configuration/matcher-match-rules">
    Todos os tipos de regra e opções de configuração em detalhe.
  </Card>

  <Card title="Pontuação de confiança" icon="chart-simple" href="/pt/products/matcher/reference/matcher-confidence-scoring">
    Como o Matcher calcula as pontuações e o que elas significam.
  </Card>

  <Card title="Resolução de exceções" icon="triangle-exclamation" href="/pt/products/matcher/daily-reconciliation/matcher-resolving-exceptions">
    Trate transações não conciliadas.
  </Card>
</CardGroup>