Open API 소개

토스플레이스 Open API는 서버 간 안정적인 데이터 연동을 위한 API예요. POS 시스템의 주문, 결제, 상품 정보에 안전하게 접근할 수 있어요.

주요 특징

• 서버 간 통신: 안정적인 서버 간 데이터 연동
• 실시간 데이터: 주문, 결제, 상품 정보를 실시간으로 조회
• 웹훅(Webhook): 매장 이벤트 발생 시 서버로 실시간 알림 수신
• 보안: API 인증으로 안전한 데이터 접근

주요 기능과 활용 사례

Open API는 외부 솔루션 서버와 토스플레이스 서버가 통신하는 방식이에요. 앱이 설치된 매장의 기본 정보와 주문·결제·카탈로그·할인 정보를 조회하고, 지원되는 범위에서 주문·배달 데이터를 기록하거나 웹훅으로 상태 변화를 동기화할 수 있어요.

데이터 연동 구조

• API 요청: 외부 솔루션 서버에서 Open API를 호출해 앱이 설치된 매장의 데이터를 조회해요.
• 데이터 기록: 주문 생성은 별도 승인을 받은 앱에서 사용할 수 있고, 배달 정보 등록·수정·완료는 Open API로 생성한 주문에만 지원돼요.
• 웹훅 수신: 토스플레이스에서 발생한 주문·결제·상품 등의 지원 이벤트를 외부 솔루션 서버로 전달해요.

매장 운영 정보

• 매장: 매장명, 사업자등록번호, 주소, 영업시간 등 기본 정보를 조회하고 변경 이벤트를 받아요.
• 카탈로그: 상품, 카테고리, 옵션 정보를 조회하고 생성·수정·삭제 이벤트를 받아요.
• 할인: 상품 또는 카테고리에 자동 적용할 수 있는 할인 정책을 확인해요.

거래 정보

• 주문: 주문 내역과 상태를 조회해요. 주문 생성 권한을 받은 앱은 외부 주문을 토스 POS에 생성하고, Open API로 생성한 주문을 상태에 따라 수락·거절·취소할 수 있어요.
• 결제: 주문별 결제 내역을 조회하고 승인·취소 이벤트를 받아요.
• 배달: 배달 정보를 조회하고, Open API로 생성한 주문의 배달 정보를 등록·수정·완료 처리해요.

실시간 동기화

개발자센터에 웹훅 수신 주소와 이벤트를 등록하면 주문·결제·상품 등의 변경 이벤트를 HTTP POST 요청으로 받아요. 여러 매장의 이벤트는 merchantId로 구분하고, x-toss-webhook-id를 기준으로 중복 처리를 방지해요.

적용 사례

외부 주문을 토스 POS로 전달해요

주문 생성 권한을 받은 앱에서 사내 앱이나 ERP로 만든 주문을 토스 POS에 전달하고, 매장에서 결제를 이어서 진행해요.

적용 사례: 컴포즈커피 앱오더, 하이브 사내카페

매장 운영 데이터를 분석해요

주문·결제 데이터를 외부 솔루션에 연동해 매장 현황, 매출 리포트, 운영 분석에 활용해요.

적용 사례: 토더, 버핏그라운드

전자 가격표를 동기화해요

토스 POS의 상품·할인 정보를 조회해 ESL 전자 가격표의 상품명과 가격을 관리해요.

적용 사례: 한아원, 에브리씬, 텔리카

웹훅 HTTP 전송 규약과 서명 검증 방법은 웹훅 가이드를 참고하세요.