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.

💼 Antes de empezar: los dos regímenes de facturación

Un provider padre opera bajo uno de dos regímenes. Determina quién le cobra al centro médico y, con eso, qué partes de esta guía aplican.

	`STRIPE` (por defecto)	`PARTNER_SELF` (self-billing)
Quién le cobra al centro	Speaknosis, vía Stripe	El provider padre, con su propia facturación
Dónde contrata el centro	Portal de Gestión de Licencias (pestaña Contratar)	Canal propio del provider padre
Cómo se contratan y cambian licencias	Checkout de Stripe desde el portal (Pasos 6 y 8)	Webhook del partner hacia Speaknosis
Suspensión por falta de pago	Sí, automática (ver más abajo)	No existe: el acceso solo se corta con el evento de baja
Pestaña Contratar en el portal	Visible	Oculta, con un mensaje que deriva al provider padre
Asignar y desasignar médicos	Portal	Portal (igual)

Esta guía describe el régimen STRIPE, que es el de la mayoría de las integraciones. Si tu provider está en self-billing, los Pasos 1 a 5 y 7 aplican igual, y los Pasos 6 y 8 los reemplaza el webhook del partner. 👉 Ver Self-billing

💡 El self-billing se habilita a nivel del provider padre, no centro por centro: al activarlo, todos sus centros hijos quedan en el flujo nuevo. Para saber en qué régimen está un centro, consultá el campo billing.mode de GET .../provider/{providerId}/user. 👉 Ver API Reference

🏥 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
✅ Licencias de prueba disponibles para asignar a los doctores

💡 La cantidad de licencias y los días de vigencia son configurados por el provider padre. Los valores por defecto son 10 licencias con 30 días de vigencia. Si necesitas ajustar estos valores, contacta al equipo de soporte técnico de Speaknosis y lo configuramos según tus necesidades.

⏱️ Importante — cuándo empieza a correr el trial: los días de vigencia no empiezan a contar al crear el provider ni al asignar la licencia, sino con el primer reporte de cada doctor. Es decir, el trial se activa por doctor, en su primer uso. Ver Paso 5 más abajo.

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

💼 En el régimen self-billing la pestaña 3 no se muestra. Contratar, cambiar cantidad y cancelar los gestiona el provider padre, y el portal muestra en su lugar un mensaje que deriva a él. Las pestañas Usuarios y Actividad funcionan igual. 👉 Ver Self-billing

🔗 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:

El portal muestra la lista de todos los doctores registrados.
Los que aún no tienen licencia aparecen con el estado Sin licencia.
Haz clic en el selector de plan de cada doctor y elige Trial.
Los cambios se acumulan y se guardan en lote al confirmar.

⚡ Asignación automática al abrir la herramienta: además de la asignación manual desde el portal, si un doctor abre el pop-up o el iframe de grabación y todavía no tiene licencia pero el provider tiene slots trial disponibles, Speaknosis le asigna automáticamente una licencia trial en ese momento. Así el doctor puede empezar a usar la herramienta aunque no se le haya asignado manualmente antes. (Si no hay slots trial disponibles, verá el aviso de "Sin licencia".)

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

Campo	Valor
Tipo	`TRIAL`
Duración	Configurable por el provider padre (por defecto: 30 días)
Inicio de la vigencia	Con el primer reporte de cada doctor (no al crear el provider ni al asignar la licencia)
Slots disponibles	Configurable por el provider padre (por defecto: 10 licencias por suscripción)
Límite de consultas	Sin límite

⏱️ Cuándo empieza a contar: mientras el doctor no genera ningún reporte, su licencia trial no tiene fecha de vencimiento (el contador no arrancó). En el primer reporte del doctor, Speaknosis fija el vencimiento en fecha del primer reporte + días de trial (por defecto, 30). El trial se cuenta por doctor, no de forma global para el provider.

¿Qué pasa cuando una licencia trial vence?

Speaknosis ejecuta una vez por día un proceso que da de baja las licencias trial vencidas y deshabilita a los doctores que las tenían.
Desde ese momento, el doctor ve un mensaje indicando que su acceso expiró.
La licencia trial vencida libera su slot: al contratar un plan pago, el doctor vuelve a operar en cuanto se le asigna una licencia paga.

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

💼 Self-billing: este paso no aplica. La contratación la gestiona el provider padre y se notifica a Speaknosis con el evento checkout.session.completed del webhook del partner. Si igualmente se intenta abrir un checkout para un centro en este régimen, la API responde 409. 👉 Ver Self-billing

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

