Mapeamento de campos

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	`transactionAmount`	`postDate`	`checkNumber`
Banco B	`amt`	`transaction_date`	`ref_num`
ERP	`AMOUNT_USD`	`GL_DATE`	`DOC_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_id`	String	Identificador único dentro da fonte	`"TXN-2024-001"`
`amount`	Decimal	Valor da transação (até 4 casas decimais)	`1234.56`
`currency`	String	Código de moeda ISO 4217	`"USD"`
`date`	Date	Data da transação (`YYYY-MM-DD`)	`"2024-01-15"`

Campos opcionais

Campo	Tipo	Descrição	Exemplo
`reference`	String	Referência externa ou descrição	`"Fatura #1234"`
`counterparty`	String	Outra parte na transação	`"Acme Corp"`
`type`	String	Direção/tipo da transação	`"credit"`, `"debit"`
`category`	String	Categoria da transação	`"payment"`, `"fee"`
`posting_date`	Date	Data de lançamento	`"2024-01-16"`
`value_date`	Date	Data de valor/liquidação	`"2024-01-17"`
`external_id`	String	Identificador do sistema externo	`"BANK-REF-999"`
`metadata`	Object	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

curl -X POST "https://api.matcher.example.com/v1/config/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"
}

Referência da API: Criar mapa de campos

Transformações de dados

Mapas de campos podem aplicar transformações para normalizar formatos e convenções antes do matching.

Transformações disponíveis

Transformação	Descrição	Exemplo
`uppercase`	Converter para maiúsculas	`"abc"` → `"ABC"`
`lowercase`	Converter para minúsculas	`"ABC"` → `"abc"`
`trim`	Remover espaços em branco	`" abc "` → `"abc"`
`parse_date`	Parsear data por formato	`"01/15/2024"` → `"2024-01-15"`
`parse_number`	Parsear número com locale	`"1,234.56"` → `1234.56`
`abs`	Valor absoluto	`-100` → `100`
`negate`	Negar número	`100` → `-100`
`multiply`	Multiplicar por fator	`100` × `0.01` → `1`
`replace`	Substituição de string	`"USD$"` → `"USD"`
`extract`	Extração com regex	Extrair números de string
`default`	Padrão se vazio	`null` → `"UNKNOWN"`
`concat`	Concatenar campos	`field1 + field2`

Exemplos de transformação

cURL

curl -X POST "https://api.matcher.example.com/v1/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 de formato de data

Padrões comuns de parse_date:

Padrão	Exemplo de entrada	Saída
`YYYY-MM-DD`	`2024-01-15`	`2024-01-15`
`MM/DD/YYYY`	`01/15/2024`	`2024-01-15`
`DD/MM/YYYY`	`15/01/2024`	`2024-01-15`
`YYYY-MM-DDTHH:mm:ssZ`	`2024-01-15T10:30:00Z`	`2024-01-15`
`MMM DD, YYYY`	`Jan 15, 2024`	`2024-01-15`
`DD-MMM-YYYY`	`15-Jan-2024`	`2024-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

Extratos bancários (csv)

Formato da 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)

Formato da fonte

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

Formato da fonte

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

Introdução

Primeiros passos

Configurações

Reconciliação diária

Casos de uso do Matcher

Integrações

Referência

Mapeamento de campos

Por que mapeamento de campos?

Schema padrão do Matcher

Campos obrigatórios

Campos opcionais

Criando mapas de campos

Mapa de campos básico

Transformações de dados

Transformações disponíveis

Exemplos de transformação

Padrões de formato de data

Campos computados

Concatenação

Mapeamento condicional

Sinal do valor baseado em tipo

Exemplos de mapeamento por tipo de fonte

Extratos bancários (csv)

Formato da fonte

Mapa de campos

Resultado

Sistemas ERP (json)

Formato da fonte

Mapa de campos

Resultado

Gateways de pagamento (xml)

Formato da fonte

Mapa de campos

Resultado

Boas práticas

Próximos passos

Regras de match

Upload de arquivos

Introdução

Primeiros passos

Configurações

Reconciliação diária

Casos de uso do Matcher

Integrações

Referência

​Por que mapeamento de campos?

​Schema padrão do Matcher

​Campos obrigatórios

​Campos opcionais

​Criando mapas de campos

​Mapa de campos básico

​Transformações de dados

​Transformações disponíveis

​Exemplos de transformação

​Padrões de formato de data

​Campos computados

​Concatenação

​Mapeamento condicional

​Sinal do valor baseado em tipo

​Exemplos de mapeamento por tipo de fonte

​Extratos bancários (csv)

​Formato da fonte

​Mapa de campos

​Resultado

​Sistemas ERP (json)

​Formato da fonte

​Mapa de campos

​Resultado

​Gateways de pagamento (xml)

​Formato da fonte

​Mapa de campos

​Resultado

​Boas práticas

​Próximos passos

Regras de match

Upload de arquivos

Por que mapeamento de campos?

Schema padrão do Matcher

Campos obrigatórios

Campos opcionais

Criando mapas de campos

Mapa de campos básico

Transformações de dados

Transformações disponíveis

Exemplos de transformação

Padrões de formato de data

Campos computados

Concatenação

Mapeamento condicional

Sinal do valor baseado em tipo

Exemplos de mapeamento por tipo de fonte

Extratos bancários (csv)

Formato da fonte

Mapa de campos

Resultado

Sistemas ERP (json)

Formato da fonte

Mapa de campos

Resultado

Gateways de pagamento (xml)

Formato da fonte

Mapa de campos

Resultado

Boas práticas

Próximos passos