KDS Order API

주방 디스플레이 시스템(KDS)의 주문을 조회하고, 주문 상태 변경 이벤트를 수신하는 API예요.

Types

PluginKdsOrderItem

KDS 주문 항목을 나타내는 객체예요.

{
  id: string;                                    // KDS 주문 항목 ID
  state: PluginKdsOrderItemState;                // KDS 주문 상태
  order: PluginOrder;                            // 주문 정보
  lineItems: PluginKdsLineItem[];                // 주문 메뉴 목록
  diningOption: 'HERE' | 'TOGO' | 'DELIVERY' | 'PICKUP';  // 주문 방식
  totalQuantity: number;                         // 총 수량
  orderRequestType: PluginKdsOrderRequestType;   // 주문 요청 유형
  cancelledAt: string;                           // 취소 시간
  completedAt: string;                           // 완료 시간
  createdAt: string;                             // 생성 시간
  updatedAt: string;                             // 수정 시간
}

Name	Type	Optional	Description	Example
id	string	false	KDS 주문 항목 ID	'kds-1'
state	PluginKdsOrderItemState	false	KDS 주문 상태	'OPENED'
order	PluginOrder	false	원본 주문 정보
lineItems	PluginKdsLineItem[]	false	KDS 주문의 메뉴 목록
diningOption	'HERE' | 'TOGO' | 'DELIVERY' | 'PICKUP'	false	주문 방식	'HERE'
totalQuantity	number	false	총 주문 수량	3
orderRequestType	PluginKdsOrderRequestType	false	주문 요청 유형	'NEW'
cancelledAt	string	false	취소 시간	'2025-01-01T00:00:00'
completedAt	string	false	완료 시간	'2025-01-01T00:00:00'
createdAt	string	false	생성 시간	'2025-01-01T00:00:00'
updatedAt	string	false	수정 시간	'2025-01-01T00:00:00'

PluginKdsOrderItemState

KDS 주문 항목의 상태예요.

값	설명
OPENED	진행 중 (주방에서 처리 대기 또는 처리 중)
COMPLETED	완료 (조리 완료)
CANCELLED	취소

PluginKdsOrderRequestType

KDS 주문의 요청 유형이에요.

값	설명
NEW	신규 주문
ADDED	추가 주문
CHANGED	변경된 주문
CANCELLED	취소된 주문
MERGED	합석/병합된 주문

PluginKdsLineItem

KDS 주문 항목의 개별 메뉴 정보예요.

{
  id: string;                             // 메뉴 항목 ID
  itemId: string;                         // 상품 ID
  title: string;                          // 상품명
  diningOption: 'HERE' | 'TOGO' | 'DELIVERY' | 'PICKUP';  // 주문 방식
  memo: string;                           // 메모
  optionChoices: PluginOrderItemOptionChoice[];  // 선택된 옵션
  orderPrice: {
    orderDiscountValue: number;           // 할인 금액
    orderListPriceValue: number;          // 정가
    orderPriceValue: number;              // 실제 결제 금액
  };
  quantity: {
    previous: number;                     // 이전 수량
    current: number;                      // 현재 수량
  };
  appliedDiscounts: PluginDiscount[];     // 적용된 할인 목록
  item: {
    id: number;                           // 상품 ID
    category: {
      id: number;                         // 카테고리 ID
      order: number;                      // 카테고리 순서
    };
  };
  createdAt: string;                      // 생성 시간
  updatedAt: string;                      // 수정 시간
}

Name	Type	Optional	Description	Example
id	string	false	메뉴 항목 ID	'line-1'
itemId	string	false	상품 ID	'item-1'
title	string	false	상품명	'아메리카노'
diningOption	'HERE' | 'TOGO' | 'DELIVERY' | 'PICKUP'	false	주문 방식	'HERE'
memo	string	false	메뉴 메모	'샷 추가'
optionChoices	PluginOrderItemOptionChoice[]	false	선택된 옵션
orderPrice.orderDiscountValue	number	false	할인 금액	1000
orderPrice.orderListPriceValue	number	false	정가	5000
orderPrice.orderPriceValue	number	false	실제 결제 금액	4000
quantity.previous	number	false	이전 수량 (변경 전)	1
quantity.current	number	false	현재 수량	2
appliedDiscounts	PluginDiscount[]	false	적용된 할인 목록
item.id	number	false	상품 ID	1
item.category.id	number	false	카테고리 ID	10
item.category.order	number	false	카테고리 정렬 순서	1
createdAt	string	false	생성 시간	'2025-01-01T00:00:00'
updatedAt	string	false	수정 시간	'2025-01-01T00:00:00'

Methods

on

KDS 주문 상태 변경 이벤트를 수신하기 위한 핸들러를 등록해요. 콜백은 KDS 주문 항목 ID(string)를 전달받아요.

open

KDS 주문이 새로 접수(오픈)되었을 때 실행돼요.

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

posPluginSdk.kdsOrder.on('open', (id: string) => {
  console.log('접수된 KDS 주문 ID:', id);
});

complete

KDS 주문이 완료(조리 완료)되었을 때 실행돼요.

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

posPluginSdk.kdsOrder.on('complete', (id: string) => {
  console.log('완료된 KDS 주문 ID:', id);
});

cancel

KDS 주문이 취소되었을 때 실행돼요.

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

posPluginSdk.kdsOrder.on('cancel', (id: string) => {
  console.log('취소된 KDS 주문 ID:', id);
});

getKdsOrderItems

KDS 주문 항목 목록을 조회해요. 상태, 주문 ID, 카테고리, 상품 등 다양한 조건으로 필터링할 수 있어요.

페이징은 결과의 last가 true가 될 때까지 조회하면 완료돼요.

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

const result = await posPluginSdk.kdsOrder.getKdsOrderItems({
  page: 1,
  size: 20,
  states: ['OPENED'],
});

Parameters

파라미터	타입	필수	설명
page	number	O	페이지 번호 (1부터 시작)
size	number	O	페이지당 결과 수
states	PluginKdsOrderItemState[]	X	KDS 주문 상태 필터. 지정하지 않으면 전체 상태 조회
orderIds	string[]	X	특정 주문 ID 목록으로 필터링
categoryIds	number[]	X	특정 카테고리 ID 목록으로 필터링
itemIds	number[]	X	특정 상품 ID 목록으로 필터링

Response

필드	타입	설명
contents	PluginKdsOrderItem[]	KDS 주문 항목 목록
last	boolean	마지막 페이지 여부
totalElements	number	전체 항목 수

사용 예시

KDS 주문 실시간 모니터링

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

posPluginSdk.kdsOrder.on('open', async (id: string) => {
  const result = await posPluginSdk.kdsOrder.getKdsOrderItems({
    page: 1,
    size: 20,
    states: ['OPENED'],
  });

  const kdsItem = result.contents.find((item) => item.id === id);
  if (kdsItem != null) {
    console.log('새 주문 접수:', kdsItem.lineItems.map((li) => li.title));
  }
});

진행 중인 KDS 주문 전체 조회

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

async function getAllOpenedKdsOrders() {
  const allItems = [];
  let page = 1;

  while (true) {
    const result = await posPluginSdk.kdsOrder.getKdsOrderItems({
      page,
      size: 20,
      states: ['OPENED'],
    });

    allItems.push(...result.contents);

    if (result.last) {
      break;
    }

    page++;
  }

  return allItems;
}