> ## 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 como Stripe e Adyen, ERPs como SAP ou Oracle e bandeiras de cartão ao Matcher pelos tipos LEDGER, BANK, GATEWAY ou CUSTOM.

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 | Dados que o [Discovery](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-discovery.md) extrai de uma conexão |

## 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](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-discovery.md) extrai dados das conexões descobertas para a ingestão |
| **Webhooks de agregador** | Os [agregadores de Open Finance](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-aggregator-connections.md) 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.

> [!TIP]
>
> Referência da API: [Enviar arquivo de transações](https://docs.lerian.studio/pt/reference/products/matcher/upload-transaction-file.md)

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

```json theme={null}
{
  "name": "Chase Business Account",
  "type": "BANK",
  "side": "RIGHT",
  "config": {
    "bank_name": "Chase",
    "account_number": "****1234",
    "currency": "USD",
    "statement_format": "CSV",
    "timezone": "America/New_York"
  }
}
```

> [!NOTE]
>
> 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`.

> [!TIP]
>
> Referência da API: [Criar fonte](https://docs.lerian.studio/pt/reference/products/matcher/create-source.md)

## 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

```json theme={null}
{
  "name": "SAP S/4HANA",
  "type": "CUSTOM",
  "side": "LEFT",
  "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](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-field-mapping.md) para traduzir os campos específicos do ERP para o formato canônico do Matcher.

## Conexões com processadores de pagamento

***

### Stripe

```json theme={null}
{
  "name": "Stripe Payments",
  "type": "GATEWAY",
  "side": "RIGHT",
  "config": {
    "provider": "stripe"
  }
}
```

### Adyen

```json theme={null}
{
  "name": "Adyen Settlements",
  "type": "GATEWAY",
  "side": "RIGHT",
  "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. Para Stripe, PagBank e Pix BCB, o Matcher também pode extrair os dados por uma [conexão REST](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-discovery.md#create-a-rest-connection).

### Bandeiras de cartão

Para arquivos de liquidação de bandeira de cartão (Visa, Mastercard, Elo), use o tipo de fonte `CUSTOM`:

```json theme={null}
{
  "name": "Visa Settlement",
  "type": "CUSTOM",
  "side": "RIGHT",
  "config": {
    "network": "VISA"
  }
}
```

## 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](https://docs.lerian.studio/pt/products/matcher/integrations/matcher-aggregator-connections.md). As entidades de fonte não têm uma configuração `settings.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:

| 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 |
| `direction` | Object | Indicador de débito ou crédito: `{column, debit, credit}` |

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 objeto `config` da fonte). O corpo da requisição é um único objeto `mapping` com 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"
   }
 }'
```

Veja o [Mapeamento de campos](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-field-mapping.md) para detalhes.

## Boas práticas

***

> [accordion] 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.

> [accordion] Use formatos de arquivo consistentes
>
> Padronize um único formato (CSV, JSON ou XML) por fonte para simplificar o mapeamento de campos e reduzir erros.

> [accordion] Proteja as credenciais de forma adequada
>
> Nunca inclua credenciais nos payloads de configuração.

> [accordion] 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

***

> [card] [Mapeamento de campos](https://docs.lerian.studio/pt/products/matcher/configuration/matcher-field-mapping.md)
>
> Configure como os campos da fonte se mapeiam para o Matcher.

> [card] [Envio de arquivos](https://docs.lerian.studio/pt/products/matcher/daily-reconciliation/matcher-uploading-files.md)
>
> Procedimentos de upload manual de arquivos.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.