Catalog API

Toss POS 플러그인에서 매장의 메뉴 정보를 관리하는 API입니다. 메뉴의 기본 정보, 가격, 옵션 등을 포함하여 종합적인 메뉴 관리를 제공합니다.

Types

PluginCatalogItem

메뉴의 기본 정보를 나타내는 객체입니다.

{
    id: number;              // 메뉴의 고유 ID
    title: string;           // 메뉴명
    titleI18n?: PluginLanguagePack;  // 다국어 지원 메뉴명
    state: 'ON_SALE' | 'SOLD_OUT' | 'UNAVAILABLE' | 'DELETED';  // 메뉴 상태
    description?: string;    // 메뉴 설명
    descriptionI18n?: PluginLanguagePack;  // 다국어 지원 설명
    category: PluginCatalogCategory;  // 메뉴 카테고리
    labels: {                // 메뉴 라벨
        title: string;       // 라벨명
        color: string;       // 라벨 색상
    }[];
    imageUrl: string | null;  // 메뉴 이미지 URL
    price: PluginCatalogItemPrice;  // 가격 정보
    options: PluginCatalogItemOption[];  // 옵션 목록
}

필드	타입	필수	설명	예시
id	number	필수	메뉴의 고유 ID	1
title	string	필수	메뉴명	'아메리카노'
titleI18n	PluginLanguagePack	선택	다국어 지원 메뉴명
state	'ON_SALE' | 'SOLD_OUT' | 'UNAVAILABLE' | 'DELETED'	필수	메뉴 상태	'ON_SALE'
description	string	선택	메뉴 설명	'아메리카노'
descriptionI18n	PluginLanguagePack	선택	다국어 지원 설명
category	PluginCatalogCategory	필수	메뉴 카테고리
labels.title	string	필수	라벨명	'HOT'
labels.color	string	필수	라벨 색상	'#FF0000'
imageUrl	string	선택	메뉴 이미지 URL	'https://toss.imimages/americano.png'
price	PluginCatalogItemPrice	필수	가격 정보
options	PluginCatalogItemOption[]	필수	옵션 목록

PluginCatalogItemPrice

메뉴의 가격 정보를 나타내는 객체입니다.

{
    id: number;              // 가격 ID
    title: string;           // 가격명
    isDefault: boolean;      // 기본 가격 여부
    state: 'ON_SALE' | 'SOLD_OUT' | 'UNAVAILABLE' | 'DELETED';  // 가격 상태
    sku: string | null;      // 재고 관리 코드
    barcode: string | null;  // 바코드 정보
    priceType: 'FIXED' | 'VARIABLE' | 'UNIT';  // 가격 유형 (unit : kg당 가격)
    priceUnit: number;       // 기본 수량
    priceValue: number;      // 부가세 포함 가격
    isTaxFree: boolean;      // 비과세 여부
    isStockable: boolean;    // 재고 관리 여부
    stockQuantity: {         // 재고 정보
        remainQuantity: number;      // 현재 재고
        lastChangeDateTime: string;  // 마지막 변경 시간
    } | null;
}

필드	타입	필수	설명	예시
id	number	필수	가격 ID	1
title	string	필수	가격명	'기본가격'
isDefault	boolean	필수	기본 가격 여부	true
state	'ON_SALE' | 'SOLD_OUT' | 'UNAVAILABLE' | 'DELETED'	필수	가격 상태	'ON_SALE'
sku	string	선택	재고 관리 코드	'123456'
barcode	string	선택	바코드 정보	'123456'
priceType	'FIXED' | 'VARIABLE' | 'UNIT'	필수	가격 유형	'FIXED'
priceUnit	number	필수	기본 수량	1
priceValue	number	필수	부가세 포함 가격	10000
isTaxFree	boolean	필수	비과세 여부	false
isStockable	boolean	필수	재고 관리 여부	true
stockQuantity.remainQuantity	number	필수	현재 재고	10
stockQuantity.lastChangeDateTime	string	필수	마지막 변경 시간	'2021-01-01T00:00:00Z'

Methods

getCatalog

매장의 카탈로그를 조회합니다.

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

/**
 * 카탈로그 목록 조회
 * @returns 카탈로그 목록
 */
const catalog = await posPluginSdk.catalog.getCatalog(catalogId);

getCatalogs

매장의 카탈로그 목록을 조회합니다.

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

