Guía de integración — Suscripciones y Licencias

Esta guía describe el flujo completo para que un provider padre pueda crear providers 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 providers hijos, el provider padre debe estar habilitado previamente por el equipo de Speaknosis. Una vez habilitado, 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 provider hijo

Con tus credenciales de provider 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/iam/v1/register/childProvider

🏥 Entorno de producción:

POST https://api-prod.speaknosis.com/iam/v1/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 provider hijo, Speaknosis genera automáticamente:

• ✅ 1 suscripción con estado TRIAL
• ✅ 10 licencias de prueba con 30 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 provider 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.

---

🎛️ 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

// 1. Autenticarse con las credenciales del provider hijo
const response = await fetch(
  "https://api-qa.speaknosis.com/api/iam/integration/token",
  // PROD: "https://api-prod.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({
  view: "licenses",
  healthProviderId: PROVIDER_ID, // providerId recibido en el Paso 1
  token: access_token,
});

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

Pestañas del portal

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 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.

---

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

Campo	Valor
Tipo	TRIAL
Vigencia	30 días desde la creación del provider 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 última consulta en curso normalmente.
• A partir de la siguiente consulta, verá un mensaje indicando que su acceso expiró.

⚠️ 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 provider 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

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 Completar checkout.
3. El portal abre automáticamente la sesión de Checkout.
4. Completá el pago.

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 el evento subscription.contracted al webhook configurado con el detalle de los slots contratados. 👉 Ver sección de Webhooks

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

---

👤 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.

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, 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. Speaknosis envía el evento subscription.updated al webhook configurado. 👉 Ver sección de Webhooks

Reducir licencias (downgrade)

Situación	Comportamiento
Hay más doctores asignados que la nueva cantidad	El portal muestra una pantalla de selección para elegir qué doctores conservan su licencia
La nueva cantidad es mayor o igual a los doctores asignados	El downgrade se confirma directamente sin pantalla de selección

La reducción no es inmediata: se aplica al inicio del próximo período de facturación. Hasta esa fecha todos los doctores mantienen su acceso. Al aplicarse, Speaknosis envía el evento subscription.updated con la nueva cantidad efectiva.

---

📋 Resumen del flujo completo

[Paso 1] Crear provider 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             → 30 días de vigencia, 10 slots disponibles
[Paso 6] Contratar plan pago       → Pestaña Contratar → pago vía Stripe → webhook subscription.contracted
[Paso 7] Asignar licencias pagas   → Pestaña Usuarios → seleccionar Basic/Elite
[Paso 8] Actualizar suscripción    → Pestaña Actualizar → ajustar cantidades → webhook subscription.updated
         └─ Downgrade con exceso   → Pantalla de selección → se aplica al próximo período

---

📊 Diagrama de flujo