Saltar al contenido principal
Las fuentes externas proporcionan datos de transacciones desde sistemas fuera de su 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 cuatro tipos de fuente. Cada uno representa una categoría de origen de datos:
TipoDescripciónUso típico
LEDGERCuentas del libro mayorSistemas contables internos
BANKExtractos bancariosFeeds bancarios externos
GATEWAYTransacciones de procesadores de pagosPasarelas de pago
CUSTOMIntegraciones personalizadasERPs, redes de tarjetas u otra fuente de datos

​
Métodos de ingesta

Los datos de transacciones se ingestan mediante carga de archivos:
MétodoCaso de usoFormatos
Carga de archivoCargas manuales CSV/JSON/XMLCSV, JSON, XML

​
Ingesta basada en archivos

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

​
Carga manual

Use 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

Use 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"]
  }
}
Exporte los datos de transacciones desde su ERP y cárguelos a través del endpoint de carga de archivos de Matcher. Use 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"
  }
}
Exporte los reportes de liquidación desde su procesador de pagos y cárguelos 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), use 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

Configure 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. Gestione 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, verifique 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:
CampoTipoDescripción
transaction_idStringID único de la fuente
amountDecimalMonto de la transacción
currencyStringCódigo ISO 4217
dateDateFecha de la transacción

​
Campos recomendados

CampoTipoDescripción
referenceStringReferencia de pago
counterpartyStringNombre de la contraparte
typeStringcrédito/débito
posting_dateDateFecha de liquidación

​
Mapeo de campos

Use un endpoint dedicado para gestionar mapeos de campos, no el objeto config de la fuente. Cree mapeos de campos para una fuente usando:
cURL
curl -X POST "https://api.matcher.example.com/v1/config/contexts/{contextId}/sources/{sourceId}/field-maps" \
 -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
   "sourceField": "trans_amount",
   "targetField": "amount"
 }'
Consulte Mapeo de campos para más detalles.

​
Mejores prácticas

Verifique que los archivos cargados contengan los campos requeridos (transaction_id, amount, currency, date) antes de subirlos. Esto previene errores de ingesta.
Estandarice en un solo formato (CSV, JSON o XML) por fuente para simplificar el mapeo de campos y reducir errores.
Almacene todas las API keys y contraseñas en el vault. Nunca incluya credenciales en los payloads de configuración.
Valide el mapeo de campos y la calidad de datos con archivos de muestra antes de cargar datos de producción.

​
Próximos pasos

Mapeo de campos

Configure cómo los campos de origen se mapean a Matcher.

Carga de archivos

Procedimientos de carga manual de archivos.