> ## 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
> Renomeie as colunas brutas de cada fonte para os campos canônicos do Matcher: external_id, amount, currency, date, mais os slots opcionais de descrição e de tarifa 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.
Um mapa de campo apenas **renomeia colunas**. Ele não faz parsing, não calcula, não transforma nem combina valores. Exatamente uma coluna da fonte preenche cada campo canônico.
## 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}
{
"": ""
}
```
* 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. Os valores são texto livre (o nome que o seu arquivo dá à coluna) e devem ser strings não vazias.
## 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 único 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 |
`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.
## Como criar um mapa de campo
***
Você cria um mapa de campo **por fonte**. 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"
}
```
Referência da API: [Criar mapa de campo](/pt/reference/products/matcher/create-field-map)
## Como atualizar um mapa de campo
***
Cada fonte tem 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"
}
}'
```
Referência da API: [Atualizar mapa de campo](/pt/reference/products/matcher/update-field-map)
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
***
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.
O Matcher aceita apenas `external_id`, `amount`, `currency`, `date`, `description`, `fee_amount` e `fee_currency`. O Matcher rejeita chaves como `transaction_id`, `reference`, `counterparty` ou `type` como chaves desconhecidas. O erro nomeia cada infratora.
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.
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".
Cada valor deve ser uma string não vazia que nomeia uma coluna da fonte. O Matcher rejeita `null`, números, objetos ou `""`.
Os mapas de campo não fazem parsing de datas, não dividem valores, não concatenam colunas nem aplicam condicionais. Entregue os valores já no formato esperado a partir do arquivo de origem, ou normalize upstream antes do upload.
## Próximos passos
***
Defina como o Matcher compara e agrupa os campos canônicos.
Importe transações usando os seus mapas de campo.