Skip to main content

Visão Geral de Telemedicina

Gerencia as salas de videochamada (LiveKit) usadas nas consultas online: criação/busca de sala, geração de token de acesso, notificação do paciente via WebSocket, gravação e transcrição.

Autenticação necessária

Todas as rotas exigem o header Authorization: Bearer {accessToken} (JWT do provedor de identidade) ou x-api-key. Veja Autenticação.

Sem permissão específica

As rotas deste módulo exigem apenas autenticação.


Base​

https://api-dev.imagemais.com.br/api/telemedicine

Rotas​

MétodoRotaDescrição
GET/telemedicine/room/{consultationId}Busca a sala LiveKit já criada para a consulta
GET/telemedicine/room/{consultationId}/staff-statusInforma se outro profissional (identidade user-* diferente do usuário atual) já está na sala: { "data": { "occupied": true } }. Sala inexistente → occupied: false. Sem página própria ainda
POST/telemedicine/tokenGera um token LiveKit para o usuário atual entrar numa sala
POST/telemedicine/roomCria a sala da consulta (ou retorna a existente)
POST/telemedicine/notifyNotifica o paciente (via WebSocket) que a sala está pronta
DELETE/telemedicine/deleteEncerra a sala e finaliza a consulta
POST/telemedicine/activate-recordingInicia a gravação (áudio) da sala
GET/telemedicine/transcriptionBusca a transcrição salva da consulta
GET/telemedicine/transcription-preferenceVerifica se a transcrição está habilitada para a consulta
PATCH/telemedicine/transcription-preferenceHabilita/desabilita a transcrição da consulta
GET/telemedicine/recording-presigned-urlGera URL assinada para baixar um arquivo de gravação

Fluxo típico de uma teleconsulta​

  1. Médico chama POST /telemedicine/room para criar a sala (idempotente — se já existe, retorna a mesma).
  2. Médico chama POST /telemedicine/notify — isso busca/gera um token para o paciente e emite telemedicine.room.ready via WebSocket (gateway de pacientes) com o token. Exige que a sala já exista (passo 1).
  3. Médico e paciente entram na sala usando POST /telemedicine/token (gera o token de cada lado) + SDK do LiveKit no client.
  4. Com participantes conectados, o frontend chama POST /telemedicine/activate-recording para começar a gravar (requer feature flag habilitada e a flag LIVEKIT_ENABLE_RECORDING).
  5. Ao final, DELETE /telemedicine/delete encerra a sala no LiveKit, finaliza a consulta (consultationStatus = FINAL) e para qualquer gravação em andamento.
Identificação dos participantes no LiveKit

O médico entra com identity = user-{userId} e o paciente com identity = patient-{patientId}. O nome de sala segue o padrão telemedicine-{consultationId}-{consultation.createdAt em ms}.


Notificação ao paciente (WebSocket)​

POST /telemedicine/notify não empurra nada por HTTP para o paciente — ele emite eventos internos que o PatientGateway (Socket.io, ver Gateways) repassa para a sala WS do paciente:

Evento internoEvento WebSocket (para o paciente)Payload
patient.room.ready (emitido por notify)telemedicine.room.ready{ token, timestamp }
patient.room.closed (emitido por delete)telemedicine.room.closed—
Falha silenciosa se o paciente não estiver conectado por WS

Se o paciente não tiver uma conexão WebSocket ativa (sem "room hash" registrado no gateway), o evento simplesmente não é enviado — só um warn no log do servidor. A resposta HTTP de POST /telemedicine/notify continua { "success": true } mesmo assim, então a API não tem como saber (por essa rota) se o paciente foi de fato avisado.


Gravação​

Gravação é somente áudio (audioOnly: true, formato OGG), feita via LiveKit Egress e enviada direto para o Cloudflare R2. Dois egresses são iniciados em paralelo:

  • Room composite: uma faixa combinada de toda a sala, salva em telemedicine/{sha256(consultationId)}/{room_name}.
  • Por participante: uma faixa de áudio individual por participante conectado, salva em telemedicine/{sha256(consultationId)}/tracks/{participantName}-{time}.

O consultationId é hasheado (SHA-256) no path do arquivo — não aparece em texto puro no storage.


Transcrição​

A transcrição em si (texto) é gerada fora deste módulo e fica salva no campo telemedicineTranscription da consulta — GET /telemedicine/transcription só lê esse campo. A "preferência" de transcrição é um flag independente, guardado no Redis (chave telemedicine:transcription:disabled:{consultationId}, sem TTL), que controla se a geração de transcrição deve rodar para aquela consulta.