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.
O mapeamento de campos converte dados de transações específicos da fonte para o schema canônico do Matcher.
Esta normalização é necessária para comparar transações entre sistemas e aplicar regras de matching de forma consistente.
Por que mapeamento de campos? Sistemas externos raramente compartilham os mesmos nomes de campos, formatos ou convenções de sinal. Por exemplo:
Sistema Campo de valor Campo de data Campo de referência Banco A transactionAmountpostDatecheckNumberBanco B amttransaction_dateref_numERP AMOUNT_USDGL_DATEDOC_NUM
Mapas de campos padronizam essas variações em um único schema que o Matcher pode validar, normalizar e conciliar.
Schema padrão do Matcher Campos obrigatórios Toda transação deve fornecer estes campos após o mapeamento:
Campo Tipo Descrição Exemplo transaction_idString Identificador único dentro da fonte "TXN-2024-001"amountDecimal Valor da transação (até 4 casas decimais) 1234.56currencyString Código de moeda ISO 4217 "USD"dateDate Data da transação (YYYY-MM-DD) "2024-01-15"
Campos opcionais Campo Tipo Descrição Exemplo referenceString Referência externa ou descrição "Fatura #1234"counterpartyString Outra parte na transação "Acme Corp"typeString Direção/tipo da transação "credit", "debit"categoryString Categoria da transação "payment", "fee"posting_dateDate Data de lançamento "2024-01-16"value_dateDate Data de valor/liquidação "2024-01-17"external_idString Identificador do sistema externo "BANK-REF-999"metadataObject Campos específicos da fonte {"department": "sales"}
Criando mapas de campos Mapa de campos básico Mapas de campos são criados para uma fonte específica dentro de um contexto. O objeto mapping define como os campos da fonte mapeiam para o schema do Matcher.
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": { "Transaction ID": "transaction_id", "Amount": "amount", "Currency": "currency", "Post Date": "date", "Description": "reference" } }'
Response { "id" : "550e8400-e29b-41d4-a716-446655440000" , "contextId" : "969a11cd-6b7d-4e71-b82b-0828e0603149" , "sourceId" : "a1b2c3d4-e5f6-7890-abcd-ef1234567890" , "mapping" : { "Transaction ID" : "transaction_id" , "Amount" : "amount" , "Currency" : "currency" , "Post Date" : "date" , "Description" : "reference" }, "version" : 1 , "createdAt" : "2024-01-15T10:00:00Z" , "updatedAt" : "2024-01-15T10:00:00Z" }
Mapas de campos podem aplicar transformações para normalizar formatos e convenções antes do matching.
Transformação Descrição Exemplo uppercaseConverter para maiúsculas "abc" → "ABC"lowercaseConverter para minúsculas "ABC" → "abc"trimRemover espaços em branco " abc " → "abc"parse_dateParsear data por formato "01/15/2024" → "2024-01-15"parse_numberParsear número com locale "1,234.56" → 1234.56absValor absoluto -100 → 100negateNegar número 100 → -100multiplyMultiplicar por fator 100 × 0.01 → 1replaceSubstituição de string "USD$" → "USD"extractExtração com regex Extrair números de string defaultPadrão se vazio null → "UNKNOWN"concatConcatenar campos field1 + field2
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 '{ "name": "Formato Banco Legado com Transformações", "source_type": "csv", "mappings": [ { "source_field": "TXN_NUM", "target_field": "transaction_id", "transformations": [ { "type": "trim" }, { "type": "uppercase" } ] }, { "source_field": "AMOUNT", "target_field": "amount", "transformations": [ { "type": "parse_number", "options": { "locale": "en-US" } }, { "type": "multiply", "options": { "factor": 0.01 } } ] }, { "source_field": "TXN_DATE", "target_field": "date", "transformations": [ { "type": "parse_date", "options": { "format": "MM/DD/YYYY" } } ] }, { "source_field": "CURR", "target_field": "currency", "transformations": [ { "type": "replace", "options": { "search": "$", "replace": "" } }, { "type": "uppercase" }, { "type": "default", "options": { "value": "USD" } } ] } ] }'
Response { "id" : "fmap_002" , "name" : "Formato Banco Legado com Transformações" , "mappings" : [ { "source_field" : "TXN_NUM" , "target_field" : "transaction_id" , "transformations" : [ { "type" : "trim" }, { "type" : "uppercase" } ] }, { "source_field" : "AMOUNT" , "target_field" : "amount" , "transformations" : [ { "type" : "parse_number" , "options" : { "locale" : "en-US" } }, { "type" : "multiply" , "options" : { "factor" : 0.01 } } ] }, { "source_field" : "TXN_DATE" , "target_field" : "date" , "transformations" : [ { "type" : "parse_date" , "options" : { "format" : "MM/DD/YYYY" } } ] }, { "source_field" : "CURR" , "target_field" : "currency" , "transformations" : [ { "type" : "replace" , "options" : { "search" : "$" , "replace" : "" } }, { "type" : "uppercase" }, { "type" : "default" , "options" : { "value" : "USD" } } ] } ] }
Padrões comuns de parse_date:
Padrão Exemplo de entrada Saída YYYY-MM-DD2024-01-152024-01-15MM/DD/YYYY01/15/20242024-01-15DD/MM/YYYY15/01/20242024-01-15YYYY-MM-DDTHH:mm:ssZ2024-01-15T10:30:00Z2024-01-15MMM DD, YYYYJan 15, 20242024-01-15DD-MMM-YYYY15-Jan-20242024-01-15
Campos computados Use campos computados quando valores devem ser derivados em vez de copiados de um único campo da fonte.
Concatenação { "target_field" : "reference" , "computed" : true , "expression" : { "type" : "concat" , "fields" : [ "DOC_TYPE" , "DOC_NUM" ], "separator" : "-" } }
Entrada: DOC_TYPE: "INV", DOC_NUM: "12345"
Saída: reference: "INV-12345"Mapeamento condicional { "target_field" : "type" , "computed" : true , "expression" : { "type" : "conditional" , "conditions" : [ { "if" : { "field" : "DR_CR" , "equals" : "D" }, "then" : "debit" }, { "if" : { "field" : "DR_CR" , "equals" : "C" }, "then" : "credit" } ], "default" : "unknown" } }
Sinal do valor baseado em tipo { "target_field" : "amount" , "computed" : true , "expression" : { "type" : "conditional" , "conditions" : [ { "if" : { "field" : "TXN_TYPE" , "equals" : "DEBIT" }, "then" : { "type" : "negate" , "field" : "AMOUNT" } } ], "default" : { "field" : "AMOUNT" } } }
Exemplos de mapeamento por tipo de fonte Transaction ID, Post Date, Description, Amount, Balance CHK001, 01/15/2024, Check #1234, -500.00, 10500.00 DEP001, 01/15/2024, Mobile Deposit, 1500.00, 12000.00 FEE001, 01/15/2024, Monthly Service Fee, -12.00, 11988.00
Mapa de campos { "name" : "CSV de Extrato Bancário" , "source_type" : "csv" , "mappings" : [ { "source_field" : "Transaction ID" , "target_field" : "transaction_id" }, { "source_field" : "Post Date" , "target_field" : "date" , "transformations" : [ { "type" : "parse_date" , "options" : { "format" : "MM/DD/YYYY" } } ] }, { "source_field" : "Description" , "target_field" : "reference" }, { "source_field" : "Amount" , "target_field" : "amount" , "transformations" : [ { "type" : "parse_number" , "options" : { "locale" : "en-US" } } ] }, { "target_field" : "currency" , "computed" : true , "expression" : { "type" : "constant" , "value" : "USD" } }, { "target_field" : "type" , "computed" : true , "expression" : { "type" : "conditional" , "conditions" : [ { "if" : { "field" : "Amount" , "less_than" : 0 }, "then" : "debit" } ], "default" : "credit" } } ] }
Resultado [ { "transaction_id" : "CHK001" , "date" : "2024-01-15" , "reference" : "Check #1234" , "amount" : -500.0 , "currency" : "USD" , "type" : "debit" }, { "transaction_id" : "DEP001" , "date" : "2024-01-15" , "reference" : "Mobile Deposit" , "amount" : 1500.0 , "currency" : "USD" , "type" : "credit" } ]
Sistemas ERP (json) { "entries" : [ { "DOC_ID" : "JE-2024-001" , "GL_DATE" : "2024-01-15" , "GL_ACCOUNT" : "1000" , "AMOUNT_USD" : 150000 , "DR_CR" : "D" , "DESCRIPTION" : "Vendor Payment - Acme Corp" } ] }
Mapa de campos { "name" : "Formato de Lançamento ERP" , "source_type" : "json" , "root_path" : "entries" , "mappings" : [ { "source_field" : "DOC_ID" , "target_field" : "transaction_id" }, { "source_field" : "GL_DATE" , "target_field" : "date" }, { "source_field" : "AMOUNT_USD" , "target_field" : "amount" , "transformations" : [ { "type" : "multiply" , "options" : { "factor" : 0.01 } } ] }, { "target_field" : "currency" , "computed" : true , "expression" : { "type" : "constant" , "value" : "USD" } }, { "source_field" : "DESCRIPTION" , "target_field" : "reference" }, { "target_field" : "type" , "computed" : true , "expression" : { "type" : "conditional" , "conditions" : [ { "if" : { "field" : "DR_CR" , "equals" : "D" }, "then" : "debit" }, { "if" : { "field" : "DR_CR" , "equals" : "C" }, "then" : "credit" } ] } }, { "source_field" : "GL_ACCOUNT" , "target_field" : "metadata.gl_account" } ] }
Resultado { "transaction_id" : "JE-2024-001" , "date" : "2024-01-15" , "amount" : 1500.0 , "currency" : "USD" , "reference" : "Vendor Payment - Acme Corp" , "type" : "debit" , "metadata" : { "gl_account" : "1000" } }
Gateways de pagamento (xml) < transactions > < transaction > < id > PAY-2024-001 </ id > < timestamp > 2024-01-15T14:30:00Z </ timestamp > < amount currency = "USD" > 99.99 </ amount > < merchant > Store #123 </ merchant > < status > completed </ status > </ transaction > </ transactions >
Mapa de campos { "name" : "Formato XML Gateway de Pagamento" , "source_type" : "xml" , "root_path" : "transactions/transaction" , "mappings" : [ { "source_field" : "id" , "target_field" : "transaction_id" }, { "source_field" : "timestamp" , "target_field" : "date" , "transformations" : [ { "type" : "parse_date" , "options" : { "format" : "ISO8601" } } ] }, { "source_field" : "amount" , "target_field" : "amount" , "transformations" : [ { "type" : "parse_number" } ] }, { "source_field" : "amount@currency" , "target_field" : "currency" }, { "source_field" : "merchant" , "target_field" : "reference" }, { "target_field" : "type" , "computed" : true , "expression" : { "type" : "constant" , "value" : "credit" } } ] }
Resultado { "transaction_id" : "PAY-2024-001" , "date" : "2024-01-15" , "amount" : 99.99 , "currency" : "USD" , "reference" : "Store #123" , "type" : "credit" }
Boas práticas
Nomeie mapas de campos como versões
Torne mudanças de formato explícitas (por exemplo, CSV Banco v2.0) para preservar reimportação e auditabilidade.
Explique transformações não óbvias
Adicione descrições para transformações que mudam a semântica (por exemplo, “Valor em centavos, dividir por 100”).
Defina valores padrão para campos opcionais intencionalmente
Use default apenas para campos opcionais e escolha valores que tornem o comportamento downstream explícito.
Normalize convenções de sinal
Padronize débitos e créditos entre fontes antes do matching.
Versione em vez de editar no lugar
Quando formatos da fonte mudam, crie um novo mapa de campos em vez de modificar um existente.
Próximos passos
Regras de match Defina como transações são comparadas e agrupadas.
Upload de arquivos Importe transações usando seus mapas de campos.
