본문으로 건너뛰기

API

위험

KOS Connect는 아직 개발 단계입니다.

API가 추가, 변경, 제거될 수 있습니다. 자세한 사항은 영업 담당자 또는 개발 담당자에게 문의하세요.

병원 홈페이지에 KOS Connect 위젯을 추가하면, 내원객이 홈페이지에서 특정 버튼을 클릭하거나 행동을 했을 때 위젯과 상호작용할 수 있습니다.

아래 API를 사용하여 병원 홈페이지에서 KOS Connect 위젯과 상호작용 할 수 있습니다.

SDK 초기화​

npm 패키지를 설치하여 타입 안전한 SDK를 사용할 수 있습니다.

npm install @kos-solution/connect-sdk
import KOSConnect from '@kos-solution/connect-sdk';

KOSConnect.init('YOUR_APP_ID');

KOSConnect.open();
클라이언트 환경에서만 사용하세요

KOSConnect.init()은 내부적으로 <script> 태그를 주입하여 위젯을 로드합니다. Server Component나 SSR 환경에서는 동작하지 않으므로, 반드시 클라이언트 환경에서 호출하세요.

'use client';

import { useEffect } from 'react';
import KOSConnect from '@kos-solution/connect-sdk';

export default function KOSConnectInit() {
  useEffect(() => {
    KOSConnect.init('YOUR_APP_ID');
  }, []);

  return null;
}

개발 환경에서는 baseUrl 옵션을 사용하세요.

KOSConnect.init('YOUR_DEV_APP_ID', {
  baseUrl: 'https://connect.dev.kos-solution.com'
});
앱 아이디

개발 환경과 운영 환경의 앱 아이디는 서로 다릅니다. 각 환경에 맞는 앱 아이디를 사용하세요.

API 호출 시점

SDK 초기화 전에 API를 호출하면, 초기화 완료 후 순차적으로 실행됩니다.

위젯 열기​

KOSConnect.open()

닫혀있던 위젯을 엽니다.

  • 이미 열려있는 경우 아무 작업도 하지 않습니다.
  • 위젯이 열려도 화면 및 상태가 초기화되지 않습니다. 마지막으로 보던 화면이 유지됩니다.
  • 다른 화면을 열고 싶다면 startReserve 등 다른 API를 사용하세요.

위젯 닫기​

KOSConnect.close()

열려있던 위젯을 닫습니다.

  • 이미 닫혀있는 경우 아무 작업도 하지 않습니다.
  • 위젯이 닫혀도 화면 및 상태가 초기화되지 않습니다. 다시 열면 마지막으로 보던 화면이 유지됩니다.

언어 변경​

KOSConnect.setLanguage(language: 'ko' | 'ja')

KOS Connect 위젯의 표시 언어를 변경합니다.

  • setLanguage를 호출하지 않아도, KOS Connect는 사용자의 브라우저 언어 설정에 따라 자동으로 언어를 감지하여 표시합니다. 특정 언어로 강제 설정이 필요한 경우 이 명령을 사용하세요.
  • 지원하지 않는 언어 코드가 전달되면 무시됩니다.

파라미터​

language (required)​

표시할 언어 코드를 지정합니다.

값설명
'ko'한국어
'ja'일본어

탭 전환​

KOSConnect.changeTab({
  tab: 'schedule' | 'history' | 'myPage',
  open?: boolean
})

지정한 탭으로 전환합니다. 탭바가 표시되는 초기 페이지에 있을 때만 동작합니다.

  • 위젯이 열려 있지 않더라도, 초기 페이지 상태라면 탭이 전환됩니다.
  • 올바르지 않은 탭 식별자가 전달되면 명령은 무시됩니다.
  • 초기 페이지가 아닌 상태에서 open: true를 사용하면, 탭 전환 없이 위젯만 열립니다.

파라미터​

tab (required)​

전환할 탭을 지정합니다.

값설명
'schedule'예정
'history'내역
'myPage'마이페이지

open (optional)​

true로 설정하면 위젯이 닫혀 있을 때 자동으로 열립니다.

  • 기본값은 false입니다.

예약 시작하기​

KOSConnect.startReserve({
  cart?: undefined
    | { type: 'consultation' }
    | { type: 'items', items: Array<{ optionId: string } | { ticketId: string }> },
  date?: Date,
  visitor?: {
    name?: string,
    phoneticName?: string,
    gender?: 'MALE' | 'FEMALE' | 'UNSPECIFIED',
    nationality?: string,
    phoneNumber?: { countryCode: string, phoneNumber: string },
    email?: string
  }
})

