API Reference — Subscriptions & Licenses

Esta sección documenta los endpoints disponibles para la gestión de providers hijos, credenciales, y consulta de licencias y suscripciones.

🔒 Todos los endpoints requieren autenticación. Consulta la sección de Autenticación para obtener tu token y usarlo en la cabecera Authorization: Bearer <token>.

---

Crear provider hijo

Permite al provider padre registrar un nuevo proveedor hijo en la plataforma.

👨🏻‍💻 QA:

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

🏥 Producción:

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

Body (application/json):

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

Campo	Tipo	Obligatorio	Descripción
name	string	Sí	Nombre del establecimiento.
country	string	Sí	País de ubicación.
city	string	Sí	Ciudad de ubicación.

Respuesta exitosa (200 OK):

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

⚠️ Guardá el providerId, clientId y secret. Los necesitarás para todos los pasos siguientes.

---

Obtener credenciales del provider hijo

Recupera las credenciales de autenticación de un proveedor hijo existente.

👨🏻‍💻 QA:

GET https://api-qa.speaknosis.com/iam/v1/provider/{childProviderId}/credentials

🏥 Producción:

GET https://api-prod.speaknosis.com/iam/v1/provider/{childProviderId}/credentials

Parámetro	Ubicación	Tipo	Obligatorio	Descripción
childProviderId	path	string	Sí	ID del proveedor hijo.

Respuesta exitosa (200 OK):

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

---

Listar providers hijos

Retorna todos los providers hijos vinculados al provider padre autenticado.

👨🏻‍💻 QA:

GET https://api-qa.speaknosis.com/core/v1/provider/{providerId}/child

🏥 Producción:

GET https://api-prod.speaknosis.com/core/v1/provider/{providerId}/child

Parámetro	Ubicación	Tipo	Obligatorio	Descripción
providerId	path	string	Sí	ID del provider padre.

Respuesta exitosa (200 OK):

{
  "success": true,
  "code": 200,
  "response": [
    {
      "providerId": 1042,
      "name": "Clínica Hija",
      "country": "Chile",
      "city": "Santiago"
    }
  ]
}

---

Suscripciones y Licencias

Consultar usuarios con sus licencias

Retorna el listado de doctores registrados en el provider junto con el estado de su licencia asignada.

👨🏻‍💻 QA:

GET https://api-qa.speaknosis.com/payments/v1/subscription/provider/{providerId}/user

🏥 Producción:

GET https://api-prod.speaknosis.com/payments/v1/subscription/provider/{providerId}/user

Parámetro	Ubicación	Tipo	Obligatorio	Descripción
providerId	path	string	Sí	ID interno del provider.

Respuesta exitosa (200 OK):

{
  "success": true,
  "code": 200,
  "response": {
    "doctors": [
      {
        "id": "tu-id-externo-1",
        "name": "Juan",
        "lastname": "Pérez",
        "license": {
          "type": "BASIC",
          "isEnabled": true,
          "currentUsage": 12,
          "limit": 100,
          "expiresAt": "2026-06-01T00:00:00.000Z"
        }
      },
      {
        "id": "tu-id-externo-2",
        "name": "María",
        "lastname": "González",
        "license": null
      }
    ]
  }
}

Campo	Tipo	Descripción
doctors[].id	string	ID externo del doctor en tu sistema.
doctors[].license	object	Licencia asignada. null si el doctor no tiene licencia.
license.type	string	Tipo de licencia: BASIC, ELITE o TRIAL.
license.isEnabled	boolean	Si la licencia está activa (false cuando el usuario llego al límite de consultas en un plan basic).
license.currentUsage	number	Consultas realizadas en el período actual.
license.limit	number	Límite mensual de consultas. null para plan ELITE (sin límite).
license.expiresAt	string	Fecha de vencimiento de la licencia.

---

Consultar licencias del proveedor

Permite consultar el resumen de licencias del provider, o filtrar por usuario específico.

👨🏻‍💻 QA:

GET https://api-qa.speaknosis.com/payments/v1/subscription/provider/{providerId}/license

🏥 Producción:

GET https://api-prod.speaknosis.com/payments/v1/subscription/provider/{providerId}/license

Parámetro	Ubicación	Tipo	Obligatorio	Descripción
providerId	path	string	Sí	ID interno del provider.
userId	query	string	No	ID externo del usuario para filtrar sus licencias específicas.

Sin userId — Resumen general

Retorna el total de licencias contratadas, en uso y disponibles por plan, más información de downgrade programado si existe.

Respuesta exitosa (200 OK):

{
  "success": true,
  "code": 200,
  "response": {
    "summary": [
      {
        "type": "BASIC",
        "total": 10,
        "used": 7,
        "available": 3
      },
      {
        "type": "ELITE",
        "total": 5,
        "used": 5,
        "available": 0
      }
    ],
    "scheduledDowngrade": {
      "quantity": {
        "8": 6,
        "9": 3
      },
      "effectiveDate": "2026-07-01T00:00:00.000Z"
    }
  }
}

ℹ️ scheduledDowngrade es null si no hay downgrade programado.

Con userId — Licencia de un usuario específico

Ejemplo:

GET .../license?userId=tu-id-externo-1

Respuesta exitosa (200 OK):

{
  "success": true,
  "code": 200,
  "response": {
    "licenses": [
      {
        "id": 301,
        "type": "BASIC",
        "limit": 100,
        "currentUsage": 12,
        "isEnabled": true,
        "createdAt": "2026-01-15 10:00:00",
        "updatedAt": "2026-05-20 08:30:00",
        "lastUsedAt": "2026-05-20 08:30:00",
        "expiresAt": "2026-06-01T00:00:00.000Z",
        "userId": "tu-id-externo-1",
        "name": "Juan",
        "lastname": "Pérez"
      }
    ]
  }
}

---

Códigos de error comunes

Código	Descripción
401	Token de autenticación faltante o inválido.
403	Sin permisos para acceder a este recurso.
404	Recurso no encontrado (proveedor, usuario o licencia inexistente).