개발관련 문의 : tech-support@rapportlabs.kr
API 규격서는 별도 문의 부탁드립니다.
1. 서비스 소개
셀러 API는 퀸잇이 제공하는 셀러 어드민 서비스의 주요 기능들로 연동사에서 원활하게 연동할 수 있도록 지원하고 있습니다.
효율적으로 상품을 관리하고, 고객 주문을 처리하며 배송 관리를 체계적으로 운영할 수 있습니다.
1.1 주요 연동 FLOW
2. 사전 준비 사항
2.1 셀러 계정 발급 안내
토큰 발급을 위해서는 셀러 계정 발급이 필요합니다.
테스트(개발) 환경의 경우, 퀸잇 Tech Support 팀에서 테스트 계정을 발급해 드립니다.
tech-support@rapportlabs.kr 로 연락 바랍니다.
2.2 도메인 및 Header 설정
API 도메인
•
테스트(개발) : https://seller.api.dev.queenit.kr
•
운영 : https://seller.api.queenit.kr
Header 설정
•
Authorization : Bearer {Access Token}
2.3 방화벽
연동사단 outbound 방화벽 설정(연동사 > 퀸잇 API 호출시 노출되는 도메인)
•
도메인에 연결된 IP는 수시 변동될 수 있으므로 퀸잇 API 도메인으로 API 호출 요청드립니다.
그리고 요청 IP에 대한 접근 제어는 따로 하고 있지 않습니다.
2.4 퀸잇 테스트(개발) 환경 주문 방법
•
마이 탭 관리자 도구 > Development 서버 선택
2. 회원 가입
•
카카오로 시작하기
•
휴대폰 인증으로 시작
◦
인증번호 : 111111 고정 값
3. 상품 구매하기
•
홈 탭 > 상품 선택 > 주문
•
주문 상세 페이지 > 결제 수단 결제테스트 선택 > 결제
3. API 별 상세 가이드
3.1 API 인증 토큰 발급
퀸잇 셀러어드민 API에 접근하기 위해서는 JWT 인증 토큰을 통해 리소스 접근이 가능합니다.
Tech Support팀으로부터 발급 받은 계정 정보를 활용하여 로그인API를 요청하시면 됩니다.
토큰 만료 시간 :
•
액세스 토큰 : 2시간 , 리프레시 토큰 : 1일
•
로그인 시 발급되는 JWT 토큰은 디코딩하여 토큰 만료 시간(exp) 값을 확인할 수 있습니다.
◦
토큰 만료 시간(exp) 값은 상황에 따라 변경될 수 있습니다.
API 인증 토큰 발급 프로세스
3.2 상품
상품 등록 시, 필요한 정보를 입력하거나 조회 하는 API 입니다.
사전에 필요한 주요 정보를 조회/생성 후 상품을 등록해 주시면 됩니다.
상품 등록 이후 상품 노출(SUBMIT)까지 완료되어야 앱에 노출됩니다.
상품 등록 API 연동 프로세스
3.3 주문 및 배송
접수된 주문 건의 확인, 상품의 출고 처리, 배송 상태 변경을 담당하는 API 입니다.
주문의 배송 상태(deliveryState)
- WAIT : 주문 처리 대기중
- PREPARING : 배송 준비중 (송장 정보 등록 가능)
- IN_DELIVERY : 배송중
- COMPLETED : 배송 완료
- CANCELLED : 배송 취소됨 (취소 요청을 처리 완료해서 환불 완료된 경우에 이 상태를 갖게 됩니다)
Plain Text
복사
주문 및 배송 API 연동 프로세스
배송 상태에 따른 액터(Actor) 별 허용 액션 목록
3.4 취소
취소 요청 상태인 주문을 조회하고, 취소 요청 승인 및 환불처리 또는 취소 요청을 반려하는 API 입니다.
주문의 취소 요청 상태(ticketState)
- SUBMITTED : 취소 요청이 최소로 생겼을 때의 초기 상태 (취소 요청됨)
- RESOLVED : 취소 요청이 처리 완료된 상태 (환불 완료)
- WITHDRAWN : 사용자가 취소 요청을 철회한 상태
- REJECTED : 입점사가 사용자의 취소 요청을 철회한 상태
Plain Text
복사
주문 취소 API 연동 프로세스
3.5 반품
반품 요청 상태인 주문을 조회하고, 반품 요청 승인 및 환불 등을 처리하는 API 입니다.
주문의 취소(반품) 요청 상태(ticketState)
- SUBMITTED: 취소(반품)가 요청됨
- CONFIRMED: 취소(반품) 요청을 승인함 (처리 진행 중)
- RESOLVED: 취소(반품) 요청이 종결됨 (고객에게 금액 환불됨)
- WITHDRAWN: 취소(반품) 요청을 고객이 철회함
- REJECTED: 취소(반품) 요청을 셀러/어드민이 반려함
Plain Text
복사
주문 반품 API 연동 프로세스
3.6 교환
교환 요청 상태의 주문을 조회하고, 교환 상품의 수거, 검수 및 배송 준비 과정을 처리하는 API 입니다.
•
주문의 교환 요청 상태(processState)
- REQUESTED: 교환 요청됨
- WITHDRAWN: 교환 요청을 고객이 철회함
- REQUEST_WAITED: 교환 요청 보류함
- CONFIRMED: 교환 요청 승인 및 배송 준비 중
- COLLECTING: 회수 중
- COLLECTED: 회수 완료(검수 중)
- INSPECTED_WAITED: 교환 검수 보류함
- INSPECTED: 교환 검수 승인 및 배송 준비 중
- IN_DELIVERY:배송 중
- COMPLETED: 완료
Plain Text
복사
주문 교환 API 연동 프로세스
#참고 : 퀸잇 셀러 어드민 교환 메뉴 가이드
4. 용어 사전
브랜드
퀸잇에서 관리하는 브랜드 입니다.
•
퀸잇에서는 브랜드, 브랜드 소싱, 셀러 3개의 개념이 있습니다.
•
브랜드는 해당 상품의 브랜드, 셀러는 해당 브랜드를 판매하는 공급사, 브랜드 소싱은 브랜드와 셀러를 이어주는 개념입니다.
•
서로 다른 셀러가 동일한 브랜드의 상품을 판매할 수 있으며, 각 셀러사에 해당 브랜드에 대한 고유한 브랜드코드를 퀸잇에서 발급합니다.
•
여기에서 LIST가 퀸잇 브랜드 ID 입니다.
브랜드 소싱
각 셀러사 별로 해당 브랜드에 해당하는 브랜드 코드입니다.
•
퀸잇에서 발급해드리며, 이 코드 정보를 연동사 내부 브랜드와 연결 해주셔야 합니다.
•
셀러사코드_브랜드ID와 유사한 포맷으로 발급해드립니다.
•
배송 정책은 브랜드 별로 관리가 가능하며, 이 때 브랜드 코드를 키로 등록하실 수 있습니다.
Order, OrderLine Group, OrderLine
•
order : 고객이 주문한 모든 상품을 하나의 단위로 묶은 최상위 개념입니다.
•
orderLineGroup : Order 내에서 합배송이 가능한 상품들끼리 묶어놓은 단위입니다. 한 박스에 담길 수 있는 상품들을 의미하며, 하나의 배송 단위로 볼 수 있습니다.
•
OrderLine : OrderLineGroup 내에 속하는 개별 상품을 의미합니다.
구매 확정
•
배송완료일 기준 8일째 구매확정이 되며, 상품 구매 확정 정산 기준일이 됩니다.
반품
유저가 구매이후 단순변심/상품훼손 등의 사유로 상품을 돌려받고 금액을 환불받는 과정을 의미합니다.
•
소비자 책임 소지인 경우에 반품 비용이 발생할 수 있으며, 무료 반품(교환) 프로모션 등 행사에 따라 일부 반품비를 유저가 부담하지 않는 경우가 있습니다. 이 경우에는 퀸잇 부담으로 정산 유형(무료 반품 행사보상 등)으로 구분되어 집니다.
•
반품비는 유저에게 환불해줘야 하는 금액에서 차감하는 방식으로 징수합니다.
•
반품은 반품티켓이란 단위를 통해서 관리됩니다.
선환불
고객이 반품을 신청한 상품의 회수가 시작되는 즉시 결제수단으로 환불해주는 것을 의미합니다.
•
기존의 유저가 반품한 경우 환불은 해당 유저가 반품 요청한 상품이 판매자(혹은 셀러)에 의해 검수되거나 회수된 이후 N 일 이상 경과된 경우 진행되었는데, 반품까지 너무 긴 시간이 소요되어 실제 검수가 되기전에 미리 유저에게 구매한 금액만큼 환불해주고 있습니다.
•
선환불시에는 발생할 수 있는 반품비를 유저에게 돌려줘야하는 금액에서 미리 차감하고 돌려주며, 정상적인 반품완료 시점에서 재계산 이후 추가적으로 환불을 진행합니다.