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

# Mapeamento de campos

> Mapeie as colunas brutas de cada fonte para os campos canônicos do Matcher: external_id, amount, currency, date, mais campos opcionais por fonte.

Um mapa de campo diz ao Matcher qual coluna bruta de uma fonte carrega cada campo canônico da transação. Cada fonte nomeia as colunas dela de um jeito: extratos bancários, exportações de ledger, relatórios de gateway. O mapa de campo normaliza esses nomes de coluna em um vocabulário fixo antes de a correspondência rodar.

## O que é um mapa de campo

***

Um mapa de campo pertence a uma única **fonte** dentro de um **contexto**. Um contexto concilia dois lados (uma fonte `LEFT` e uma fonte `RIGHT`), e cada fonte tem o mapa de campo dela. O Matcher compara os campos canônicos produzidos pelos dois mapas. Os dois lados devem chegar ao mesmo vocabulário, mesmo quando os arquivos brutos deles não se parecem em nada.

O mapeamento é um objeto JSON no formato:

```JSON theme={null}
  { 
    "<canonicalKey>": "<sourceColumnName>"
  }
```

* A **chave** é um campo canônico. As chaves vêm de um **vocabulário fechado, sensível a maiúsculas e minúsculas**. O Matcher rejeita qualquer chave fora dele.
* O **valor** é o nome da coluna na fonte bruta que carrega esse campo.

## Vocabulário canônico

***

O Matcher usa um espaço de chaves fechado. Estas são as únicas chaves que o Matcher aceita.

### Chaves obrigatórias

Cada mapa de campo deve declarar as quatro:

| Chave | Descrição |
| - | - |
| `external_id` | Identificador do registro dentro da fonte |
| `amount` | Valor da transação |
| `currency` | Código de moeda ISO 4217 |
| `date` | Data da transação |

### Chaves opcionais

Declare estas apenas quando a fonte as carregar:

| Chave | Descrição |
| - | - |
| `description` | Rótulo de texto livre copiado para a coluna de descrição da transação |
| `fee_amount` | Coluna que carrega um valor de tarifa do registro |
| `fee_currency` | Coluna que carrega a moeda dessa tarifa |
| `direction` | Objeto que nomeia uma coluna de débito ou crédito (veja abaixo) |

> [!NOTE]
>
> `fee_amount` e `fee_currency` são o **slot de tarifa** opcional. Quando presentes, o valor da coluna mapeada é copiado para os metadados da transação que a verificação de tarifa lê. Uma coluna com qualquer nome, por exemplo `mdr_fee`, pode assim carregar tarifas de ponta a ponta sem metadados montados na mão. Omita-as e o comportamento é idêntico ao de um mapa sem slot de tarifa.

> [!NOTE]
>
> `direction` serve para um arquivo que marca cada linha como débito ou crédito em uma coluna própria. O valor dela é um objeto com três strings não vazias, por exemplo `{"column": "DC", "debit": "D", "credit": "C"}`. `column` nomeia essa coluna, e `debit` e `credit` são os dois valores que ela contém. O Matcher compara esses valores sem diferenciar maiúsculas de minúsculas, e eles devem ser diferentes. Uma linha de débito é importada com valor negativo, e uma linha de crédito com valor positivo. A coluna de valor deve então conter valores sem sinal. O Matcher rejeita uma linha com valor com sinal, ou com uma célula de direção vazia ou que não contém nenhum dos dois valores. `direction` se aplica apenas a uploads CSV, JSON e XML.

## Como criar um mapa de campo

***

Você cria um mapa de campo **por fonte**. Um segundo mapa de campo para a mesma fonte é recusado com `409`. Atualize o mapa existente. Envie o objeto de mapeamento ao endpoint de mapa de campo da fonte:

```bash cURL theme={null}
curl -X POST "https://api.matcher.example.com/v1/contexts/{contextId}/sources/{sourceId}/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": "Memo"
   }
 }'
```

**Resposta**

```json theme={null}
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "contextId": "969a11cd-6b7d-4e71-b82b-0828e0603149",
  "sourceId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "mapping": {
    "external_id": "Transaction ID",
    "amount": "Amount",
    "currency": "Currency",
    "date": "Post Date",
    "description": "Memo"
  },
  "version": 1,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-15T10:00:00Z"
}
```

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

## Como atualizar um mapa de campo

***

Para mudar um mapeamento, faça `PATCH` pelo ID do próprio mapa (não pelo ID da fonte). Envie o mapeamento completo. Ele substitui o anterior e incrementa `version`.

