Integrar no significa juntar columnas
Cuando un club recibe datos de Catapult, STATSports, WIMU y hojas propias, la dificultad no suele ser abrir los archivos. El reto es determinar si dos campos significan lo mismo, a qué jugador y sesión pertenecen, con qué permisos se obtuvieron y qué versión debe conservarse.
Una tabla con una fila por jugador puede ocultar diferencias importantes. Dos proveedores pueden usar nombres parecidos para métricas calculadas con umbrales, filtros o algoritmos distintos. Incluso dentro de la misma plataforma, una exportación de sesión completa y otra por tareas pueden producir niveles de agregación diferentes. La integración empieza por documentar estas diferencias, no por forzar equivalencias.
La arquitectura debe admitir tres realidades: algunas cuentas tienen acceso a una API; otras trabajan con exportaciones desde la interfaz; y determinados datos requieren módulos, licencias o autorización del proveedor. La documentación oficial confirma opciones concretas, pero no permite afirmar que estén habilitadas para todos los clientes.
Qué está documentado por cada proveedor
Catapult OpenField
Catapult documenta la creación de informes y su exportación mediante CSV, API o Catapult Connect. La documentación permite confirmar que existen esos mecanismos, pero la combinación disponible depende del producto y de la configuración de cada cuenta.
Catapult documenta además tokens para Catapult Connect API. La propia guía indica que el módulo “API Token Admin” debe estar habilitado en la cuenta y que puede requerir contactar con soporte. Por tanto, la existencia de una API no equivale a acceso automático para cualquier organización. Un diseño responsable contempla exportación por archivo como alternativa hasta confirmar contrato, módulo, alcance y límites.
STATSports Sonra
La documentación de STATSports describe exportaciones configurables, incluido CSV. En ese formato es relevante decidir si se incluyen tareas individuales o totales por participante, porque esa opción cambia la granularidad de las filas.
STATSports también documenta una función de API de terceros dentro de Sonra. La selección de integraciones disponibles se realiza desde la interfaz y, si un tercero no aparece, la indicación oficial es consultar al account manager. De nuevo, no debe suponerse que una integración concreta está disponible para todas las cuentas. El flujo debe verificar qué edición, configuración y permisos existen realmente.
WIMU dentro del ecosistema Hudl
Hudl presenta actualmente Signal como su plataforma de monitorización de rendimiento. Las notas de versión de WIMU documentan acceso a una API REST para determinados roles de cuenta, cambios de permisos a lo largo del tiempo, integraciones con Hudl Sportscode y la transición de marca de WIMU Cloud hacia Hudl Signal. Esa documentación no garantiza que la API esté habilitada para cualquier cliente: antes de diseñar el conector hay que confirmar contrato, producto, rol y permisos con Hudl.
Esto obliga a confirmar producto, versión, rol y entorno antes de diseñar la extracción. Una referencia histórica a WIMU Cloud puede convivir con interfaces y nombres actuales distintos. La integración no debería depender de una URL o etiqueta de menú sin validarla en la cuenta concreta.
Archivos CSV y Excel internos
Los archivos propios pueden contener información que ningún proveedor conoce: tipo de microciclo, disponibilidad, observaciones, convocatoria o equivalencias internas. No son una fuente menor, pero necesitan contrato de datos: columnas obligatorias, formato de fecha, unidades, valores permitidos y responsable de cada campo.
Un archivo enviado por correo con columnas variables no es todavía una interfaz estable. Puede funcionar como entrada si se valida y se rechaza de forma comprensible cuando cambia.
Separar extracción y normalización
Una integración mantenible utiliza dos capas. La primera habla el idioma de cada fuente y conserva el dato original. La segunda traduce ese dato a un modelo común.
| Capa | Responsabilidad | Qué no debería hacer |
|---|---|---|
| Conector de origen | Autenticarse, descargar, registrar versión y conservar respuesta | Decidir que dos métricas de proveedores distintos son equivalentes |
| Normalización | Mapear jugadores, sesiones, unidades y nombres internos | Ocultar campos desconocidos o inventar valores faltantes |
| Reglas de negocio | Agregar, comparar y preparar indicadores | Modificar el dato original |
| Presentación | Crear tablas, gráficos e informes | Recalcular silenciosamente definiciones |
Este diseño permite sustituir una exportación manual por una API sin rehacer todos los informes. También permite reprocesar históricos si cambia una regla, porque la entrada original sigue disponible.
El diccionario de métricas
Antes de unir datos conviene crear un diccionario con una fila por métrica de origen. Como mínimo debería registrar:
- proveedor y producto;
- nombre exacto en la exportación;
- descripción disponible;
- unidad;
- nivel de agregación;
- umbral o zona del que depende;
- valor absoluto o relativo;
- frecuencia o periodo;
- nombre interno propuesto;
- estado de la equivalencia: confirmada, parcial o no comparable.
Por ejemplo, dos columnas llamadas “High Speed Running” no deben fusionarse sólo por el nombre. Pueden depender de umbrales absolutos, porcentajes individuales, bandas distintas o criterios de inclusión diferentes. Si no puede demostrarse la equivalencia, es mejor conservarlas como métricas separadas y mostrar su origen.
Identificar jugadores sin depender del nombre
Los nombres cambian de formato, contienen tildes, pueden repetirse y a veces se sustituyen por dorsales. La integración necesita un identificador interno estable y una tabla de correspondencias por proveedor.
| Identificador interno | Catapult | STATSports | WIMU | Archivo interno |
|---|---|---|---|---|
player_0042 | ID de atleta confirmado | ID de jugador confirmado | ID de jugador confirmado | Código de plantilla |
La correspondencia inicial debe revisarla una persona con conocimiento de la plantilla. Las coincidencias automáticas por nombre pueden proponer candidatos, pero no deberían unir perfiles de forma irreversible. También debe existir un estado para jugadores pendientes de mapear; descartarlos silenciosamente produce informes incompletos.
Cuando un jugador cambia de equipo, vuelve de cesión o aparece en selecciones y clubes con perfiles distintos, el modelo debe conservar el historial de sus identificadores externos sin mezclar permisos entre organizaciones.
Fechas, sesiones y tareas
Una fecha aislada no identifica una sesión. Puede haber doble sesión, datos en directo y postentrenamiento, tareas internas o correcciones posteriores. Es más seguro construir una clave con proveedor, identificador de sesión, fecha y hora con zona, equipo y versión.
Las tareas también requieren tratamiento explícito. Una exportación puede incluir una fila para la sesión completa y varias para ejercicios. Sumarlas todas duplicaría carga. El modelo normalizado debería distinguir niveles como sesión, periodo y tarea, y las consultas deben elegir uno de ellos.
Las zonas horarias merecen atención especial cuando la plataforma almacena UTC y la exportación muestra hora local. El cambio de día puede afectar al microciclo y a las agregaciones semanales.
Unidades y precisión
Todas las conversiones deben ser explícitas. Distancia puede llegar en metros, kilómetros o yardas; velocidad en metros por segundo o kilómetros por hora; duración como segundos, minutos o texto. La unidad original y la normalizada deberían quedar registradas.
También conviene evitar redondear demasiado pronto. El sistema puede conservar la precisión de origen y aplicar redondeo sólo al presentar. Si una plataforma ya entrega una métrica calculada, no debe presentarse como si el integrador hubiera reproducido su algoritmo.
Deduplicación y versiones
El mismo dato puede llegar por API y CSV, o un archivo puede volver a exportarse tras corregir tareas. Una política práctica distingue entre duplicado exacto, nueva versión de la misma sesión y dato potencialmente conflictivo.
- Un duplicado exacto puede ignorarse conservando el registro de recepción.
- Una versión posterior puede marcar la anterior como sustituida.
- Un conflicto entre fuentes debe quedar pendiente de revisión.
- Una sesión eliminada en origen no debería borrar automáticamente el histórico sin una regla acordada.
La prioridad de fuentes también debe definirse. No siempre la API es “más verdadera” que el archivo; puede contener otra granularidad o haberse consultado antes de una corrección.
Permisos y seguridad
Las credenciales de API deben tratarse como secretos, con el alcance mínimo y un token distinto por integración cuando el proveedor lo permita. Catapult recomienda expresamente tratar el token como una contraseña, no enviarlo por correo y limitarlo mediante scopes.
Además del acceso técnico, hay que confirmar autorización organizativa. Los datos de deportistas pueden incluir información personal y, según el contenido, categorías especialmente sensibles. La integración debe limitar quién puede ver, exportar y combinar datos, registrar accesos relevantes y definir conservación y borrado.
Una prueba no necesita datos reales de toda la plantilla. Puede utilizar un conjunto sintético que reproduzca columnas y casos límite sin exponer información privada de clubes o jugadores.
Estrategia de implantación
Una secuencia segura puede ser:
- Inventariar cuentas, formatos, roles y permisos realmente disponibles.
- Seleccionar una sesión representativa de cada fuente y conservar la exportación original.
- Crear el diccionario de métricas y la tabla de jugadores.
- Normalizar primero identificadores, fechas y unidades.
- Comparar totales contra las plataformas de origen.
- Añadir deduplicación y control de versiones.
- Ejecutar varias semanas en paralelo con el proceso actual.
- Automatizar la extracción sólo cuando el modelo sea estable.
El CSV puede ser una primera fase válida. La comparación entre CSV, API y webhook ayuda a elegir el mecanismo por frecuencia, fiabilidad y coste, no por prestigio técnico.
Qué debe quedar documentado
La integración está preparada cuando otra persona puede responder de dónde salió cada valor, con qué permisos se obtuvo, qué transformación recibió y qué hacer si cambia el proveedor. Como mínimo deben existir:
- inventario de fuentes y responsables;
- matriz de permisos;
- diccionario de métricas;
- correspondencias de jugadores;
- reglas de sesiones y tareas;
- conversiones de unidades;
- política de versiones y duplicados;
- controles de calidad;
- procedimiento para rotar credenciales;
- plan de recuperación si falla una extracción.
El resultado no es una “base única” que borra las diferencias. Es una capa común que conserva el contexto necesario para comparar con prudencia. Esa distinción permite combinar datos sin atribuir a un proveedor capacidades no confirmadas ni convertir métricas parecidas en equivalencias falsas.