Table API

Toss POS에서 테이블 관리를 위한 API예요. 테이블 정보 조회, 퇴장 처리, 이벤트 구독 등의 기능을 제공해요.

주의사항

이 API는 POS에서 업종이 음식점 -> 후불형 매장일 때만 활성화돼요.

Types

PluginTable

테이블의 기본 정보를 나타내는 객체예요.

{
    id: number;           // 테이블 ID
    hallId: number;       // 테이블이 위치한 공간 ID
    title: string;        // 테이블명
    capacity?: number;       // 인원수
    group?: PluginTableGroup;  // 테이블 그룹 정보
}

필드	타입	필수	설명	예시
id	number	필수	테이블 ID	1
hallId	number	필수	테이블이 속한 홀의 ID (PluginHall.id)	1
title	string	필수	테이블명	'1번 테이블'
capacity	number	선택	테이블에 앉을 수 있는 인원 수	4
group	PluginTableGroup	선택	테이블 그룹 정보

PluginHall

테이블이 놓여진 공간(홀) 정보를 나타내는 객체예요. 각 테이블은 하나의 홀에 속하며, PluginTable.hallId로 어느 홀에 있는지 식별할 수 있어요.

{
    id: number;     // 공간 ID
    title: string;  // 공간명
    order: number;  // 순서값 (오름차순 정렬)
}

필드	타입	필수	설명	예시
id	number	필수	공간 ID	1
title	string	필수	공간명	'홀 A'
order	number	필수	순서값 (오름차순 정렬)	0

PluginTableGroup

테이블 그룹의 정보를 나타내는 객체예요.

{
    id: number;         // 그룹 ID
    color: string;      // 그룹 색상
    merchantId: number; // 매장 ID
    tableIds: number[]; // 그룹에 속한 테이블 ID 목록
}

필드	타입	필수	설명	예시
id	number	필수	그룹 ID	1
color	string	필수	그룹 색상	'#FF0000'
merchantId	number	필수	매장 ID	1
tableIds	number[]	필수	그룹에 속한 테이블 ID	[1, 2]

MovePayload

테이블 이동 이벤트의 페이로드 타입이에요.

{
    order: {
        id: number; // 이동된 주문 ID
    };
    from: {
        table: {
            id: number; // 이동 전 테이블 ID
        };
    };
    to: {
        table: {
            id: number; // 이동 후 테이블 ID
        };
    };
}

필드	타입	필수	설명
order.id	number	필수	이동된 주문 ID
from.table.id	number	필수	이동 전 테이블 ID
to.table.id	number	필수	이동 후 테이블 ID

MergePayload

테이블 합석 이벤트의 페이로드 타입이에요.

{
    from: {
        table: {
            id: number; // 합석 전 테이블 ID
        };
        order: {
            id: number; // 합석 전 주문 ID
        };
    };
    to: {
        table: {
            id: number; // 합석 후 테이블 ID
        };
        order: {
            id: number; // 합석 후 주문 ID
        };
    };
}

필드	타입	필수	설명
from.table.id	number	필수	합석 전 테이블 ID
from.order.id	number	필수	합석 전 주문 ID
to.table.id	number	필수	합석 후 테이블 ID
to.order.id	number	필수	합석 후 주문 ID

Methods

getHalls

매장의 전체 홀(공간) 목록을 조회해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

const halls = await posPluginSdk.table.getHalls();

getTable

매장의 전체 테이블 목록을 조회해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

/**
 * 테이블 조회
 */
const table = await posPluginSdk.table.getTable(tableId);

getTables

매장의 전체 테이블 목록을 조회해요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

/**
 * 테이블 목록 조회
 * @returns 테이블 배열
 */
const tables = await posPluginSdk.table.getTables();

테이블 비우기

테이블을 비우려면 posPluginSdk.order.complete()를 사용하세요.

on

이벤트 구독을 위한 메서드예요.

clear

테이블이 비워졌을 때 발생하는 이벤트예요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.table.on('clear', (id: number) => {
  console.log('비워진 테이블 ID:', id);
});

add

테이블이 새로 추가되었을 때 발생하는 이벤트예요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.table.on('add', (id: number) => {
  console.log('새로 추가된 테이블 ID:', id);
});

delete

테이블이 삭제되었을때 발생하는 이벤트예요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.table.on('delete', (id: number) => {
  console.log('삭제된 테이블 ID:', id);
});

update

테이블의 정보가 수정되었을 때 발생하는 이벤트예요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.table.on('update', (id: number) => {
  console.log('업데이트 된 테이블 ID:', id);
});

move

테이블이 이동되었을 때 발생하는 이벤트예요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.table.on('move', (payload: MovePayload) => {
  console.log('테이블 이동:', payload);
});

merge

테이블이 합석되었을 때 발생하는 이벤트예요.

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

posPluginSdk.table.on('merge', (payload: MergePayload) => {
  console.log('테이블 합석:', payload);
});

사용 예시

테이블 관리 클래스

import { posPluginSdk } from '@tossplace/pos-plugin-sdk';

class TableManager {
  private tables: PluginTable[] = [];

  /**
   * 테이블 목록 조회 및 초기화
   */
  async initialize() {
    try {
      this.tables = await posPluginSdk.table.getTables();
      this.setupEventListeners();
    } catch (error) {
      console.error('테이블 초기화 실패:', error);
    }
  }

  /**
   * 이벤트 리스너 설정
   */
  private setupEventListeners() {
    posPluginSdk.table.on('clear', this.handleTableClear.bind(this));
    posPluginSdk.table.on('add', this.handleTableAdd.bind(this));
    posPluginSdk.table.on('delete', this.handleTableDelete.bind(this));
    posPluginSdk.table.on('update', this.handleTableUpdate.bind(this));
    posPluginSdk.table.on('move', this.handleTableMove.bind(this));
    posPluginSdk.table.on('merge', this.handleTableMerge.bind(this));
  }

  private handleTableClear(id: number) {
    console.log('테이블 비우기 ID:', id);
  }

  private handleTableAdd(id: number) {
    console.log('테이블 추가 ID:', id);
  }

  private handleTableDelete(id: number) {
    console.log('테이블 삭제 ID:', id);
  }

  private handleTableUpdate(id: number) {
    console.log('테이블 업데이트 ID:', id);
  }

  private handleTableMove(payload: MovePayload) {
    console.log('테이블 이동:', payload);
  }

  private handleTableMerge(payload: MergePayload) {
    console.log('테이블 합석:', payload);
  }

}

// 사용 예시
async function manageTables() {
  const tableManager = new TableManager();
  await tableManager.initialize();
}