Pular para o conteúdo principal
Fontes externas fornecem dados de transações de sistemas fora da sua organização. Este guia cobre como conectar bancos, gateways de pagamento e outros sistemas externos ao Matcher.

​
Tipos de fontes suportados

O Matcher suporta quatro tipos de fontes. Cada um representa uma categoria de origem de dados:
TipoDescriçãoUso típico
LEDGERContas do razão geralSistemas contábeis internos
BANKExtratos bancáriosFeeds bancários externos
GATEWAYTransações de processadores de pagamentoGateways de pagamento
CUSTOMIntegrações personalizadasERPs, bandeiras de cartão ou qualquer outra fonte de dados

​
Métodos de ingestão

Dados de transação são ingeridos através de upload de arquivo:
MétodoCaso de UsoFormatos
Upload de ArquivoUploads manuais de CSV/JSON/XMLCSV, JSON, XML

​
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 arquivos para importar arquivos de transação manualmente.
Referência da API: Upload de arquivo de transação

​
Conexões bancárias

​
Formato bancário padrão

A maioria dos bancos fornece extratos em formato CSV ou MT940: 
{
  "name": "Chase Business Account",
  "type": "BANK",
  "config": {
    "bank_name": "Chase",
    "account_number": "****1234",
    "currency": "USD",
    "statement_format": "CSV",
    "timezone": "America/New_York"
  }
}

​
Formato Mt940/mt942

Para extratos bancários formatados em SWIFT: 
{
  "name": "International Bank SWIFT",
  "type": "BANK",
  "config": {
    "statement_format": "MT940",
    "swift_bic": "CHASUS33",
    "parse_options": {
      "date_format": "YYMMDD",
      "amount_decimal_indicator": ","
    }
  }
}
Referência da API: Criar fonte

​
Conexões ERP e personalizadas

Use o tipo de fonte CUSTOM para sistemas ERP (SAP, Oracle, NetSuite, etc.) e qualquer outra fonte de dados que não se encaixe nas categorias BANK, LEDGER ou GATEWAY.

​
Exemplo: fonte ERP

{
  "name": "SAP S/4HANA",
  "type": "CUSTOM",
  "config": {
    "erp_type": "SAP",
    "company_codes": ["1000", "2000"]
  }
}
Exporte os dados de transação do seu ERP e faça upload através do endpoint de upload de arquivos do Matcher. Use mapeamento de campos para traduzir os campos específicos do ERP para o formato canônico do Matcher.

​
Conexões de processadores de pagamento

​
Stripe

{
  "name": "Stripe Payments",
  "type": "GATEWAY",
  "config": {
    "provider": "stripe"
  }
}

​
Adyen

{
  "name": "Adyen Settlements",
  "type": "GATEWAY",
  "config": {
    "provider": "adyen",
    "merchant_account": "CompanyECOM"
  }
}
Exporte os relatórios de liquidação do seu processador de pagamento e faça upload através do endpoint de upload de arquivos do Matcher.

​
Bandeiras de cartão

Para arquivos de liquidação de bandeiras de cartão (Visa, Mastercard, Elo), use o tipo de fonte CUSTOM: 
{
  "name": "Visa Settlement",
  "type": "CUSTOM",
  "config": {
    "network": "VISA",
    "file_format": "TC33"
  }
}

​
Segurança de conexão

​
Armazenamento de credenciais

Todas as credenciais devem ser armazenadas de forma segura em um vault criptografado e referenciadas por ID nas configurações de fonte.

​
Lista de IPs permitidos

Configure a lista de IPs permitidos no nível de infraestrutura (balanceador de carga, API gateway ou firewall) para restringir quais IPs podem enviar dados ao Matcher. As entidades de fonte não possuem uma configuração settings.security. Gerencie restrições de IP fora da aplicação.

​
Assinaturas de webhook

O Matcher assina payloads de webhooks de saída com HMAC-SHA256. Para dados de entrada, verifique as assinaturas no nível de infraestrutura antes que os dados cheguem ao Matcher. As entidades de fonte não possuem uma configuração settings.webhook.

​
Requisitos de formato de dados

​
Campos obrigatórios

Toda transação deve incluir:
CampoTipoDescrição
transaction_idStringID único da fonte
amountDecimalValor da transação
currencyStringCódigo ISO 4217
dateDateData da transação

​
Campos recomendados

CampoTipoDescrição
referenceStringReferência de pagamento
counterpartyStringNome da contraparte
typeStringcrédito/débito
posting_dateDateData de liquidação

​
Mapeamento de campos

Use um endpoint dedicado para gerenciar mapeamentos de campo, não o objeto config da fonte. Crie mapeamentos de campos para uma fonte usando:
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 '{
   "sourceField": "trans_amount",
   "targetField": "amount"
 }'
Consulte Mapeamento de Campos para detalhes.

​
Melhores práticas

Verifique se os arquivos carregados contêm os campos obrigatórios (transaction_id, amount, currency, date) antes do upload. Isso evita erros de ingestão.
Padronize em um único formato (CSV, JSON ou XML) por fonte para simplificar o mapeamento de campos e reduzir erros.
Armazene todas as chaves de API e senhas no vault. Nunca inclua credenciais nos payloads de configuração.
Valide o mapeamento de campos e a qualidade dos dados com arquivos de amostra antes de carregar dados de produção.

​
Próximos passos

Mapeamento de Campos

Configure como os campos da fonte mapeiam para o Matcher.

Upload de Arquivos

Procedimentos de upload manual de arquivos.