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]

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();

clearTable

테이블을 퇴장 처리합니다.

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

/**
 * 테이블 퇴장 처리
 * @param table 퇴장 처리할 테이블 정보
 */
const tables = await posPluginSdk.table.getTables();
const table = tables.find((table) => table.id === 1);
await posPluginSdk.table.clearTable({ table });

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', (before: number, after: number) => {
  console.log('테이블 이동:', { from: before, to: after });
});

사용 예시

테이블 관리 클래스

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));
  }

  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(before: number, after: number) {
    console.log('테이블 이동:', { from: before, to: after });
  }

  /**
   * 테이블 퇴장 처리
   * @param tableId 테이블 ID
   */
  async clearTable(tableId: number) {
    const table = this.tables.find((t) => t.id === tableId);
    if (table) {
      await posPluginSdk.table.clearTable({ table });
    }
  }
}

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