> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.
# Fontes externas
> Conecte bancos, gateways de pagamento, ERPs e outros sistemas externos ao Matcher e ingira os dados de transações deles.
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 são ingeridos através de upload de arquivo:
| Método | Caso de Uso | Formatos |
| --------------------- | ------------------------------- | -------------- |
| **Upload de Arquivo** | Uploads manuais de CSV/JSON/XML | CSV, 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](/pt/reference/matcher/upload-transaction-file)
## Conexões bancárias
***
### Formato bancário padrão
A maioria dos bancos fornece extratos em formato CSV ou MT940:
```json theme={null}
{
"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:
```json theme={null}
{
"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](/pt/reference/matcher/create-source)
## 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
```json theme={null}
{
"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](/pt/matcher/configuration/matcher-field-mapping) para traduzir os campos específicos do ERP para o formato canônico do Matcher.
## Conexões de processadores de pagamento
***
### Stripe
```json theme={null}
{
"name": "Stripe Payments",
"type": "GATEWAY",
"config": {
"provider": "stripe"
}
}
```
### Adyen
```json theme={null}
{
"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`:
```json theme={null}
{
"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 }`:
```bash cURL theme={null}
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](/pt/matcher/configuration/matcher-field-mapping) para detalhes.
## Melhores práticas
***
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.
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
***
Configure como os campos da fonte mapeiam para o Matcher.
Procedimentos de upload manual de arquivos.