/**
 * 카탈로그 목록 조회
 * @returns 카탈로그 목록
 */
const catalogs = await posPluginSdk.catalog.getCatalogs();

on

이벤트 구독을 위한 메서드입니다.

sold-out

메뉴가 품절되었을 때 발생하는 이벤트입니다.

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

posPluginSdk.catalog.on('sold-out', (catalog: PluginCatalogItem) => {
    console.log('품절된 메뉴:', catalog.title);
});

on-sale

메뉴가 판매 가능 상태로 변경되었을 때 발생하는 이벤트입니다.

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

posPluginSdk.catalog.on('on-sale', (catalog: PluginCatalogItem) => {
    console.log('판매 가능 상태로 변경된 메뉴:', catalog.title);
});

update

메뉴의 정보가 업데이트되었을 때 발생하는 이벤트입니다.

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

posPluginSdk.catalog.on('update', (catalog: PluginCatalogItem) => {
    console.log('정보가 업데이트 된 메뉴:', catalog.title);
});

add

메뉴가 추가되었을 때 발생하는 이벤트입니다

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

posPluginSdk.catalog.on('add', (catalog: PluginCatalogItem) => {
    console.log('새로 추가 된 메뉴:', catalog.title);
});

delete

메뉴가 삭제되었을 때 발생하는 이벤트입니다

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

posPluginSdk.catalog.on('delete', (catalog: PluginCatalogItem) => {
    console.log('삭제 된 메뉴:', catalog.title);
});

사용 예시

카탈로그 관리 클래스

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

class CatalogManager {
    private catalogs: PluginCatalogItem[] = [];

    /**
     * 카탈로그 목록 조회 및 초기화
     */
    async initialize() {
        try {
            this.catalogs = await posPluginSdk.catalog.getCatalogs();
            this.setupEventListeners();
        } catch (error) {
            console.error('카탈로그 초기화 실패:', error);
        }
    }

    /**
     * 이벤트 리스너 설정
     */
    private setupEventListeners() {
        posPluginSdk.catalog.on('sold-out', this.handleSoldOut.bind(this));
        posPluginSdk.catalog.on('on-sale', this.handleOnSale.bind(this));
    }

    /**
     * 품절 이벤트 처리
     * @param catalog 품절된 메뉴 정보
     */
    private handleSoldOut(catalog: PluginCatalogItem) {
        console.log('품절 알림:', catalog.title);
        // 품절 처리 로직
    }

    /**
     * 판매 가능 이벤트 처리
     * @param catalog 판매 가능 상태로 변경된 메뉴 정보
     */
    private handleOnSale(catalog: PluginCatalogItem) {
        console.log('판매 가능 알림:', catalog.title);
        // 판매 가능 처리 로직
    }

    /**
     * 메뉴 정보 조회
     * @param menuId 메뉴 ID
     * @returns 메뉴 정보
     */
    getMenu(menuId: number): PluginCatalogItem | undefined {
        return this.catalogs.find(menu => menu.id === menuId);
    }
}

// 사용 예시
async function manageCatalog() {
    const catalogManager = new CatalogManager();
    await catalogManager.initialize();
}

재고 관리 예시

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

/**
 * 재고 상태 확인
 * @param catalog 메뉴 정보
 * @returns 재고 상태 메시지
 */
function checkStockStatus(catalog: PluginCatalogItem): string {
    const price = catalog.price;
    if (!price.isStockable || !price.stockQuantity) {
        return '재고 관리 대상이 아닙니다.';
    }

    const { remainQuantity } = price.stockQuantity;
    if (remainQuantity <= 0) {
        return '품절';
    } else if (remainQuantity <= 5) {
        return `재고 부족 (${remainQuantity}개 남음)`;
    }
    return `재고 있음 (${remainQuantity}개)`;
}

// 사용 예시
async function monitorStock() {
    const catalogs = await posPluginSdk.catalog.getCatalogs();
    catalogs.forEach(catalog => {
        const status = checkStockStatus(catalog);
        console.log(`${catalog.title}: ${status}`);
    });
}
// 품절 이벤트 구독
posPluginSdk.catalog.on("sold-out", (catalog) => {
  console.log("품절된 메뉴:", catalog.title);
});

// 판매중 이벤트 구독
posPluginSdk.catalog.on("on-sale", (catalog) => {
  console.log("판매중으로 변경된 메뉴:", catalog.title);
});