```bash cURL theme={null}
curl -X PATCH "https://api.matcher.example.com/v1/field-maps/{fieldMapId}" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "mapping": {
     "external_id": "Transaction ID",
     "amount": "Amount",
     "currency": "Currency",
     "date": "Value Date",
     "description": "Memo",
     "fee_amount": "Fee",
     "fee_currency": "Fee Currency"
   }
 }'
```

> [!TIP]
>
> Referência da API: [Atualizar mapa de campo](https://docs.lerian.studio/pt/reference/products/matcher/update-field-map.md)

Outras operações:

| Operação | Endpoint |
| - | - |
| Obter o mapa de campo de uma fonte | `GET /v1/contexts/{contextId}/sources/{sourceId}/field-maps` |
| Listar cada mapa de campo de um contexto | `GET /v1/contexts/{contextId}/field-maps` |
| Excluir um mapa de campo | `DELETE /v1/field-maps/{fieldMapId}` |

## Exemplo: os dois lados de um contexto

***

Um contexto concilia um feed bancário contra uma exportação interna do ledger. Os dois arquivos usam nomes de coluna diferentes, então cada fonte declara o mapa dela, mas os dois chegam às mesmas chaves canônicas.

### Fonte LEFT: extrato bancário (CSV)

Colunas brutas:

```csv theme={null}
BankRef,BookingDate,Amount,Ccy,Narrative
BANK-001,2025-01-15,-500.00,USD,Wire to Acme Corp
```

Mapa de campo:

```json theme={null}
{
  "mapping": {
    "external_id": "BankRef",
    "amount": "Amount",
    "currency": "Ccy",
    "date": "BookingDate",
    "description": "Narrative"
  }
}
```

### Fonte RIGHT: exportação do ledger (CSV)

Colunas brutas:

```csv theme={null}
entry_id,posted_at,value,asset,memo,mdr_fee,fee_ccy
LDG-9931,2025-01-15,-500.00,USD,Payment Acme Corp,2.50,USD
```

Mapa de campo:

```json theme={null}
{
  "mapping": {
    "external_id": "entry_id",
    "amount": "value",
    "currency": "asset",
    "date": "posted_at",
    "description": "memo",
    "fee_amount": "mdr_fee",
    "fee_currency": "fee_ccy"
  }
}
```

As duas fontes agora expõem `external_id`, `amount`, `currency` e `date` no vocabulário canônico. As regras de correspondência podem compará-las diretamente, mesmo que um arquivo tenha chamado o valor de `Amount` e o outro o tenha chamado de `value`.

## Erros comuns

***

> [accordion] Inverter a direção
>
> A chave é o campo canônico e o valor é a sua coluna: `{"external_id": "BankRef"}`, não `{"BankRef": "external_id"}`. Escrever ao contrário coloca uma chave desconhecida (`BankRef`) à esquerda, e o Matcher rejeita o mapa.

> [accordion] Usar chaves fora do vocabulário
>
> O Matcher rejeita chaves fora do vocabulário, como `transaction_id`, `reference`, `counterparty` ou `type`, como chaves desconhecidas. O erro nomeia cada infratora.

> [accordion] Caixa errada
>
> As chaves são tokens em minúsculas e sensíveis a maiúsculas e minúsculas. O Matcher trata `External_Id`, `Amount` ou `CURRENCY` como chaves desconhecidas.

> [accordion] Faltar uma chave obrigatória
>
> Todas as chaves `external_id`, `amount`, `currency` e `date` devem estar presentes. Um mapa sem alguma delas falha na validação com a mensagem "missing required keys".

> [accordion] Nomes de coluna vazios ou que não são string
>
> Um nome de coluna deve ser uma string não vazia. O Matcher rejeita `null`, números, objetos ou `""` no lugar dele.

> [accordion] Deixar de fora um campo da chave de duplicidade
>
> O `config` de uma fonte pode declarar `duplicate_key`, a lista ordenada de campos que identificam uma linha duplicada. A chave padrão é apenas `external_id`. O mapa de campo deve mapear cada campo que `duplicate_key` nomeia. O Matcher rejeita um mapa de campo que deixa algum deles de fora.

> [accordion] Esperar transformações
>
> Os mapas de campo não fazem parsing de datas, não dividem valores nem concatenam colunas. Entregue os valores já no formato esperado a partir do arquivo de origem, ou normalize upstream antes do upload.

## Próximos passos

***

> [card] [Regras de correspondência](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-match-rules.md)
>
> Defina como o Matcher compara e agrupa os campos canônicos.

> [card] [Como enviar arquivos](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-uploading-files.md)
>
> Importe transações usando os seus mapas de campo.


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