> ## 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 para conciliarlos entre fuentes.
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 llegan a Matcher por varias vías:
| Método | Caso de uso |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Carga de archivo** | Cargas manuales (CSV, JSON, XML, OFX, camt.053, CNAB, EDIs de adquirentes) |
| **Fetch por transporte** | Matcher extrae archivos de un transporte configurado (por ejemplo SFTP) y los ingesta |
| **Extracción de Discovery** | [Discovery](/es/matcher/integrations/matcher-discovery) extrae datos de conexiones de Fetcher hacia la ingesta |
| **Webhooks de agregadores** | Los [agregadores Open Finance](/es/matcher/integrations/matcher-aggregator-connections) señalan datos nuevos, que se extraen de forma asíncrona |
## 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 un formato que Matcher analiza de forma nativa — CSV, OFX, camt.053 o los layouts CNAB brasileños:
```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"
}
}
```
El objeto `config` es metadato descriptivo de forma libre — Matcher lo almacena pero no interpreta claves como `bank_name` o `statement_format`. El comportamiento de análisis lo determinan el dialecto de formato declarado y las claves de configuración fijas (política de tasa de errores, política de duplicados, `blank_external_id` y opciones de camt.053), no estas etiquetas.
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.