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

<Tip>
  **Este guia é destinado a desenvolvedores.** Se você está procurando uma visão geral de nível de negócio sobre o que o Matcher faz e como ele ajuda sua equipe, veja [O que é o Matcher?](/pt/matcher/what-is-matcher).
</Tip>

Coloque o Matcher em funcionamento em minutos. Este guia percorre o caminho completo, desde a criação do primeiro contexto de conciliação até a revisão de transações correspondidas.

## Antes de começar

***

Você vai precisar de:

* Uma instância do Matcher em execução
* Um token JWT válido para autenticação
* Dois arquivos de transações 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.

## Passo 1: Criar um contexto de conciliação

***

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

<Tip>
  Referência da API: [Criar contexto](/pt/reference/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 as transações são pareadas:

| Tipo  | Descrição                                                   |
| ----- | ----------------------------------------------------------- |
| `1:1` | Cada transação corresponde a exatamente uma contrapartida   |
| `1:N` | Uma transação pode corresponder a múltiplas contrapartidas  |
| `N:M` | Múltiplas transações podem corresponder entre os dois lados |

Salve o `id` da resposta. Você vai usá-lo em todos os passos 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 inicia com status DRAFT. Ele muda para ACTIVE quando você estiver pronto para executar a conciliação.
</Info>

## Passo 2: Adicionar fontes de dados

***

Todo contexto precisa de pelo menos duas fontes: os sistemas cujas transações você quer comparar.

<Tip>
  Referência da API: [Criar fonte](/pt/reference/matcher/create-source)
</Tip>

### Criar fonte bancária

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

### Criar 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 valores de `id` de ambas as fontes.

### Tipos de fonte

| Tipo      | Caso de uso                         |
| --------- | ----------------------------------- |
| `BANK`    | Extratos bancários                  |
| `LEDGER`  | Livro razão / exportações de ERP    |
| `GATEWAY` | Dados de processadores de pagamento |
| `CUSTOM`  | Qualquer outra fonte de dados       |

## Passo 3: Mapear campos das fontes

***

Seus arquivos de origem provavelmente usam nomes de coluna diferentes dos que o Matcher espera. Mapas de campos traduzem esses nomes para o schema padrão do Matcher.

<Tip>
  Referência da API: [Criar mapa de campos](/pt/reference/matcher/create-field-map)
</Tip>

### Mapear a fonte bancária

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

### Mapear 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 após o mapeamento:

| Campo            | Tipo    | Descrição                           |
| ---------------- | ------- | ----------------------------------- |
| `transaction_id` | String  | Identificador único dentro da fonte |
| `amount`         | Decimal | Valor da transação                  |
| `currency`       | String  | Código ISO 4217 (ex.: BRL, USD)     |
| `date`           | Date    | Data da transação (YYYY-MM-DD)      |

**Opcional, mas recomendado:** `reference` (referência externa ou descrição).

## Passo 4: Criar regras de match

***

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

<Tip>
  Referência da API: [Criar regra de match](/pt/reference/matcher/create-match-rule)
</Tip>

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

### Adicionar regra tolerance como fallback

Captura pequenas diferenças como taxas 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 regras por prioridade (menor número primeiro). A regra exact roda primeiro. Apenas transações sem match caem para a regra tolerance.
</Tip>

### Tipos de regra

| Tipo        | Quando usar                        | Faixa de prioridade |
| ----------- | ---------------------------------- | ------------------- |
| `EXACT`     | Valores devem coincidir exatamente | 1-10                |
| `TOLERANCE` | Pequenas diferenças esperadas      | 11-50               |
| `DATE_LAG`  | Atrasos de data entre sistemas     | 51-100              |

## Passo 5: Ativar o contexto

***

Mova o contexto de DRAFT para ACTIVE:

<Tip>
  Referência da API: [Atualizar contexto](/pt/reference/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"
 }'
```

## Passo 6: Fazer upload dos arquivos de transações

***

Faça upload de um arquivo por fonte. O Matcher aceita formatos CSV, JSON e XML via upload multipart.

<Tip>
  * Referência da API: [Upload de arquivo de transações](/pt/reference/matcher/upload-transaction-file)
  * [Listar jobs de ingestão](/pt/reference/matcher/list-ingestion-jobs)
</Tip>

### Upload de transações bancárias

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

### Upload de 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 ambos os jobs alcançarem o status `COMPLETED` antes de executar o matching.

## Passo 7: Executar o matching

***

Comece com um dry run para visualizar resultados sem persistir:

<Tip>
  Referência da API: [Executar match](/pt/reference/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"
 }'
```

Ambas as respostas incluem um `runId`. Salve-o para o Passo 8.

Revise os resultados do dry run. Quando estiver satisfeito, execute com COMMIT para persistir os matches:

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

## Passo 8: Revisar resultados

***

<Tip>
  * Referência da API: [Listar grupos de match](/pt/reference/matcher/list-match-run-groups)
  * [Desfazer match](/pt/reference/matcher/unmatch-group)
</Tip>

### Visualizar grupos de match

```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 match contém transações pareadas e uma pontuação de confiança (0-100):

| Pontuação    | O que acontece                           |
| ------------ | ---------------------------------------- |
| 90-100       | Auto-confirmado, nenhuma ação necessária |
| 60-89        | Necessita revisão manual                 |
| Abaixo de 60 | Nenhum match criado, torna-se exceção    |

### Desfazer um match incorreto

Use o endpoint de unmatch para rejeitar um grupo de match e devolver as transações ao pool de não correspondidas:

```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": "Transações pertencem a registros diferentes"
 }'
```

As transações retornam ao pool de não correspondidas para a próxima execução.

## Passo 9: Tratar exceções

***

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

<Tip>
  Referência da API: [Listar exceções](/pt/reference/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`      | Todas as outras                   | 7 dias   |

### Listar exceções

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

Resolva exceções forçando um match, criando ajustes ou despachando para sistemas externos como JIRA.

## Próximos passos

***

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

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

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

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