Fuentes externas

Las fuentes externas aportan datos de transacciones de sistemas fuera de tu organización. Esta guía cubre cómo conectar bancos, gateways de pago y otros sistemas externos a Matcher.

Tipos de fuente admitidos

Matcher admite cinco tipos de fuente. Cada uno representa una categoría de origen de datos:

Tipo	Descripción	Uso típico
`LEDGER`	Ledger interno	Sistemas contables internos (incluido Midaz)
`BANK`	Flujo de extractos bancarios	Flujos bancarios externos
`GATEWAY`	Gateway de pago	Procesadores de pago (Stripe, Adyen, PayPal)
`CUSTOM`	Flujo a medida	ERP, redes de tarjetas o cualquier otra fuente de datos
`FETCHER`	Obtención por el motor de Discovery	Conexiones con agregadores traídas de forma automática

Métodos de ingesta

Los datos de transacciones llegan a Matcher por varias rutas:

Método	Caso de uso
Subida de archivos	Subidas manuales (CSV, JSON, XML, OFX, camt.053, CNAB, EDI de adquirentes)
Obtención por transporte	Matcher trae archivos de un transporte configurado (por ejemplo SFTP) y los ingiere
Extracción por Discovery	Discovery extrae datos de las conexiones descubiertas hacia la ingesta
Webhooks de agregadores	Los agregadores de Open Finance señalan datos nuevos, que se traen de forma asíncrona

Ingesta basada en archivos

El método más común para extractos bancarios y exportaciones de ERP.

Subida manual

Usa el endpoint de subida de archivos para importar archivos de transacciones a mano.

Referencia de API: Subir un archivo de transacciones

Conexiones bancarias

Formato bancario estándar

La mayoría de los bancos entregan extractos en un formato que Matcher parsea de forma nativa (CSV, OFX, camt.053 o los layouts brasileños CNAB):

{
  "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 dialecto de formato declarado y las claves de configuración fijadas determinan el comportamiento del parseo, no estas etiquetas. Esas claves son la política de tasa de errores, la clave y la política de duplicados, blank_external_id y las opciones de camt.053.

Referencia de API: Crear una fuente

Conexiones con ERP y personalizadas

Usa el tipo de fuente CUSTOM para sistemas ERP (SAP, Oracle, NetSuite, etc.) y cualquier otra fuente de datos que no encaje en las categorías BANK, LEDGER o GATEWAY.

Ejemplo: fuente de ERP

{
  "name": "SAP S/4HANA",
  "type": "CUSTOM",
  "config": {
    "erp_type": "SAP",
    "company_codes": ["1000", "2000"]
  }
}

Exporta los datos de transacciones de tu ERP y súbelos por el endpoint de subida de archivos de Matcher. Usa el mapeo de campos para traducir los campos específicos del ERP al formato canónico de Matcher.

Conexiones con procesadores de pago

Stripe

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

Adyen

{
  "name": "Adyen Settlements",
  "type": "GATEWAY",
  "config": {
    "provider": "adyen",
    "merchant_account": "CompanyECOM"
  }
}

Exporta los informes de liquidación de tu procesador de pago y súbelos por el endpoint de subida de archivos de Matcher.

Redes de tarjetas

Para los 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 las conexiones

Almacenamiento de credenciales

Guarda todas las credenciales de forma segura en un vault cifrado. Referéncialas por ID en las configuraciones de fuente.

Lista de IP permitidas

Configura la lista de IP permitidas en el nivel de la infraestructura (balanceador de carga, API gateway o firewall) para restringir qué IP pueden enviar datos a Matcher. Las entidades de fuente no tienen una configuración settings.security. Administra las restricciones de IP fuera de la aplicación.

Firmas de webhook

Matcher firma los payloads de webhook salientes con HMAC-SHA256. Para los datos entrantes, verifica las firmas en el nivel de la 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 obligatorios

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 en crudo de la fuente. Estas claves canónicas son obligatorias:

Clave canónica	Tipo	Descripción
`external_id`	String	Identificador de la transacción en el 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 o descripción (alimenta la columna de descripción de la transacción)
`fee_amount`	Decimal	Espacio de comisión: columna de origen que lleva el monto de la comisión
`fee_currency`	String	Espacio de comisión: columna de origen que lleva la moneda de la comisión

No se aceptan otras claves.

Mapeo de campos

Administra 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 subidos contengan columnas para los campos canónicos obligatorios (external_id, amount, currency, date) antes de subirlos. Esto evita errores de ingesta.

Usa formatos de archivo consistentes

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

Protege bien las credenciales

Guarda todas las claves de API 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 los datos con archivos de muestra antes de subir datos de producción.

Resumen

Guías

Matcher UI

Servidor MCP

Operaciones

Fuentes externas

Tipos de fuente admitidos

Métodos de ingesta

Ingesta basada en archivos

Subida manual

Conexiones bancarias

Formato bancario estándar

Conexiones con ERP y personalizadas

Ejemplo: fuente de ERP

Conexiones con procesadores de pago

Stripe

Adyen

Redes de tarjetas

Seguridad de las conexiones

Almacenamiento de credenciales

Lista de IP permitidas

Firmas de webhook

Requisitos de formato de datos

Campos obligatorios

Campos opcionales

Mapeo de campos

Mejores prácticas

Próximos pasos

Mapeo de campos

Subida de archivos

​Tipos de fuente admitidos

​Métodos de ingesta

​Ingesta basada en archivos

​Subida manual

​Conexiones bancarias

​Formato bancario estándar

​Conexiones con ERP y personalizadas

​Ejemplo: fuente de ERP

​Conexiones con procesadores de pago

​Stripe

​Adyen

​Redes de tarjetas

​Seguridad de las conexiones

​Almacenamiento de credenciales

​Lista de IP permitidas

​Firmas de webhook

​Requisitos de formato de datos

​Campos obligatorios

​Campos opcionales

​Mapeo de campos

​Mejores prácticas

​Próximos pasos

Mapeo de campos

Subida de archivos

Tipos de fuente admitidos

Métodos de ingesta

Ingesta basada en archivos

Subida manual

Conexiones bancarias

Formato bancario estándar

Conexiones con ERP y personalizadas

Ejemplo: fuente de ERP

Conexiones con procesadores de pago

Stripe

Adyen

Redes de tarjetas

Seguridad de las conexiones

Almacenamiento de credenciales

Lista de IP permitidas

Firmas de webhook

Requisitos de formato de datos

Campos obligatorios

Campos opcionales

Mapeo de campos

Mejores prácticas

Próximos pasos