Uso de la API: Autenticación y Creación de Sesión

Para iniciar una consulta asistida con IA, tu backend realiza una llamada server-to-server a la API de Qlini. Esta llamada es privada y nunca debe originarse desde el navegador del usuario.

Autenticación de la API

Cada petición a la API de integraciones debe incluir tu API Key en el encabezado X-API-Key y un identificador único de idempotencia:

• X-API-Key: Tu clave secreta asignada (ejemplo: qlp_live_...). Guárdala en variables de entorno seguras.
• Idempotency-Key: Un identificador UUID generado por tu sistema para evitar crear sesiones duplicadas ante reintentos de red.
• Content-Type: application/json

Endpoint: POST /api/v1/integrations/consultation-sessions

Ejemplo de solicitud para crear una nueva sesión médica:

POST /api/v1/integrations/consultation-sessions HTTP/1.1
Host: api.qlini.co
X-API-Key: qlp_live_0192837465abcde...
Idempotency-Key: f47ac10b-58cc-4372-a567-0e02b2c3d479
Content-Type: application/json

{
  "externalEncounterId": "enc-2026-000456",
  "externalClientId": "sede-norte-bogota",
  "template": {
    "code": "medicina-general-adultos"
  },
  "patient": {
    "name": "María Camila Pérez",
    "document": "1098765432",
    "documentType": "CC",
    "age": "42",
    "gender": "FEMENINO",
    "birthDate": "1984-05-12"
  }
}

Parámetros del cuerpo de la solicitud

• externalEncounterId (obligatorio): Identificador de la consulta en tu propio sistema. Qlini lo devolverá en el webhook para que puedas asociar el resultado a la historia clínica correspondiente.
• externalClientId (opcional): Referencia opaca de tu cliente final, sede o sucursal médica.
• template.code (obligatorio): Código de la plantilla clínica asignada a tu catálogo.
• patient (opcional o requerido según la plantilla): Datos del paciente para mostrar en la cabecera contextual del iframe y evaluar reglas lógicas (visibleIf) dependientes de edad o sexo.

Respuesta de la API

La API devuelve el enlace efímero de lanzamiento que debe cargarse en el iframe:

{
  "sessionId": "cs_01928374-65ab-7c8d-9e0f",
  "externalEncounterId": "enc-2026-000456",
  "embedUrl": "https://app.qlini.co/embed/launch/eyJhbGciOi...",
  "expiresAt": "2026-09-03T23:30:00.000Z",
  "template": {
    "code": "medicina-general-adultos",
    "version": 2,
    "definitionHash": "sha256:d8f7e6a4b2c1..."
  }
}