신규 예약 흐름을 시작합니다. 위젯이 닫혀 있으면 자동으로 열립니다.

신규 예약 흐름​

신규 예약 흐름은 아래 단계로 구성됩니다.

  1. 희망 시술 선택
  2. 예약 일시 선택
  3. 예약 정보 입력
  4. 예약 완료

파라미터​

cart (optional)​

장바구니 초기 상태를 지정합니다. 값에 따라 시작 단계가 달라집니다. KOS Connect 장바구니에 담긴 항목을 기반으로 예약을 시작하려면 cart를 전달하지 않으면 됩니다.

값시작 단계설명
undefined희망 시술 선택내원객이 직접 희망 시술을 선택하거나 '상담 예약'을 선택합니다. 장바구니에 담긴 항목이 있다면 유지됩니다.
{ type: 'consultation' }예약 일시 선택'상담 예약'으로 진행됩니다. 기존 장바구니 항목은 무시됩니다.
{ type: 'items', items: [...] }예약 일시 선택지정한 항목이 장바구니에 담긴 상태로 진행됩니다. 기존 항목은 유지됩니다.

items 배열에는 다음 형식을 사용합니다.

  • { optionId: string }: 시술 옵션 ID
  • { ticketId: string }: 시술권 ID (추후 지원 예정)

date (optional)​

예약 일시 선택 단계에서 기본 선택되는 날짜를 지정합니다.

  • 전달하지 않으면 오늘 날짜가 기본 선택됩니다.
  • 시간 값은 무시되고 날짜만 적용됩니다.

visitor (optional)​

예약 정보 입력 단계에 표시할 내원객 정보 초기값입니다.

  • 내원객이 로그인된 상태라면 이 값은 무시됩니다.
  • 올바르지 않은 형식의 값은 무시됩니다.
필드타입설명
namestring내원객 이름
phoneticNamestring내원객 발음명. 일본의 경우 후리가나(振り仮名), 한국의 경우 외국인의 한국어 발음
gender'MALE' | 'FEMALE' | 'UNSPECIFIED'성별
nationalitystring국적 (ISO 3166-1 alpha-2 코드). 예: 'KR', 'JP', 'US'
phoneNumber{ countryCode: string, phoneNumber: string }연락처. countryCode는 국제전화 국가 번호(예: '82'), phoneNumber는 하이픈 없는 전화번호(예: '1012345678')
emailstring이메일

모든 필드는 선택 사항입니다.

장바구니 보기​

KOSConnect.showCart({
  open?: boolean
})

장바구니 바텀시트를 엽니다.

  • KOS Connect에 장바구니 버튼이 렌더링된 상태에서만 동작합니다.
  • 위젯이 닫혀 있는 상태에서 open: true를 사용하면, 위젯을 열고 장바구니 바텀시트를 표시합니다.

파라미터​

open (optional)​

true로 설정하면 위젯이 닫혀 있을 때 자동으로 열립니다.

  • 기본값은 false입니다.

장바구니에 담기​

KOSConnect.addToCart({
  options: [{ id: string }],
  silent?: boolean
})

지정한 시술 옵션을 장바구니에 추가합니다.

  • 로그인하지 않은 상태에서도 장바구니에 담을 수 있습니다.
  • 위젯이 닫혀 있어도 장바구니만 업데이트됩니다. 위젯은 자동으로 열리지 않습니다.
  • 기본적으로 토스트 알림이 표시됩니다. silent: true로 숨길 수 있습니다.
  • 이미 담긴 옵션 ID는 중복으로 추가되지 않습니다.
  • 유효하지 않은 옵션 ID는 무시되고, 유효한 항목만 반영됩니다.

장바구니에서 제거​

KOSConnect.removeFromCart({
  options: [{ id: string }],
  silent?: boolean
})

지정한 시술 옵션을 장바구니에서 제거합니다.

  • 로그인하지 않은 상태에서도 사용할 수 있습니다.
  • 위젯이 닫혀 있어도 장바구니만 업데이트됩니다. 위젯은 자동으로 열리지 않습니다.
  • 기본적으로 토스트 알림이 표시됩니다. silent: true로 숨길 수 있습니다.
  • 장바구니에 없는 옵션 ID는 무시됩니다.

장바구니 초기화​

KOSConnect.resetCart()

장바구니에 담긴 모든 시술 옵션을 삭제합니다.

  • 로그인하지 않은 상태에서도 사용할 수 있습니다.
  • 위젯이 닫혀 있어도 장바구니만 업데이트됩니다. 위젯은 자동으로 열리지 않습니다.
  • 장바구니가 이미 비어있는 경우 아무 작업도 하지 않습니다.