팝업레이어 알림
팝업레이어 알림이 없습니다.
채널이 곧 쇼핑몰!
텔레그램 상품 카탈로그 및 주문 관리 봇 구축 가이드
텔레그램 Bot API의 Inline Keyboard와 결제 시스템을 결합하여 상품 등록, 장바구니, 주문 접수, 상태 관리까지 완전 자동화된 커머스 봇을 구축하는 전체 프로세스를 학습합니다.
텔레그램 봇은 단순한 자동 응답 도구를 넘어, 완전한 전자상거래 플랫폼으로 활용할 수 있습니다. Inline Keyboard UI를 통해 상품 카탈로그를 구성하고, Callback Query로 장바구니 로직을 처리하며, 스타즈 또는 외부 결제 시스템을 연동하면 별도의 쇼핑몰 웹사이트 없이도 채널 안에서 상품 주문부터 배송 추적까지 모든 것을 자동화할 수 있습니다.
이 가이드에서는 상품 데이터 설계부터 봇 개발, 주문 상태 관리, 재고 추적까지의 전체 구축 과정을 설명하고, 하단의 주문 관리 시뮬레이터에서 상품 브라우징 -> 장바구니 담기 -> 주문 접수 -> 상태 변경까지 실제 운영 플로우를 체험할 수 있습니다.
텔레그램 커머스 봇은 3계층 구조로 설계합니다: (1) 프론트엔드(Inline Keyboard UI), (2) 비즈니스 로직(장바구니/주문 처리), (3) 데이터 계층(상품/재고/주문 DB). 모든 사용자 인터랙션은 Callback Query를 통해 처리되므로, 메시지를 새로 보내지 않고도 기존 메시지의 키보드를 실시간으로 업데이트할 수 있습니다.
| 계층 | 역할 | 핵심 API/기술 |
|---|---|---|
| UI 계층 | 상품 목록, 장바구니, 주문 확인 화면 렌더링 | InlineKeyboardMarkup, editMessageText |
| 로직 계층 | 장바구니 CRUD, 가격 계산, 재고 차감, 주문 생성 | CallbackQuery, answerCallbackQuery |
| 데이터 계층 | 상품 정보, 재고 수량, 주문 내역, 고객 정보 저장 | SQLite/PostgreSQL, Redis (세션) |
| 결제 계층 | 결제 요청/확인, 환불 처리 | sendInvoice, Stars (XTR) |
상품 카탈로그의 기본 데이터 구조를 설계합니다. 각 상품에는 고유 ID, 이름, 설명, 가격(Stars 단위), 카테고리, 재고 수량, 이미지 URL이 포함됩니다. JSON 또는 DB 테이블로 관리하며, 봇 시작 시 메모리에 로드합니다.
Bot API의 InlineKeyboardMarkup을 활용하여 상품 목록을 버튼 형태로 표시합니다. 각 버튼의 callback_data에 "add_카테고리_상품ID" 형식의 식별자를 넣어 사용자가 클릭하면 어떤 상품을 선택했는지 서버에서 파싱할 수 있도록 합니다.
각 사용자(chat_id)별로 장바구니 세션을 메모리 또는 Redis에 유지합니다. 상품 추가/삭제/수량 변경 시 editMessageReplyMarkup으로 기존 메시지의 키보드를 실시간 갱신하여 페이지 전환 없이 부드러운 UX를 제공합니다.
장바구니 확인 후 "주문하기" 버튼을 누르면 sendInvoice API로 결제를 요청합니다. 스타즈(XTR) 결제가 완료되면 successful_payment 이벤트에서 주문을 DB에 기록하고, 재고를 차감하며, 관리자에게 새 주문 알림을 전송합니다.
주문은 접수 -> 준비중 -> 배송중 -> 완료 4단계로 관리합니다. 관리자가 봇의 관리 패널에서 상태를 변경하면 고객에게 자동으로 상태 변경 알림이 전송됩니다. sendMessage와 Inline Keyboard를 조합하여 고객이 실시간으로 주문 상태를 확인할 수 있게 합니다.
lightbulbWebhook vs Polling
상용 커머스 봇은 반드시 Webhook 모드로 운영하세요. Long Polling 방식은 동시 주문 처리 시 지연이 발생할 수 있습니다. Webhook은 텔레그램 서버가 이벤트 발생 즉시 여러분의 서버로 HTTP POST를 보내므로 실시간 응답이 가능합니다.
아래 시뮬레이터에서 상품을 장바구니에 담고 주문을 접수한 뒤, 주문 상태를 단계별로 변경해 보세요. 실제 텔레그램 커머스 봇과 동일한 운영 플로우를 체험할 수 있습니다.
상품 탭에서 담기 -> 장바구니에서 주문 -> 주문내역에서 상태 변경
> Commerce Bot Simulator 초기화 완료.
> 상품 6종 로드됨. 재고 확인 완료.
> 상품을 장바구니에 담고 주문을 접수해 보세요.
실시간 재고 관리는 커머스 봇의 핵심입니다. 주문 접수 시 즉시 재고를 차감하고, 재고가 0이 되면 해당 상품의 "담기" 버튼을 비활성화하여 과매도를 방지해야 합니다.
| 재고 이벤트 | 처리 로직 | 사용자 알림 |
|---|---|---|
| 정상 재고 | 주문 접수 즉시 재고 차감 | 주문 확인 메시지 |
| 재고 부족 (5개 이하) | 관리자에게 입고 필요 알림 | "곧 품절 예정" 표시 |
| 품절 (0개) | "담기" 버튼 비활성화, Inline Keyboard 갱신 | "일시 품절" 배지 표시 |
| 주문 취소/환불 | 재고 수량 복구 | 환불 완료 메시지 |
warning동시 주문 Race Condition 주의
여러 사용자가 동시에 마지막 1개 남은 상품을 주문할 경우 Race Condition이 발생합니다. DB 트랜잭션 또는 Redis의 원자적 감소 연산(DECR)을 사용하여 재고 차감의 원자성을 보장하세요.
텔레그램 커머스 봇은 별도의 웹사이트 구축 없이 채널 안에서 완전한 쇼핑 경험을 제공합니다. 소규모 크리에이터 마켓부터 중소 규모의 디지털 상품 판매까지, Bot API의 Inline Keyboard와 결제 시스템만으로 충분히 구현 가능합니다.
시뮬레이터에서 체험한 상품 브라우징, 장바구니, 주문 접수, 상태 변경 플로우를 실제 봇 코드로 옮기면 바로 운영 가능한 커머스 봇이 완성됩니다. Python(python-telegram-bot) 또는 Node.js(grammY)로 시작하여 점차 기능을 확장해 보세요.
lightbulb관련 가이드 연계 학습
상품 결제를 스타즈로 처리하려면 Bot API 결제 연동 방법을 함께 익혀 두세요.
텔레그램 비즈니스 스타즈(Stars) 결제 연동 및 디지털 상품 판매 가이드 보러 가기
텔레그램 비즈니스 챗봇(Business Bots) 연동 가이드
커머스 봇과 함께 24시간 무인 CS 응대 봇을 연동하면 주문 문의, 배송 확인, 환불 처리까지 완전 자동화된 비즈니스를 운영할 수 있습니다.
smart_toy챗봇 연동 가이드 보러 가기