Tipos de fonte com suporte
O Matcher oferece suporte a cinco tipos de fonte. Cada um representa uma categoria de origem de dados:
Métodos de ingestão
Os dados de transações chegam ao Matcher por vários caminhos:
Ingestão baseada em arquivos
O método mais comum para extratos bancários e exportações de ERP.
Upload manual
Use o endpoint de upload de arquivo para importar arquivos de transações manualmente.Conexões bancárias
Formato bancário padrão
A maioria dos bancos fornece extratos em um formato que o Matcher interpreta nativamente (CSV, OFX, camt.053 ou os layouts CNAB brasileiros):O objeto
config é metadado descritivo de forma livre. O Matcher o armazena, mas não interpreta chaves como bank_name ou statement_format. Em vez disso, o Matcher age sobre estas chaves reservadas quando você as define: dialect, fail_on_error_rate_percent, duplicate_policy, duplicate_key, blank_external_id, camt053, connection_id e connection_config_name.Conexões de ERP e customizadas
Use o tipo de fonte
CUSTOM para sistemas de ERP (SAP, Oracle, NetSuite etc.) e para qualquer outra fonte de dados que não se encaixe nas categorias BANK, LEDGER ou GATEWAY.
Exemplo: fonte de ERP
Conexões com processadores de pagamento
Stripe
Adyen
Bandeiras de cartão
Para arquivos de liquidação de bandeira de cartão (Visa, Mastercard, Elo), use o tipo de fonteCUSTOM:
Segurança da conexão
Assinaturas de webhook
O Matcher verifica os webhooks de entrada dos agregadores com uma assinatura HMAC-SHA256 ou uma allowlist de IPs de origem, como descreve Conexões de agregador. As entidades de fonte não têm uma configuraçãosettings.webhook.
Requisitos de formato dos dados
Campos obrigatórios
Os mapas de campo usam um vocabulário canônico fechado: as chaves do mapeamento são fixas, e os valores nomeiam a coluna bruta da fonte. Estas chaves canônicas são obrigatórias:Campos opcionais
O Matcher não aceita nenhuma outra chave.
Use
direction quando um arquivo marca cada linha como débito ou crédito em uma coluna separada. column nomeia essa coluna, e debit e credit são os valores que ela contém. O Matcher importa uma linha de débito com valor negativo e uma linha de crédito com valor positivo. Quando você mapeia direction, as células de valor não podem ter sinal. Um valor com sinal, uma célula de direção vazia ou um valor de direção desconhecido rejeita a linha. O Matcher aplica direction apenas a entradas CSV, JSON e XML.
Mapeamento de campos
Gerencie os mapas de campo pelo endpoint dedicado (não pelo objetoconfig da fonte). O corpo da requisição é um único objeto mapping com pares { canonicalKey: sourceColumnName }:
cURL
Boas práticas
Valide os arquivos antes de enviar
Valide os arquivos antes de enviar
Confira se os arquivos enviados têm colunas para os campos canônicos obrigatórios (external_id, amount, currency, date) antes do envio. Isso evita erros de ingestão.
Use formatos de arquivo consistentes
Use formatos de arquivo consistentes
Padronize um único formato (CSV, JSON ou XML) por fonte para simplificar o mapeamento de campos e reduzir erros.
Proteja as credenciais de forma adequada
Proteja as credenciais de forma adequada
Nunca inclua credenciais nos payloads de configuração.
Teste primeiro com dados de exemplo
Teste primeiro com dados de exemplo
Valide o mapeamento de campos e a qualidade dos dados com arquivos de exemplo antes de enviar dados de produção.
Próximos passos
Mapeamento de campos
Configure como os campos da fonte se mapeiam para o Matcher.
Envio de arquivos
Procedimentos de upload manual de arquivos.