Skip to main content

Gestión de Creación y Reactivación de Doctores vía API

Este endpoint permite crear doctores asociados a su Centro Médico, registrar múltiples doctores en una sola llamada a la API, o reactivar un userId que fue previamente eliminado mediante el método DELETE (teniendo en cuenta que es un soft delete).

🔒 Nota: Este recurso requiere autenticación. Consulte la sección de Autenticación para instrucciones sobre cómo obtener su token y cómo usarlo en la cabecera Authorization

Endpoint​

💡 Importante: Para conocer en detalle los métodos, parámetros requeridos, el formato del body y posibles respuestas, puede consultar la documentación específica en el Portal de desarrolladores o revisar el request configurado en el archivo de Postman previamente compartido.

🔐 Nota: Para obtener el catálogo de HealthAPI, debe autenticarse en ese mismo portal utilizando las credenciales otorgadas.

Parámetros​

ParámetroTipoObligatorioDescripción
providerIdnumberSíID del proveedor/centro médico. Este debe ser incluido en los parámetros de la ruta (path params).

Creación de un Doctor Individual​

Para crear un solo doctor, envíe un objeto JSON en el cuerpo de la solicitud.

Ejemplo de cuerpo de la solicitud (application/json):

[
  {
    "id": "",         // ID único del usuario
    "name": "",       // Nombre de usuario
    "lastname": "",   // Apellido del usuario
    "email": "",      // Correo electrónico del usuario (opcional)
    "specialityId": 1,// ID de la especialidad médica (por ejemplo, Medicina General)
    "lang": ""        // Idioma del usuario ("ES", "EN", "CA", "PT", "FR")
  }
]

Ejemplo de respuesta exitosa (201 Created):

{
  "success": true,
  "code": 201,
  "response": [
    {
      "id": "1051",
      "name": "Juan",
      "lastname": "Pérez",
      "status": "user created successfully"
    }
  ]
}

Creación de Múltiples Doctores​

Para registrar varios doctores simultáneamente, envíe un array de objetos JSON en el cuerpo de la solicitud. Cada objeto en el array representa un doctor a registrar.

Ejemplo de cuerpo de la solicitud (application/json):

[
  {
    "id": "1052",
    "name": "Lucía",
    "lastname": "Gómez",
    "email": "[email protected]",
    "specialityId": 1,
    "lang": "ES"
  },
  {
    "id": "1053",
    "name": "Marc",
    "lastname": "Dubois",
    "email": "[email protected]",
    "specialityId": 1,
    "lang": "FR"
  }
]

Ejemplo de respuesta exitosa (201 Created):

{
  "success": true,
  "code": 201,
  "response": [
    {
      "id": "1052",
      "name": "Lucía",
      "lastname": "Gómez",
      "status": "user created successfully"
    },
    {
      "id": "1053",
      "name": "Marc",
      "lastname": "Dubois",
      "status": "user created successfully"
    }
  ]
}

Reactivación de un Usuario Eliminado (Soft Delete)​

Para reactivar un userId que fue previamente eliminado mediante el método DELETE (soft delete), envíe un objeto JSON con los datos actualizados del usuario. Es crucial que el id en el cuerpo de la solicitud coincida con el id del usuario previamente eliminado.

Ejemplo de cuerpo de la solicitud (application/json):

[
  {
    "id": "1051",       // ID del usuario existente pero previamente eliminado
    "name": "new",      // Nuevo nombre de usuario
    "lastname": "new",  // Nuevo apellido
    "email": "[email protected]", // Nuevo correo electrónico (opcional)
    "specialityId": 1,  // Nueva especialidad del usuario
    "lang": "EN"        // Nuevo idioma del usuario ("ES", "EN", "CA", "PT", "FR")
  }
]

Ejemplo de respuesta exitosa (201 Created):

{
  "success": true,
  "code": 201,
  "response": [
    {
      "id": "1051",
      "name": "new",
      "lastname": "new",
      "status": "updated and reactivated userId"
    }
  ]
}

Notas sobre los Campos​

Para completar el campo specialityId, utilice el método Obtener todas las especialidades para consultar las especialidades disponibles y sus identificadores correspondientes.

Ejemplo de Implementación: Verificación y Creación Automática​

Para reducir la fricción en la integración y evitar errores de "Usuario no encontrado" cuando un médico intenta acceder por primera vez, recomendamos implementar un flujo en tu frontend.

Esta lógica verifica si el doctor existe antes de lanzar el popup/iframe de Speaknosis. Si el doctor no existe (error 404), el sistema lo crea automáticamente.

A continuación, presentamos un ejemplo funcional en JavaScript:

/**
 * Verifica si un doctor existe en Speaknosis.
 * Si no existe (404), lo crea automáticamente.
 * @param {string} token - Token de acceso obtenido previamente
 * @param {object} doctorData - Objeto con los datos del doctor (id, name, lastname, specialityId, lang)
 * @param {string} providerId - ID del centro médico
 */
async function checkAndCreateDoctor(token, doctorData, providerId) {
  const DOCTOR_API_HOST = "https://api-qa.speaknosis.com/v1/health"; // Ajustar según entorno (QA/PROD)
  
  const checkUrl = `${DOCTOR_API_HOST}/provider/${providerId}/user/${doctorData.id}`;
  const createUrl = `${DOCTOR_API_HOST}/provider/${providerId}/user`;

  try {
    // 1. VERIFICAR: Consultamos si el doctor ya existe
    const checkResponse = await fetch(checkUrl, {
      method: "GET",
      headers: { Authorization: `Bearer ${token}` },
    });

    if (checkResponse.ok) {
      console.log("✅ El doctor ya existe. Continuando...");
      return; 
    }

    // 2. CREAR: Si recibimos un 404, procedemos a crearlo
    if (checkResponse.status === 404) {
      console.log("⚠️ Doctor no encontrado. Creando automáticamente...");

      const createResponse = await fetch(createUrl, {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          Authorization: `Bearer ${token}`,
        },
        // 🚨 IMPORTANTE: La API espera un array de doctores, 
        // incluso si solo estamos creando uno.
        body: JSON.stringify([doctorData]), 
      });

      if (!createResponse.ok) {
        throw new Error(`Error creando doctor: ${createResponse.statusText}`);
      }

      console.log("🎉 Doctor creado exitosamente.");
      return;
    }

    // Manejo de otros errores no relacionados con 404
    throw new Error(`Error inesperado al verificar: ${checkResponse.status}`);
    
  } catch (error) {
    console.error("Error en el flujo de verificación de doctor:", error);
    throw error; // Propagar error para manejarlo en la UI (ej. mostrar alerta)
  }
}

💡 Tip para Desarrolladores: En el paso de creación (POST), envolvemos el objeto doctorData dentro de corchetes [doctorData]. Esto es obligatorio ya que el endpoint está diseñado para recibir y procesar listas de doctores, incluso cuando se envía una sola unidad.