Provider Child — Suscripciones y Licencias

Esta guía describe el flujo completo para que un centro médico (provider padre) pueda crear centros médicos hijos, registrar sus profesionales, gestionar licencias de prueba y, cuando esté listo, contratar y administrar un plan pago, todo desde el Portal de Gestión de Licencias de Speaknosis.

---

🔑 Prerequisito: Habilitación por parte de Speaknosis

Para poder crear centros médicos hijos, el provider padre debe estar habilitado previamente por el equipo de Speaknosis. Una vez habilitado, el provider padre podrá autenticarse con sus credenciales existentes (clientId y client_secret) y comenzar a operar.

💡 ¿Aún no estás habilitado? Contacta a nuestro equipo de soporte técnico para iniciar el proceso.

---

🏥 Paso 1 — Crear el HP hijo

Con tus credenciales de HP padre, autentícate según la sección de Autenticación y luego realiza la siguiente solicitud:

👨🏻‍💻 Entorno QA:

POST https://api-qa.speaknosis.com/api/iam/register/childProvider

🏥 Entorno de producción:

POST https://api-prod.speaknosis.com/api/iam/register/childProvider

Cuerpo de la solicitud (application/json):

{
  "name": "Clínica Hija",
  "country": "Chile",
  "city": "Santiago"
}

Respuesta exitosa (200 OK):

