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 provider 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 provider 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 provider 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.
`limit`	query	`number`	No	Cantidad de resultados por página. Si no se envía, retorna todos los hijos.
`offset`	query	`number`	No	Cantidad de resultados a saltar. Por defecto: `0`.

Ejemplo con paginación:

GET .../child?limit=10&offset=20

Respuesta exitosa (200 OK):

{
  "success": true,
  "code": 200,
  "response": {
    "data": [
      {
        "id": 1042,
        "name": "Clínica Hija",
        "country": "Chile"
      }
    ],
    "meta": {
      "total": 45,
      "offset": 0,
      "limit": 10
    }
  }
}

Campo	Tipo	Descripción
`data`	`array`	Listado de providers hijos.
`meta.total`	`number`	Total de providers hijos del padre.
`meta.offset`	`number`	Offset aplicado en la consulta.
`meta.limit`	`number`	Límite aplicado. Si no se envió `limit`, coincide con `total` (se trajo todo).

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.
`limit`	query	`number`	No	Cantidad de resultados por página. Por defecto: `10`.
`offset`	query	`number`	No	Cantidad de resultados a saltar. Por defecto: `0`.

Ejemplo con paginación:

GET .../user?limit=20&offset=40

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
      }
    ],
    "meta": {
      "total": 152,
      "offset": 0,
      "limit": 20
    }
  }
}

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 llegó 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.
`meta.total`	`number`	Total de doctores del provider, útil para calcular páginas.
`meta.offset`	`number`	Offset aplicado en la consulta.
`meta.limit`	`number`	Límite aplicado. Si no se envió `limit`, coincide con `total` (se trajo todo).

Consultar licencias del provider

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 (provider, usuario o licencia inexistente).

Crear provider hijo​

Obtener credenciales del provider hijo​

Listar providers hijos​

Suscripciones y Licencias​

Consultar usuarios con sus licencias​

Consultar licencias del provider​

Sin userId — Resumen general​

Con userId — Licencia de un usuario específico​

Códigos de error comunes​

Crear provider hijo

Obtener credenciales del provider hijo

Listar providers hijos

Suscripciones y Licencias

Consultar usuarios con sus licencias

Consultar licencias del provider

Sin `userId` — Resumen general

Con `userId` — Licencia de un usuario específico

Códigos de error comunes