Desde la pestaña Contratar, ajusta la cantidad de slots Basic y/o Elite que necesitas.
Completá el email y el teléfono de facturación (obligatorios): se usan para avisos de cobro (por ejemplo, si un pago falla) y soporte.
Haz clic en Completar checkout.
El portal abre automáticamente la sesión de Checkout.
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:

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

⚡ Centro de un solo usuario: si el centro tiene un único doctor, la asignación es automática — tanto la licencia trial como el plan pago se asignan solos (el plan, apenas se confirma el pago). No necesitas hacer este paso manual.

En centros con varios doctores, el trial se auto-asigna al abrir la herramienta (ver Paso 4), pero las licencias del plan pago se asignan manualmente desde el portal (este paso).

Resumen de asignación:

Centro	Licencia trial	Licencia de plan pago
Un usuario	Automática (al abrir la herramienta)	Automática (al contratar)
Varios	Automática (al abrir la herramienta)	Manual (portal, este paso)

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.

💼 Self-billing: este paso no aplica. Los cambios de cantidad los envía el provider padre con el evento customer.subscription.updated, y se aplican de inmediato (no hay downgrade programado al próximo período). 👉 Ver Self-billing

Aumentar licencias (upgrade)

Ajusta las cantidades al nuevo valor deseado.
Haz clic en Actualizar suscripción.
Los nuevos slots quedan disponibles de inmediato.
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.

💳 Pagos fallidos y suspensión (planes pagos, régimen Stripe)

💼 Self-billing: nada de esta sección aplica. Speaknosis no recibe información de cobro del provider padre, así que no hay estado de pago pendiente ni suspensión automática: el único camino que corta el acceso es el evento de baja customer.subscription.deleted. Un centro atrasado sigue operando hasta que el provider padre envíe esa baja, y los avisos al centro los manda el propio provider padre. 👉 Ver Self-billing

Cuando falla el cobro automático de una suscripción paga, Speaknosis aplica un proceso de reintentos antes de suspender:

Etapa	Qué pasa	¿Los doctores pueden grabar?
Pago pendiente	Falló un cobro; se reintenta según la política de facturación. Se notifica por email al centro.	✅ Sí (todavía no se bloquea)
Suspensión	Tras varios intentos fallidos sin regularizar, la suscripción se suspende.	❌ No: todos los doctores del centro quedan bloqueados
Reactivación	Al recuperarse el pago (actualizar el medio de pago y saldar la factura), se reactiva automáticamente.	✅ Sí, sin acción adicional

Puntos clave para tu integración:

La suspensión afecta a todo el centro: mientras esté suspendido, ningún doctor del provider puede generar reportes.
La reactivación es automática en cuanto se registra el pago; no hace falta volver a asignar licencias.
No se envía un webhook por estos eventos (pago fallido / suspensión / reactivación). El aviso se hace por email al contacto de facturación del centro (el que se carga en el checkout, ver Paso 6).
Si tu sistema necesita reflejar el estado, podés detectarlo por API: cuando el provider está suspendido, sus licencias quedan con isEnabled: false en GET .../provider/{providerId}/user. 👉 Ver API Reference

⚠️ Para evitar suspensiones, mantené actualizado el medio de pago y el email de facturación del centro.

📋 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             → Vigencia y slots según config del padre (por defecto: 30 días, 10 slots)
[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

En el régimen self-billing, los Pasos 6 y 8 se reemplazan por eventos que el provider padre envía al webhook del partner:

[Paso 6'] Contratar         → POST /payments/v1/partner/webhook  checkout.session.completed
[Paso 8'] Cambiar cantidad  → POST /payments/v1/partner/webhook  customer.subscription.updated
[Baja]    Cortar el acceso  → POST /payments/v1/partner/webhook  customer.subscription.deleted
[Volver]  Reactivar         → customer.subscription.updated con reactivate: true

🔑 Prerequisito: Habilitación por parte de Speaknosis​

💼 Antes de empezar: los dos regímenes de facturación​

🏥 Paso 1 — Crear el provider hijo​

👥 Paso 2 — Registrar los profesionales en Speaknosis​

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

Cómo abrir el portal​

Pestañas del portal​

🔗 Paso 4 — Asignar licencias trial a los doctores​

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

💳 Paso 6 — Contratar un plan pago​

Planes disponibles​

Proceso de contratación​

👤 Paso 7 — Asignar licencias del plan pago​

🔄 Paso 8 — Actualizar la suscripción​

Aumentar licencias (upgrade)​

Reducir licencias (downgrade)​

💳 Pagos fallidos y suspensión (planes pagos, régimen Stripe)​

📋 Resumen del flujo completo​

📊 Diagrama de flujo​