@qualitrain/sdk

SDK para dar acceso a las capacitaciones de QualiTrain desde sistemas externos, por rol de usuario. El sistema externo mete a sus usuarios con un botón "Ver capacitación"; QualiTrain mantiene el control de quién vio qué, progreso y puntaje (visible en el panel admin de QualiTrain).

Envuelve la API de integración que QualiTrain ya expone (/launch, /v1/sessions). Soporta dos modos de identidad:

• Backchannel (recomendado) — tu backend pide un ticket; el company_token nunca sale del servidor.
• Enlace directo — el company_token viaja en la URL; más simple, menos seguro.

Instalación

npm install @qualitrain/sdk

Sin dependencias en runtime. react es una peerDependency opcional (solo si usas el subpath @qualitrain/sdk/react). Requiere fetch global (Node 18+).

Datos que te da QualiTrain

• company_token de tu empresa (desde Admin → Proyecto → Integración)
• Los roles (rol) definidos para tu empresa

Guarda el company_token como variable de entorno, nunca en el frontend.

appUrl y apiBaseUrl ya apuntan por defecto a la instancia alojada de QualiTrain, así que no hace falta configurarlas. Solo se pasan si tienes una instancia propia:

• URL del frontend (appUrl), p. ej. https://qualitrain.tuempresa.com
• URL de la API (apiBaseUrl), p. ej. https://qualitrain.tuempresa.com/api

Receta 1 — Backend (backchannel seguro)

import { QualiTrainClient } from "@qualitrain/sdk/server";

const client = new QualiTrainClient({
  companyToken: process.env.QUALITRAIN_COMPANY_TOKEN!,
  // apiBaseUrl / appUrl solo si usas una instancia propia
});

// En tu endpoint "abrir capacitación":
const { launchUrl, destination } = await client.createSession({
  externalUserId: user.id,
  rol: user.role,          // rol tal como está configurado en QualiTrain
  name: user.fullName,
  email: user.email,
  // opcionales:
  // moduleRef: "clientes",
  // courseRef: "COURSE_ID",   // abrir una capacitación puntual
  // attrs: { area: "Litigios" },
});

res.redirect(launchUrl);   // el usuario queda logueado en QualiTrain

Receta 2 — React (botón "Ver capacitación")

Configura el token una sola vez en la raíz de tu app con el provider; después cada botón solo necesita rol + externalUserId (+ opcional name, moduleRef):

// app root (una vez)
import { QualiTrainProvider } from "@qualitrain/sdk/react";

<QualiTrainProvider
  config={{ companyToken: process.env.NEXT_PUBLIC_QT_COMPANY_TOKEN! }}
>
  {children}
</QualiTrainProvider>

// en cualquier módulo (solo cambia moduleRef)
import { QualiTrainButton } from "@qualitrain/sdk/react";

<QualiTrainButton rol={user.role} externalUserId={user.id} name={user.name} moduleRef="clientes">
  Ver capacitación
</QualiTrainButton>

⚠️ Este modo (directo) expone el company_token en el navegador. Para máxima seguridad, pásale al botón una launchUrl obtenida del backchannel: <QualiTrainButton launchUrl={launchUrl}>…</QualiTrainButton>.

El componente no impone estilos: pásale tu className. target por defecto _blank.

Receta 3 — Enlace directo (cualquier stack, sin React)

import { buildLaunchUrl } from "@qualitrain/sdk";

const url = buildLaunchUrl("https://qualitrain.tuempresa.com", {
  companyToken: COMPANY_TOKEN,
  rol: "abogado",
  externalUserId: "USER_123",
  name: "Juan Pérez",
});
// <a href={url}>Ver capacitación</a>

Seguridad

• Preferí el backchannel en producción: el company_token se queda en tu servidor.
• El modo directo expone el company_token en la URL: úsalo solo para pruebas o enlaces internos. Si se filtra, regeneralo desde el panel de QualiTrain.
• El company_token es secreto: mantenelo en variables de entorno del backend.

API

| Export | Subpath | Descripción | | --- | --- | --- | | buildLaunchUrl(appUrl, params) | . | URL de launch directo (token en la URL). | | buildTicketUrl(appUrl, ticket) | . | URL de launch por ticket (sin token). | | QualiTrainClient | ./server | Cliente backchannel: createSession(). | | QualiTrainError | ./server | Error tipado (status, code). | | QualiTrainProvider | ./react | Config global (appUrl + companyToken) una vez. | | QualiTrainButton | ./react | Botón/anchor "Ver capacitación". |

Control y reporting

El progreso, la finalización y el puntaje de cada quiz se registran en QualiTrain automáticamente cuando el alumno usa el player, y se consultan en el panel admin (Admin → Proyecto → Integración → Seguimiento). Este SDK se encarga solo del acceso.