Skip to main content
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:
  • 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:

​
Chaves opcionais

Declare estas apenas quando a fonte as carregar:
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:
cURL
Resposta
Referência da API: Criar mapa de campo

​
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.
cURL
Referência da API: Atualizar mapa de campo
Outras operações:

​
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:
Mapa de campo:

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

Colunas brutas:
Mapa de campo:
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

Regras de correspondência

Defina como o Matcher compara e agrupa os campos canônicos.

Como enviar arquivos

Importe transações usando os seus mapas de campo.