Cómo funciona
POST /v1/scribe-sessions/livedevuelve una URL de WebSocket.- Conéctate a esa URL y transmite el audio a medida que se captura.
- Envía
stop_recordingcuando termine la consulta. - El webhook
scribe_session.completedte avisa que la historia clínica está lista. - Obtén la historia clínica desde Documentos de historia clínica.
Qué debe tener la API key
La API key que uses aquí necesita cumplir las tres condiciones siguientes; de lo contrario, la llamada falla con403:
- El permiso
scribe:write, otorgado de forma explícita. Una API key antigua sin el claim de permisos funciona en algunos otros endpoints, pero aquí se rechaza; regenera la API key para obtener una que lo tenga. - El rol
doctor. - Un vínculo con una institución.
Crear una sesión
El cuerpo de la solicitud lleva el contexto de la consulta: de qué consulta se trata, qué plantilla se debe llenar, a qué paciente pertenece y cualquier contexto escrito que ya tengas.live.url como un valor opaco y manéjala como un secreto. Conéctate a ella exactamente como se devuelve y no la construyas tú: el host, la ruta y la credencial pueden cambiar sin aviso.
La credencial se verifica solo cuando se abre el socket. Una conexión establecida antes de expiresAt puede seguir transmitiendo después de esa hora, y un intento de conexión posterior se rechaza; por eso, solicita una sesión nueva en lugar de reutilizar una URL vencida.
Campos de la solicitud
Elegir la plantilla
template acepta un id o el propio JSON de la plantilla. Envía exactamente uno de los dos.
Enviar ambos, o ninguno, devuelve
400 con param igual a template.
La forma en línea:
Identificar al paciente
patient también acepta un id o la identidad en línea. Envía exactamente uno de los dos.
Reintentar la misma consulta
Llamar al endpoint de nuevo con el mismoconsultation.id mientras la sesión sigue grabando devuelve la misma sesión con una URL nueva. Esa es la forma admitida de recuperarse de una conexión caída. No compares las dos URL entre sí ni guardes en caché la primera. Una vez detenida la grabación, el mismo id devuelve 409.
Enviar audio
Conéctate alive.url. El servidor envía un mensaje ready cuando está preparado para recibir audio.
Envía el audio como frames binarios de WebSocket. Se aceptan dos formatos:
Envía aproximadamente 100 ms de audio por frame, al ritmo en que se captura. Una carga PCM de menos de 1024 bytes (unos 32 ms) se conserva en la grabación, pero no se reenvía al reconocedor en vivo; por eso, los frames muy pequeños retrasan el texto que ves, pero no hacen que se pierda audio.
Mantener la conexión activa
Envía{"type": "ping", "data": {}} cuando quieras confirmar que el socket está activo; el servidor responde con {"type": "pong", "data": {}}. Cualquier frame entrante, incluido el audio, cuenta como actividad. El servidor cierra una sesión que no recibe nada durante 15 minutos, así que envía audio de forma continua o envía un ping durante las pausas largas.
Mensajes que recibes
Cada mensaje es JSON con un campotype y un campo data.
Una
correction reemplaza lo que un transcript informó para el mismo segmento. Si le muestras el texto a un médico, aplica las correcciones a medida que llegan.
reconnect puede traer dos motivos. server_draining significa que el servidor se está reiniciando: reconéctate y sigue transmitiendo. resume_upload significa que la orden de detener llegó antes que todo el audio: reconéctate y envía el audio que falta.
Finalizar la sesión
Envía este mensaje cuando termine la consulta:scribe_completed con data.status igual a processing y cierra la conexión.
Recibir la historia clínica
El webhookscribe_session.completed incluye consultationInternalId, que es el mismo consultation.id que enviaste. Úsalo para obtener la historia clínica:
stop_recording. La generación avanza en parte mientras se transmite el audio, así que una consulta más larga no tarda proporcionalmente más en terminar.
Pérdida de conexión
Reconectarse es normal y seguro.- El socket se cae durante la grabación. Vuelve a llamar a
POST /v1/scribe-sessions/livecon el mismoconsultation.idy conéctate a la URL que devuelve. El audio ya recibido se conserva. live.urlllega aexpiresAt. Solicita una sesión nueva con el mismoconsultation.id. Un socket ya abierto no se ve afectado.- Cierre 1013. Se puede reintentar: el servidor está ocupado o reiniciándose. Espera un momento y reconéctate.
- Cierre 1003. El audio no se pudo decodificar. La sesión pasa a estado de error, así que reconectarse no la recupera. Corrige el codificador y empieza una consulta nueva.
- Cierre 1008. Definitivo: la credencial o la sesión no son válidas. No te reconectes; reintentar da el mismo resultado.
Errores
Consulta Manejo de errores para ver el formato completo de la respuesta.