Fontes externas

As 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 fonte com suporte

O Matcher oferece suporte a cinco tipos de fonte. Cada um representa uma categoria de origem de dados:

Tipo	Descrição	Uso típico
`LEDGER`	Ledger interno	Sistemas contábeis internos (incluindo o Midaz)
`BANK`	Feed de extrato bancário	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 agregador puxadas automaticamente

Métodos de ingestão

Os dados de transações chegam ao Matcher por vários caminhos:

Método	Caso de uso
Upload de arquivo	Envios manuais (CSV, JSON, XML, OFX, camt.053, CNAB, EDIs de adquirente)
Busca por transporte	O Matcher puxa arquivos de um transporte configurado (por exemplo, SFTP) e os ingere
Extração pelo Discovery	O Discovery extrai dados das conexões descobertas para a ingestão
Webhooks de agregador	Os agregadores de Open Finance sinalizam dados novos, puxados 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 arquivo para importar arquivos de transações manualmente.

Referência da API: Enviar arquivo de transações

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):

{
  "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 dialeto de formato declarado e as chaves de configuração fixadas comandam o comportamento do parse, não esses rótulos. Essas chaves são a política de taxa de erro, a chave e a política de duplicados, blank_external_id e as opções de camt.053.

Referência da API: Criar fonte

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

{
  "name": "SAP S/4HANA",
  "type": "CUSTOM",
  "config": {
    "erp_type": "SAP",
    "company_codes": ["1000", "2000"]
  }
}

Exporte os dados de transações do seu ERP e envie pelo endpoint de upload de arquivo do Matcher. Use o mapeamento de campos para traduzir os campos específicos do ERP para o formato canônico do Matcher.

Conexões com 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 envie-os pelo endpoint de upload de arquivo do Matcher.

Bandeiras de cartão

Para arquivos de liquidação de bandeira 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 da conexão

Armazenamento de credenciais

Guarde todas as credenciais com segurança em um vault criptografado. Referencie-as por ID nas configurações de fonte.

Lista de IPs permitidos

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

Assinaturas de webhook

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

Requisitos de formato dos dados

Campos obrigatórios

Cada transação deve incluir: 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:

Chave canônica	Tipo	Descrição
`external_id`	String	Identificador da transação no 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 tarifa: coluna da fonte que carrega o valor da tarifa
`fee_currency`	String	Slot de tarifa: coluna da fonte que carrega a moeda da tarifa

Nenhuma outra chave é aceita.

Mapeamento de campos

Gerencie os mapas de campo pelo endpoint dedicado (não pelo objeto config da fonte). O corpo da requisição é um único objeto mapping com 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"
   }
 }'

Veja o Mapeamento de campos para detalhes.

Boas práticas

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

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

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

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.

Visão geral

Guias

Matcher UI

Servidor MCP

Operações

Fontes externas

Tipos de fonte com suporte

Métodos de ingestão

Ingestão baseada em arquivos

Upload manual

Conexões bancárias

Formato bancário padrão

Conexões de ERP e customizadas

Exemplo: fonte de ERP

Conexões com processadores de pagamento

Stripe

Adyen

Bandeiras de cartão

Segurança da conexão

Armazenamento de credenciais

Lista de IPs permitidos

Assinaturas de webhook

Requisitos de formato dos dados

Campos obrigatórios

Campos opcionais

Mapeamento de campos

Boas práticas

Próximos passos

Mapeamento de campos

Envio de arquivos

​Tipos de fonte com suporte

​Métodos de ingestão

​Ingestão baseada em arquivos

​Upload manual

​Conexões bancárias

​Formato bancário padrão

​Conexões de ERP e customizadas

​Exemplo: fonte de ERP

​Conexões com processadores de pagamento

​Stripe

​Adyen

​Bandeiras de cartão

​Segurança da conexão

​Armazenamento de credenciais

​Lista de IPs permitidos

​Assinaturas de webhook

​Requisitos de formato dos dados

​Campos obrigatórios

​Campos opcionais

​Mapeamento de campos

​Boas práticas

​Próximos passos

Mapeamento de campos

Envio de arquivos

Tipos de fonte com suporte

Métodos de ingestão

Ingestão baseada em arquivos

Upload manual

Conexões bancárias

Formato bancário padrão

Conexões de ERP e customizadas

Exemplo: fonte de ERP

Conexões com processadores de pagamento

Stripe

Adyen

Bandeiras de cartão

Segurança da conexão

Armazenamento de credenciais

Lista de IPs permitidos

Assinaturas de webhook

Requisitos de formato dos dados

Campos obrigatórios

Campos opcionais

Mapeamento de campos

Boas práticas

Próximos passos