Mapeamento de campos

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:

{ "<canonicalKey>": "<sourceColumnName>" }

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:

cURL

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

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

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.

cURL

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

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:

BankRef,BookingDate,Amount,Ccy,Narrative
BANK-001,2025-01-15,-500.00,USD,Wire to Acme Corp

Mapa de campos:

{
  "mapping": {
    "external_id": "BankRef",
    "amount": "Amount",
    "currency": "Ccy",
    "date": "BookingDate",
    "description": "Narrative"
  }
}

Fonte RIGHT — exportação de ledger (CSV)

Colunas brutas:

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:

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

Inverter a direção

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.

Usar chaves fora do vocabulário

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.

Caixa incorreta

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.

Faltar uma chave obrigatória

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

Valores vazios ou que não são strings

Cada valor deve ser uma string não vazia que nomeie uma coluna de origem. null, números, objetos ou "" são rejeitados.

Esperar transformações

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.

Mapeamento de campos

O que é um mapa de campos

Vocabulário canônico

Chaves obrigatórias

Chaves opcionais

Criando um mapa de campos

Atualizando um mapa de campos

Exemplo: ambos os lados de um contexto

Fonte LEFT — extrato bancário (CSV)

Fonte RIGHT — exportação de ledger (CSV)

Erros comuns

Próximos passos

Regras de match

Upload de arquivos

​O que é um mapa de campos

​Vocabulário canônico

​Chaves obrigatórias

​Chaves opcionais

​Criando um mapa de campos

​Atualizando um mapa de campos

​Exemplo: ambos os lados de um contexto

​Fonte LEFT — extrato bancário (CSV)

​Fonte RIGHT — exportação de ledger (CSV)

​Erros comuns

​Próximos passos

Regras de match

Upload de arquivos

O que é um mapa de campos

Vocabulário canônico

Chaves obrigatórias

Chaves opcionais

Criando um mapa de campos

Atualizando um mapa de campos

Exemplo: ambos os lados de um contexto

Fonte LEFT — extrato bancário (CSV)

Fonte RIGHT — exportação de ledger (CSV)

Erros comuns

Próximos passos