> ## 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 de transação canônicos do Matcher usando um vocabulário de mapeamento fechado, para que cada lado de uma conciliação seja comparado de forma consistente.
Um mapa de campos informa ao Matcher qual coluna bruta de uma fonte carrega cada campo de transação canônico. Como cada fonte (extratos bancários, exportações de ledger, relatórios de gateways) nomeia suas colunas de forma diferente, o mapa de campos normaliza esses nomes de coluna em um único vocabulário fixo antes de o matching rodar.
Um mapa de campos apenas **renomeia colunas**. Ele não analisa, calcula, transforma nem combina valores. Cada campo canônico é preenchido a partir de exatamente uma coluna de origem.
## O que é um mapa de campos
***
Um mapa de campos 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 seu próprio mapa de campos. O Matcher compara os campos canônicos produzidos por ambos os mapas, então os dois lados devem resolver para o mesmo vocabulário mesmo quando seus arquivos brutos não se parecem em nada.
O mapeamento é um objeto JSON no formato:
```
{ "": "" }
```
* A **chave** é um campo canônico. As chaves vêm de um **vocabulário fechado e 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 (seja qual for o nome que seu arquivo dá à coluna) e devem ser strings não vazias.
## Vocabulário canônico
***
O espaço de chaves é fechado. Estas são as únicas chaves que o Matcher aceita.
### Chaves obrigatórias
Todo mapa de campos 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 o valor de uma taxa para o registro |
| `fee_currency` | Coluna que carrega a moeda dessa taxa |
`fee_amount` e `fee_currency` são o **slot de taxa** opcional. Quando presentes, o valor da coluna mapeada é copiado para o metadata da transação que a verificação de taxas lê, de modo que uma coluna com qualquer nome (por exemplo `mdr_fee`) pode carregar taxas de ponta a ponta sem metadata construído à mão. Omita-as e o comportamento é idêntico ao de um mapa sem slot de taxa.
## Criando um mapa de campos
***
Mapas de campos são criados **por fonte**. Envie o objeto de mapeamento para o endpoint de mapa de campos 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"
}
```
API Reference: [Create field map](/pt/reference/matcher/create-field-map)
## Atualizando um mapa de campos
***
Cada fonte tem um mapa de campos. Para alterar um mapeamento, faça `PATCH` por seu próprio ID (não o 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"
}
}'
```
API Reference: [Update field map](/pt/reference/matcher/update-field-map)
Outras operações:
| Operação | Endpoint |
| ---------------------------------------------- | ------------------------------------------------------------ |
| Obter o mapa de campos de uma fonte | `GET /v1/contexts/{contextId}/sources/{sourceId}/field-maps` |
| Listar todos os mapas de campos de um contexto | `GET /v1/contexts/{contextId}/field-maps` |
| Excluir um mapa de campos | `DELETE /v1/field-maps/{fieldMapId}` |
## Exemplo: ambos os lados de um contexto
***
Um contexto concilia um feed bancário contra uma exportação de ledger interna. Os dois arquivos usam nomes de coluna diferentes, então cada fonte declara seu próprio mapa — mas ambos resolvem para as 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 campos:
```json theme={null}
{
"mapping": {
"external_id": "BankRef",
"amount": "Amount",
"currency": "Ccy",
"date": "BookingDate",
"description": "Narrative"
}
}
```
### Fonte RIGHT — exportação de 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 campos:
```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"
}
}
```
Ambas as fontes agora expõem `external_id`, `amount`, `currency` e `date` no vocabulário canônico, de modo que as regras de match podem compará-las diretamente — mesmo que um arquivo chamasse o valor de `Amount` e o outro o chamasse de `value`.
## Erros comuns
***
A chave é o campo canônico e o valor é sua coluna — `{"external_id": "BankRef"}`, não `{"BankRef": "external_id"}`. Escrever ao contrário coloca uma chave desconhecida (`BankRef`) à esquerda e é rejeitado.
Apenas `external_id`, `amount`, `currency`, `date`, `description`, `fee_amount` e `fee_currency` são aceitas. Chaves como `transaction_id`, `reference`, `counterparty` ou `type` são rejeitadas como chaves desconhecidas, e o erro nomeia cada infratora.
As chaves são tokens em minúsculas e sensíveis a maiúsculas e minúsculas. `External_Id`, `Amount` ou `CURRENCY` são tratadas como chaves desconhecidas.
Todas as chaves `external_id`, `amount`, `currency` e `date` devem estar presentes. Um mapa ao qual falte qualquer uma delas falha na validação com uma mensagem "missing required keys".
Cada valor deve ser uma string não vazia que nomeie uma coluna de origem. `null`, números, objetos ou `""` são rejeitados.
Mapas de campos não analisam datas, dividem valores, concatenam colunas nem aplicam condicionais. Entregue os valores já no formato esperado a partir do arquivo de origem, ou normalize a montante antes do upload.
## Próximos passos
***
Defina como os campos canônicos são comparados e agrupados.
Importe transações usando seus mapas de campos.