Fontes externas

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 cinco tipos de fontes. Cada um representa uma categoria de origem de dados:

Tipo	Descrição	Uso típico
`LEDGER`	Razão interno	Sistemas contábeis internos (incluindo o Midaz)
`BANK`	Feed de extratos bancários	Feeds bancários externos
`GATEWAY`	Gateway de pagamento	Processadores de pagamento (Stripe, Adyen, PayPal)
`CUSTOM`	Feed sob medida	ERPs, bandeiras de cartão ou qualquer outra fonte de dados
`FETCHER`	Extração do motor de descoberta	Conexões de agregadores extraídas automaticamente

Métodos de ingestão

Dados de transação chegam ao Matcher por vários caminhos:

Método	Caso de uso
Upload de arquivo	Uploads manuais (CSV, JSON, XML, OFX, camt.053, CNAB, EDIs de adquirentes)
Fetch por transporte	O Matcher busca arquivos de um transporte configurado (por exemplo SFTP) e os ingere
Extração do Discovery	O Discovery extrai dados de conexões do Fetcher para a ingestão
Webhooks de agregadores	Os agregadores Open Finance sinalizam novos dados, extraídos de forma assíncrona

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 um formato que o Matcher analisa nativamente — CSV, OFX, camt.053 ou os layouts CNAB brasileiros:

{
  "name": "Chase Business Account",
  "type": "BANK",
  "config": {
    "bank_name": "Chase",
    "account_number": "****1234",
    "currency": "USD",
    "statement_format": "CSV",
    "timezone": "America/New_York"
  }
}

O objeto config é metadado descritivo de forma livre — o Matcher o armazena, mas não interpreta chaves como bank_name ou statement_format. O comportamento de análise é determinado pelo dialeto de formato declarado e pelas chaves de configuração fixas (política de taxa de erros, chave e política de duplicatas, blank_external_id e opções de camt.053), não por esses rótulos.

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: Os mapas de campos usam um vocabulário canônico fechado: as chaves do mapeamento são fixas e os valores nomeiam a coluna original da fonte. Estas chaves canônicas são obrigatórias:

Chave canônica	Tipo	Descrição
`external_id`	String	Identificador de transação do sistema de origem
`amount`	Decimal	Valor da transação
`currency`	String	Código ISO 4217
`date`	Date	Data da transação

Campos opcionais

Chave canônica	Tipo	Descrição
`description`	String	Texto de referência/descrição (alimenta a coluna de descrição da transação)
`fee_amount`	Decimal	Slot de taxa: coluna de origem que carrega o valor da taxa
`fee_currency`	String	Slot de taxa: coluna de origem que carrega a moeda da taxa

Nenhuma outra chave é aceita: chaves fora deste vocabulário são rejeitadas.

Mapeamento de campos

Gerencie os mapas de campos com o endpoint dedicado (não com o objeto config da fonte). O corpo da requisição é um único objeto mapping de pares { canonicalKey: sourceColumnName }:

cURL

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": {
     "external_id": "TXN_ID",
     "amount": "trans_amount",
     "currency": "CCY",
     "date": "POST_DATE",
     "description": "memo",
     "fee_amount": "mdr_fee",
     "fee_currency": "fee_ccy"
   }
 }'

Consulte Mapeamento de Campos para detalhes.

Melhores práticas

Valide os arquivos antes de enviar

Verifique se os arquivos carregados contêm colunas para os campos canônicos obrigatórios (external_id, amount, currency, date) antes do upload. Isso evita erros de ingestão.

Use formatos de arquivo consistentes

Padronize em um único formato (CSV, JSON ou XML) por fonte para simplificar o mapeamento de campos e reduzir erros.

Proteja as credenciais adequadamente

Armazene todas as chaves de API e senhas no vault. Nunca inclua credenciais nos payloads de configuração.

Teste primeiro com dados de amostra

Valide o mapeamento de campos e a qualidade dos dados com arquivos de amostra antes de carregar dados de produção.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Fontes externas

Tipos de fontes suportados

Métodos de ingestão

Ingestão baseada em arquivos

Upload manual

Conexões bancárias

Formato bancário padrão

Conexões ERP e personalizadas

Exemplo: fonte ERP

Conexões de processadores de pagamento

Stripe

Adyen

Bandeiras de cartão

Segurança de conexão

Armazenamento de credenciais

Lista de IPs permitidos

Assinaturas de webhook

Requisitos de formato de dados

Campos obrigatórios

Campos opcionais

Mapeamento de campos

Melhores práticas

Próximos passos

Mapeamento de Campos

Upload de Arquivos

​Tipos de fontes suportados

​Métodos de ingestão

​Ingestão baseada em arquivos

​Upload manual

​Conexões bancárias

​Formato bancário padrão

​Conexões ERP e personalizadas

​Exemplo: fonte ERP

​Conexões de processadores de pagamento

​Stripe

​Adyen

​Bandeiras de cartão

​Segurança de conexão

​Armazenamento de credenciais

​Lista de IPs permitidos

​Assinaturas de webhook

​Requisitos de formato de dados

​Campos obrigatórios

​Campos opcionais

​Mapeamento de campos

​Melhores práticas

​Próximos passos

Mapeamento de Campos

Upload de Arquivos

Tipos de fontes suportados

Métodos de ingestão

Ingestão baseada em arquivos

Upload manual

Conexões bancárias

Formato bancário padrão

Conexões ERP e personalizadas

Exemplo: fonte ERP

Conexões de processadores de pagamento

Stripe

Adyen

Bandeiras de cartão

Segurança de conexão

Armazenamento de credenciais

Lista de IPs permitidos

Assinaturas de webhook

Requisitos de formato de dados

Campos obrigatórios

Campos opcionais

Mapeamento de campos

Melhores práticas

Próximos passos