Pular para o conteúdo principal
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:
  • 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:

​
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.
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:
cURL
Resposta
Referência da API: Criar mapa de campo

​
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.
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 rejeita chaves fora do vocabulário, 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”.
Um nome de coluna deve ser uma string não vazia. O Matcher rejeita null, números, objetos ou "" no lugar dele.
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.
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

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.