learnex연동 문의
LEARNEX DEVELOPERS · API v1

LMS 음성·화상 API 연동 규약

고객사 LMS에서 수업방을 만들고, 학생과 강사에게 로그인 없는 입장 링크를 제공하세요. 수업 결과는 웹훅과 조회 API로 받아볼 수 있습니다.

이용 상태 · 연동 규약을 먼저 공개합니다. 운영 API는 고객사 연동 설정과 활성화가 완료된 뒤 사용할 수 있습니다.

1. 공통 규칙

  1. LMS 서버에서 수업방을 생성합니다.
  2. 권한을 확인한 학생·강사에게 각각 본인 역할의 링크를 제공합니다.
  3. 웹훅 또는 결과 조회 API로 입장·연결·종료를 반영합니다.

기본 주소는 https://learnex.kr/api/lms/v1입니다. 요청은 HTTPS와 JSON을 사용합니다. API 키는 서버에 보관하고, 브라우저에는 역할별 입장 링크만 제공합니다.

Authorization: Bearer <LMS_API_KEY>
Content-Type: application/json

2. 수업방 생성

POST /api/lms/v1/rooms

필드형식규칙
externalId문자열 · 필수LMS 내부 수업 ID. 영문·숫자와 _.:-로 구성한 1~128자입니다. 이름이나 이메일은 넣지 마세요.
expiresInMinutes정수 · 선택기본 60분, 범위 5~1,440분. 생성 시점부터 계산하며 만료 시 진행 중인 수업도 종료합니다.

요청 예제

curl -X POST https://learnex.kr/api/lms/v1/rooms \
  -H "Authorization: Bearer ${LMS_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{"externalId":"lesson-12345","expiresInMinutes":60}'

응답 예제 · 201 Created

{
  "id": "9f34b004-beb6-4f4c-babe-e77662e52cc2",
  "externalId": "lesson-12345",
  "status": "waiting",
  "expiresAt": "2026-11-08T02:00:00.000Z",
  "events": [],
  "links": {
    "teacher": "https://learnex.kr/lms/classroom.html#<TEACHER_TICKET>",
    "student": "https://learnex.kr/lms/classroom.html#<STUDENT_TICKET>"
  }
}

같은 고객사가 동일한 externalId와 만료 설정으로 다시 요청하면 HTTP 200과 기존 방을 받습니다. 사용한 역할의 링크는 응답에서 빠지고, 종료된 방에는 links가 없습니다. 동일 ID에 만료 설정이 다르면 409를 반환합니다.

3. 학생·강사 입장

LMS가 사용자 권한을 확인하고 links.student 또는 links.teacher 중 본인 역할에 해당하는 링크를 제공합니다. 서버가 반환한 URL을 그대로 같은 탭이나 새 탭에서 여세요.

  • 러넥스 회원가입과 로그인은 필요 없습니다. 마이크를 허용하고 입장에 성공하면 해당 링크를 다시 사용할 수 없습니다.
  • 두 사람이 입장하면 통화 연결을 시도합니다. 입장은 실제 연결 성공과 별개로 기록됩니다.
  • 새로고침이나 신호 연결 종료로 세션이 끝난 뒤 다시 수업하려면 새 externalId로 수업방을 생성합니다.
  • 녹음·녹화는 상대방 동의 확인 후 선택합니다. 수업을 마치면 탭을 닫기 전에 파일을 내려받아야 합니다. 파일은 결과 API에 포함되지 않습니다.

4. 수업 결과 조회

GET /api/lms/v1/rooms/{id}

curl https://learnex.kr/api/lms/v1/rooms/9f34b004-beb6-4f4c-babe-e77662e52cc2 \
  -H "Authorization: Bearer ${LMS_API_KEY}"

응답은 id, externalId, status, expiresAt, events를 포함합니다. 상태는 waiting(입장 대기), joining(참가자 입장), active(양쪽 연결 보고), ended(종료)입니다.

이벤트발생 조건
participant.joined입장 링크가 승인되어 학생 또는 강사가 접속했습니다.
room.connected두 브라우저가 모두 WebRTC 연결 성립을 보고했습니다.
room.ended수업이 종료되었습니다. 실제 연결 전에 끝난 수업도 포함됩니다.

이벤트 시각 at은 UTC ISO 8601입니다. role은 해당하는 경우 teacher 또는 student이며, 역할이나 사유가 없으면 null입니다.

5. 웹훅과 서명

등록한 고객사 HTTPS 주소로 이벤트를 JSON POST로 전달합니다. 같은 방의 이벤트는 순서대로 전달합니다. 수신 데이터 저장을 완료한 뒤 2xx로 응답하세요.

이벤트 본문 예제

{
  "id": "2c4f93c9-b724-476b-8e0b-24800899124a",
  "roomId": "9f34b004-beb6-4f4c-babe-e77662e52cc2",
  "externalId": "lesson-12345",
  "type": "room.ended",
  "at": "2026-11-08T01:30:00.000Z",
  "role": "student",
  "reason": "participant_ended"
}

서명 검증 예제 · Node.js

X-Learnex-Timestamp는 Unix 초이며 X-Learnex-Signature는 타임스탬프, 마침표, 원본 본문을 서명한 Base64URL 값입니다. JSON 파싱 전의 본문 바이트를 사용하세요.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyWebhook(rawBody, timestamp, signature, secret) {
  if (!/^\d{1,12}$/.test(timestamp ?? '')) return false;
  if (!/^[A-Za-z0-9_-]{43}$/.test(signature ?? '')) return false;
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac('sha256', secret)
    .update(timestamp + '.')
    .update(rawBody)
    .digest('base64url');

  return timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

서명이 유효한 경우에도 이벤트 id를 기준으로 중복 처리를 막으세요. API 키와 웹훅 서명 키는 서로 다른 값입니다.

6. 오류와 재시도

HTTP오류 코드대응
400invalid_room_request필드 값과 만료 범위를 확인합니다.
401invalid_integration_key서버의 Bearer 인증 키를 확인합니다.
404room_not_found방 ID와 해당 고객사 소유 여부를 확인합니다.
409external_id_already_used최초와 같은 설정으로 요청하거나 새 수업 ID를 사용합니다.

생성 응답을 받지 못하면 같은 수업 ID와 설정으로 재시도합니다. 웹훅 응답이 유실되거나 2xx가 아니면 같은 이벤트 ID로 다시 전송됩니다. 현재 상태는 조회 API로 확인할 수 있습니다.

종료 사유는 participant_ended, participant_disconnected, connection_failed, expired, server_shutdown, server_restart입니다.