> ## 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.
# Fuentes externas
> Conecta bancos, pasarelas de pago, ERPs y otros sistemas externos a Matcher e ingiere sus datos de transacciones.
Las fuentes externas proporcionan datos de transacciones desde sistemas fuera de tu organización. Esta guía cubre cómo conectar bancos, pasarelas de pago y otros sistemas externos a Matcher.
## Tipos de fuentes soportadas
***
Matcher soporta cinco tipos de fuente. Cada uno representa una categoría de origen de datos:
| Tipo | Descripción | Uso típico |
| --------- | -------------------------------------- | --------------------------------------------------- |
| `LEDGER` | Libro mayor interno | Sistemas contables internos (incluido Midaz) |
| `BANK` | Feed de extractos bancarios | Feeds bancarios externos |
| `GATEWAY` | Pasarela de pago | Procesadores de pago (Stripe, Adyen, PayPal) |
| `CUSTOM` | Feed a medida | ERPs, redes de tarjetas u otra fuente de datos |
| `FETCHER` | Extracción del motor de descubrimiento | Conexiones de agregadores extraídas automáticamente |
## Métodos de ingesta
***
Los datos de transacciones se ingestan mediante carga de archivos:
| Método | Caso de uso | Formatos |
| -------------------- | ---------------------------- | -------------- |
| **Carga de archivo** | Cargas manuales CSV/JSON/XML | CSV, JSON, XML |
## Ingesta basada en archivos
***
El método más común para extractos bancarios y exportaciones de ERP.
### Carga manual
Usa el endpoint de carga de archivos para importar archivos de transacciones manualmente.
Referencia de API: [Cargar archivo de transacciones](/es/reference/matcher/upload-transaction-file)
## Conexiones bancarias
***
### Formato bancario estándar
La mayoría de los bancos proporcionan extractos en formato CSV o 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 extractos bancarios con formato 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": ","
}
}
}
```
Referencia de API: [Crear fuente](/es/reference/matcher/create-source)
## Conexiones ERP y personalizadas
***
Usa el tipo de fuente `CUSTOM` para sistemas ERP (SAP, Oracle, NetSuite, etc.) y cualquier otra fuente de datos que no se ajuste a las categorías `BANK`, `LEDGER` o `GATEWAY`.
### Ejemplo: fuente ERP
```json theme={null}
{
"name": "SAP S/4HANA",
"type": "CUSTOM",
"config": {
"erp_type": "SAP",
"company_codes": ["1000", "2000"]
}
}
```
Exporta los datos de transacciones desde tu ERP y cárgalos a través del endpoint de carga de archivos de Matcher. Usa [mapeo de campos](/es/matcher/configuration/matcher-field-mapping) para traducir los campos específicos del ERP al formato canónico de Matcher.
## Conexiones de procesadores de pagos
***
### 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"
}
}
```
Exporta los reportes de liquidación desde tu procesador de pagos y cárgalos a través del endpoint de carga de archivos de Matcher.
### Redes de tarjetas
Para archivos de liquidación de redes de tarjetas (Visa, Mastercard, Elo), usa el tipo de fuente `CUSTOM`:
```json theme={null}
{
"name": "Visa Settlement",
"type": "CUSTOM",
"config": {
"network": "VISA",
"file_format": "TC33"
}
}
```
## Seguridad de conexión
***
### Almacenamiento de credenciales
Todas las credenciales deben almacenarse de forma segura en un vault encriptado y referenciarse por ID en las configuraciones de fuente.
### Lista blanca de IPs
Configura la lista blanca de IPs a nivel de infraestructura (balanceador de carga, API gateway o firewall) para restringir qué IPs pueden enviar datos a Matcher. Las entidades de fuente no tienen una configuración `settings.security`. Gestiona las restricciones de IP fuera de la aplicación.
### Firmas de webhook
Matcher firma los payloads de webhooks salientes con HMAC-SHA256. Para datos entrantes, verifica las firmas a nivel de infraestructura antes de que los datos lleguen a Matcher. Las entidades de fuente no tienen una configuración `settings.webhook`.
## Requisitos de formato de datos
***
### Campos requeridos
Cada transacción debe incluir:
Los mapas de campos usan un vocabulario canónico **cerrado**: las *claves* del mapeo son fijas y los *valores* nombran la columna original de la fuente. Estas claves canónicas son requeridas:
| Clave canónica | Tipo | Descripción |
| -------------- | ------- | -------------------------------------------------- |
| `external_id` | String | Identificador de transacción del sistema de origen |
| `amount` | Decimal | Monto de la transacción |
| `currency` | String | Código ISO 4217 |
| `date` | Date | Fecha de la transacción |
### Campos opcionales
| Clave canónica | Tipo | Descripción |
| -------------- | ------- | -------------------------------------------------------------------------------------- |
| `description` | String | Texto de referencia/descripción (alimenta la columna de descripción de la transacción) |
| `fee_amount` | Decimal | Ranura de tarifa: columna de origen que contiene el monto de la tarifa |
| `fee_currency` | String | Ranura de tarifa: columna de origen que contiene la moneda de la tarifa |
No se aceptan otras claves: las claves fuera de este vocabulario se rechazan.
### Mapeo de campos
Gestiona los mapas de campos con el endpoint dedicado (no con el objeto `config` de la fuente). El cuerpo de la solicitud es un ú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"
}
}'
```
Consulta [Mapeo de campos](/es/matcher/configuration/matcher-field-mapping) para más detalles.
## Mejores prácticas
***
Verifica que los archivos cargados contengan columnas para los campos canónicos requeridos (external\_id, amount, currency, date) antes de subirlos. Esto previene errores de ingesta.
Estandariza en un solo formato (CSV, JSON o XML) por fuente para simplificar el mapeo de campos y reducir errores.
Almacena todas las API keys y contraseñas en el vault. Nunca incluyas credenciales en los payloads de configuración.
Valida el mapeo de campos y la calidad de datos con archivos de muestra antes de cargar datos de producción.
## Próximos pasos
***
Configura cómo los campos de origen se mapean a Matcher.
Procedimientos de carga manual de archivos.