{
  "success": true,
  "code": 200,
  "response": {
    "providerId": 1042,
    "clientId": "speaknosis-client-xxxxx",
    "secret": "xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

⚠️ Importante: Guarda el providerId, el clientId y el secret del response. Los necesitarás en todos los pasos siguientes.

Al crear el HP hijo, Speaknosis genera automáticamente:

• ✅ 1 suscripción con estado TRIAL
• ✅ 10 licencias de prueba con 60 días de vigencia desde la fecha de creación

---

👥 Paso 2 — Registrar los profesionales en Speaknosis

En esta etapa, los profesionales ya existen en tu plataforma. Este paso consiste en registrarlos en Speaknosis para que puedan ser gestionados desde el portal de licencias.

Para registrar a un doctor, autentícate con el token del HP hijo y realiza la solicitud de creación de doctor:

👉 Ver sección de Creación de Doctores

💡 Importante: El campo id que enviás al registrar el doctor debe ser el identificador del usuario en tu propio sistema. Speaknosis lo utilizará en el portal de gestión para identificar a cada profesional.

Una vez que los profesionales están registrados en Speaknosis, ya pueden ser gestionados desde el portal de licencias.

---

🎛️ Paso 3 — Abrir el Portal de Gestión de Licencias

Speaknosis provee un portal listo para usar, que permite gestionar visualmente las licencias de los doctores sin necesidad de desarrollar una interfaz propia.

Cómo abrir el portal

Para abrir el portal, primero obtén un token de acceso del HP hijo y luego construye la URL del portal:

// 1. Autenticarse con las credenciales del HP hijo
const response = await fetch(
  "https://api.speaknosis.com/api/iam/integration/token",
  {
    method: "POST",
    headers: { "Content-Type": "application/x-www-form-urlencoded" },
    body: new URLSearchParams({
      grant_type: "client_credentials",
      client_id: HP_CLIENT_ID,
      client_secret: HP_CLIENT_SECRET,
    }),
  },
);
const { access_token } = await response.json();

// 2. Construir la URL del portal
const params = new URLSearchParams({
  token: access_token,
  providerId: PROVIDER_ID, // providerId recibido en el Paso 1
});

// 3. Abrir el portal
window.open(
  `https://portal.speaknosis.com/#/pop-up/license-management?${params}`,
  "LicenseManagement",
  "width=800,height=700",
);

El portal recibe el token vía URL y lo gestiona de forma autónoma — no requiere que el HP mantenga la sesión activa.

Pestañas del portal

El portal está organizado en 3 pestañas:

Pestaña	Nombre	Descripción
1	Usuarios	Lista de doctores con su licencia asignada. Permite asignar y desasociar en lote.
2	Actividad	Ranking de doctores por cantidad de consultas realizadas.
3	Actualizar / Contratar	Gestión de la suscripción: contratación inicial o actualización de plan.

---

🔗 Paso 4 — Asignar licencias trial a los doctores

Con los doctores ya registrados (Paso 2) y el portal abierto (Paso 3), el siguiente paso es asignarles las licencias trial disponibles.

Desde la pestaña Usuarios:

1. El portal muestra la lista de todos los doctores registrados.
2. Los que aún no tienen licencia aparecen con el estado Sin licencia.
3. Haz clic en el selector de plan de cada doctor y elige Trial.
4. Los cambios se acumulan y se guardan en lote al confirmar — el portal valida en tiempo real que no se supere la cantidad de slots disponibles.

💡 Tienes 10 slots trial disponibles. Puedes asignárselos a los primeros 10 doctores que quieran usar Speaknosis.

Desasociar una licencia trial:

Si un doctor ya no necesita la licencia, desde la pestaña Usuarios cambia su plan a Sin licencia y confirma. La licencia queda libre para asignarse a otro doctor.

---

⏱️ Paso 5 — Período trial: duración y vencimiento

Las licencias trial tienen las siguientes características:

Campo	Valor
Tipo	TRIAL
Vigencia	60 días desde la creación del HP hijo
Slots disponibles	10 licencias por suscripción
Límite de consultas	Sin límite

¿Qué pasa cuando una licencia trial vence?

• El doctor puede completar la consulta en curso normalmente.
• A partir de la siguiente consulta, verá un mensaje indicando que su acceso expiró.
• La licencia queda marcada automáticamente como inactiva y eliminada.
• Las licencias vencidas no aparecen en el portal ni pueden reasignarse.

⚠️ Antes de que venza el trial, contrata un plan pago para evitar interrupciones en el servicio de tus doctores.

---

💳 Paso 6 — Contratar un plan pago

Cuando el HP esté listo para contratar un plan pago, abre el portal y navega a la pestaña Contratar.

Planes disponibles

Plan	Límite de consultas por doctor
Basic	Límite mensual (se resetea al inicio de cada período)
Elite	Sin límite de consultas

Los precios varían según la cantidad contratada por plan (descuentos por volumen). El portal muestra el cálculo en tiempo real a medida que ajustas las cantidades.

Proceso de contratación

1. Desde la pestaña Contratar, ajusta la cantidad de slots Basic y/o Elite que necesitas.
2. Haz clic en Ir a pagar en Stripe.
3. El portal abre automáticamente la sesión de Stripe Checkout.
4. Completá el pago en Stripe.

Al confirmar el pago, Speaknosis procesa automáticamente:

• Crea los nuevos slots de licencias pagadas como disponibles.
• Registra la cantidad contratada por plan.
• Envía un callback al endpoint configurado del HP con el detalle de los nuevos slots.

💡 Una vez confirmado el pago, los slots aparecen disponibles en la pestaña Usuarios dentro de los siguientes minutos.

---

👤 Paso 7 — Asignar licencias del plan pago

Luego de contratar el plan, los slots quedan disponibles. El proceso de asignación es idéntico al de las licencias trial:

1. Abre el portal y navega a la pestaña Usuarios.
2. Para cada doctor, selecciona el plan que le corresponde (Basic o Elite).
3. Confirma los cambios en lote.

El portal valida en tiempo real que no se supere la cantidad contratada. Si todos los slots de un plan están ocupados, ese plan no aparecerá como opción hasta que se libere alguno.

Renovación mensual:

Al inicio de cada nuevo período de facturación, Speaknosis resetea automáticamente el contador de consultas de todas las licencias y reactiva las que hayan alcanzado su límite. Los doctores recuperan su acceso sin ninguna acción adicional.

---

🔄 Paso 8 — Actualizar la suscripción

Para cambiar la cantidad de licencias contratadas (aumentar o reducir), abre el portal y navega a la pestaña Actualizar.

Aumentar licencias (upgrade)

1. Ajusta las cantidades al nuevo valor deseado.
2. Haz clic en Actualizar suscripción.
3. Los nuevos slots quedan disponibles de inmediato.
4. Asígnalos a tus doctores desde la pestaña Usuarios.

Reducir licencias (downgrade)

Reducir la cantidad de licencias implica que en el próximo período de facturación habrá menos slots. El proceso está diseñado para que la decisión sea siempre consciente:

¿Qué pasa si hay más doctores asociados que la nueva cantidad de slots?

Por ejemplo: tienes 8 licencias Basic ocupadas y quieres reducir a 3.

1. Al hacer clic en Actualizar suscripción, el portal detecta que hay 5 doctores en exceso.
2. Aparece una pantalla de selección: ves la lista de los doctores actualmente asignados y eliges cuáles 3 conservan su licencia.
3. Los doctores que no selecciones figurarán como "Perderá acceso" — esto no es inmediato.
4. Confirmas la reducción.

¿Cuándo se aplica el cambio?

La reducción no es inmediata: se programa para aplicarse al inicio del próximo período de facturación. El portal te muestra la fecha exacta en la que se hará efectiva.

Hasta esa fecha:

• Todos los doctores mantienen su acceso sin interrupciones.
• El portal muestra un banner con la reducción programada y la fecha de aplicación.
• Los doctores que no conservarán licencia perderán el acceso recién en esa fecha.

¿Qué pasa si no hay doctores en exceso?

Si la nueva cantidad sigue siendo mayor o igual a la cantidad de doctores asociados, el downgrade se confirma directamente sin mostrar la pantalla de selección. Speaknosis aplica el cambio en el próximo período sin impacto en el acceso de ningún doctor.

---

📋 Resumen del flujo completo

[Paso 1] Crear HP hijo             → Recibir providerId + credenciales
[Paso 2] Registrar profesionales   → Crear doctores con su ID externo
[Paso 3] Abrir el portal           → Autenticar y abrir el popup de gestión
[Paso 4] Asignar licencias trial   → Pestaña Usuarios → seleccionar plan Trial
[Paso 5] Período trial             → 60 días de vigencia, 10 slots disponibles
[Paso 6] Contratar plan pago       → Pestaña Contratar → pago vía Stripe
[Paso 7] Asignar licencias pagas   → Pestaña Usuarios → seleccionar Basic/Elite
[Paso 8] Actualizar suscripción    → Pestaña Actualizar → ajustar cantidades
         └─ Downgrade con exceso   → Pantalla de selección → se aplica al próximo período

---

📊 Diagrama de flujo