Fuentes externas

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

Conexiones bancarias

Formato bancario estándar

La mayoría de los bancos proporcionan extractos en formato CSV o MT940:

{
  "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:

{
  "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

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

{
  "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 para traducir los campos específicos del ERP al formato canónico de Matcher.

Conexiones de procesadores de pagos

Stripe

{
  "name": "Stripe Payments",
  "type": "GATEWAY",
  "config": {
    "provider": "stripe"
  }
}

Adyen

{
  "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:

{
  "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 }:

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"
   }
 }'

Consulta Mapeo de campos para más detalles.

Mejores prácticas

Valida los archivos antes de subirlos

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.

Usa formatos de archivo consistentes

Estandariza en un solo formato (CSV, JSON o XML) por fuente para simplificar el mapeo de campos y reducir errores.

Protege las credenciales adecuadamente

Almacena todas las API keys y contraseñas en el vault. Nunca incluyas credenciales en los payloads de configuración.

Prueba primero con datos de muestra

Valida el mapeo de campos y la calidad de datos con archivos de muestra antes de cargar datos de producción.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Fuentes externas

Tipos de fuentes soportadas

Métodos de ingesta

Ingesta basada en archivos

Carga manual

Conexiones bancarias

Formato bancario estándar

Formato MT940/MT942

Conexiones ERP y personalizadas

Ejemplo: fuente ERP

Conexiones de procesadores de pagos

Stripe

Adyen

Redes de tarjetas

Seguridad de conexión

Almacenamiento de credenciales

Lista blanca de IPs

Firmas de webhook

Requisitos de formato de datos

Campos requeridos

Campos opcionales

Mapeo de campos

Mejores prácticas

Próximos pasos

Mapeo de campos

Carga de archivos

​Tipos de fuentes soportadas

​Métodos de ingesta

​Ingesta basada en archivos

​Carga manual

​Conexiones bancarias

​Formato bancario estándar

​Formato MT940/MT942

​Conexiones ERP y personalizadas

​Ejemplo: fuente ERP

​Conexiones de procesadores de pagos

​Stripe

​Adyen

​Redes de tarjetas

​Seguridad de conexión

​Almacenamiento de credenciales

​Lista blanca de IPs

​Firmas de webhook

​Requisitos de formato de datos

​Campos requeridos

​Campos opcionales

​Mapeo de campos

​Mejores prácticas

​Próximos pasos

Mapeo de campos

Carga de archivos

Tipos de fuentes soportadas

Métodos de ingesta

Ingesta basada en archivos

Carga manual

Conexiones bancarias

Formato bancario estándar

Formato MT940/MT942

Conexiones ERP y personalizadas

Ejemplo: fuente ERP

Conexiones de procesadores de pagos

Stripe

Adyen

Redes de tarjetas

Seguridad de conexión

Almacenamiento de credenciales

Lista blanca de IPs

Firmas de webhook

Requisitos de formato de datos

Campos requeridos

Campos opcionales

Mapeo de campos

Mejores prácticas

Próximos pasos