이 문서는 스마트십에서 Ebay Japan(Qoo10 JP)의 API와의 연동을 설정하는 방법을 설명하고 있습니다.
목차
1. API연동에 관해
API란 서로 다른 시스템들 사이에 데이터를 주고 받기 위해 미리 약속된 규약입니다. 스마트십 시스템은 쇼핑 사이트와의 API를 연동하는 기능을 제공하여 체결된 판매 주문을 가져올 수 있습니다. API 연동을 사용하면 쇼핑 사이트에서 주문 정보를 엑셀 파일로 다운로드 받고 다시 스마트십에 업로드하는 번거로운 작업 없이 자동으로 주문을 등록하고, 주문 확인 및 송장 등록까지 시스템을 통해 자동으로 처리할 수 있습니다.
1.1. API 연동 기능의 장점
•
주기적으로 새로운 주문을 감지하고 스마트십 배송 건을 자동으로 등록합니다.
•
주문 확인을 스마트십에서 처리하거나, 주문 수집 후 자동으로 확인 처리를 할 수 있습니다.
•
송장이나 패킹 라벨을 출력할 때, 자동으로 쇼핑 사이트에 송장 번호를 등록하고 발송처리를 할 수 있습니다.
•
판매 주문의 취소 및 부분 취소를 감지하여 스마트십의 배송 주문에 반영합니다. 취소된 주문은 스마트십에서 삭제되며, 부분 취소의 경우 해당 상품만 자동으로 제거됩니다.
•
풀필먼트 서비스를 이용하시는 경우, 주문 수집에서 출고 및 발송처리까지의 프로세스를 완전 자동화할 수 있습니다.
1.2. API 연동 사용 시 주의 사항
1.2.1. 주문의 삭제
•
API 연동을 통해 등록된 주문을 스마트십에서 삭제한 후에는 API 수동 연동으로도 재등록 되지 않습니다. 삭제한 주문을 복구하기 위해서는 [주문 > 취소 주문 관리]에서 삭제한 주문을 선택 후 [재연동] 버튼을 클릭하여 복원해주세요.
•
취소 주문의 재연동은 주문의 실시간 상태에 따라서 연동되지 않을 수 있습니다. 또 체결 시점 기준으로 2주 이상 지난 주문은 연동에 실패할 수 있습니다.
1.2.2. 주문 및 주문품의 변경
•
API를 통해 수집된 스마트십 배송주문 내 상품에는, 판매사이트 주문의 상태를 처리하기 위한 정보가 포함되어 있습니다. 따라서 스마트십 주문에 포함된 배송상품 정보를 임의로 삭제하거나, 교체 혹은 수량을 변경하는 경우에 API를 통한 송장등록(발송처리)가 작동하지 않을 수 있습니다. 불가피하게 주문을 수정한 경우에는 해당 주문의 송장번호는 판매 사이트에서 직접 등록해주세요.
•
타 주문 관리 시스템을 사용 중이시라면 스마트십에서 API 연동하는 방법을 추천하지 않습니다.
•
쇼핑 사이트는 여러 시스템이 같은 API를 사용하는 것을 알지 못하여, 동일 주문을 중복 처리하게 될 수 있습니다.
•
타 시스템이 주문 상태를 변경하면 스마트십에서 주문을 가져오지 못할 수 있습니다.
•
쇼핑 사이트에 따라서는 신규로 키를 발급받는 경우, 기존에 발급된 키가 자동으로 폐기되는 경우도 있습니다.
2. 사전 준비 사항
2.1. 접속 토큰과 사용자 인증
쇼핑 사이트의 판매자 어드민을 사용하기 위해서는 판매자 ID와 패스워드를 사용하여 로그인을 하듯이, API를 사용하여 주문 정보를 처리하기 위해서는 쇼핑사이트가 제공하는 인증 정보가 필요합니다. 접속 토큰은 이 때 사용되는 인증 정보이며, 쇼핑 사이트의 로그인 과정을 거쳐 원격으로 발급 받습니다. 아이디와 패스워드를 입력하는 화면은 쇼핑 사이트가 제공하는 화면이며, 스마트십은 판매자의 쇼핑 사이트 아이디나 패스워드를 획득하거나 저장하지 못합니다.
3. 스마트십에서 API 연결 추가하기
주문 > 쇼핑몰 연동 > 쇼핑몰 API 설정
3.1. 신규 API 연결 추가하기
1.
쇼핑몰 API 설정 화면으로 이동합니다.
2.
상단, [신규등록] 버튼을 클릭합니다.
3.
연결할 쇼핑사이트를 선택합니다. 빠르게 찾기 위해서는 쇼핑 사이트 이름의 일부만 타이핑하여 검색하면 빠르게 찾을 수 있습니다.
3.2. 정보 입력 및 연결 정보 등록
1.
‘쇼핑몰 샵 ID’ 입력란에 "JQSM 로그인 아이디"를 입력합니다.
2.
하단 [인증받기] 버튼을 클릭합니다.
3.
“api.qoo10.jp” 주소의 팝업창이 열리면, JQSM 로그인 아이디와 비밀번호를 입력하고 “Generate”를 클릭하세요.
4.
팝업창이 닫히면서 인증 정보가 자동으로 저장됩니다.
• 표시가 있는 필드는 필수 필드입니다.
3.3. 완료 및 연결 테스트
1.
하단 회면에서 [등록하기] 버튼을 클릭하세요.
신규 API를 설정하거나, 기존 정보를 수정한 후에는 연결 테스트를 하기 전에 항상 등록/수정을 통해 변경된 인증 정보를 시스템에 적용해야 합니다.
2.
등록이 완료된 후, 정상적인 API 통신이 가능한지 확인하기 위해 [연결 테스트] 버튼을 클릭하세요.
3.4. 연결 테스트에 실패하는 경우
연결 테스트에 실패하는 경우에는 다음과 같은 사항을 확인해보세요.
1.
판매 사이트 API 키 발급 시 IP 정보가 정확하게 입력되었나요?
2.
Access Key와 Secret Key가 각각 올바른 필드에 저장되었나요?
3.
[등록하기] 혹은 [수정하기] 버튼을 클릭하여 변경 사항을 시스템에 적용하였나요?
4.
해당 사이트의 API 서버의 일시적인 장애나 네트워크 문제로 연결에 실패할 수 있습니다. 잠시 기다린 후 다시 시도해보세요.
•
판매자 로그인 이메일 혹은 아이디
•
연결하려는 사이트 및 샵 ID
•
스마트십의 오류 화면 캡쳐
•
쇼핑사이트 API 키 발급 시 입력한 정보 화면 캡쳐
4. API 설정 및 연동 주문
API 연동을 통해 주문을 수집하고 처리하는 동작을 조정하는 몇 가지 옵션이 있습니다.
4.1. API 설정
4.1.1. 자동 주문 연동
‘자동 주문 연동’을 사용함으로 설정하면, 스마트십이 주기적으로 새로운 주문을 확인하고 새 주문을 스마트십으로 등록합니다. 이 기능을 사용하지 않을 경우, [주문 > 쇼핑몰 연동 > 쇼핑몰 주문연동] 화면에서 기간을 지정하여 원할 때에만 주문을 자동으로 가져오게끔 할 수 있습니다.
4.1.2. 자동 주문 확인
API를 통해 수집한 주문을 등록할 때 쇼핑 사이트에 주문 확인 처리를 합니다. 확인 처리된 주문은 구매자가 취소할 수 없으며, 취소 요청까지만 할 수 있습니다.
전체 주문을 자동으로 확인하거나, 풀필먼트 주문만 자동으로 확인하도록 할 수 있습니다.
API 연동을 통한 자동 주문 확인은 일시적인 네트워크 장애 등의 이유로도 실패할 수 있습니다.
4.1.3. 자동 풀필먼트 출하지시
API를 통해 수집한 주문이 확인되면 자동으로 풀필먼트 센터에 출하지시를 내립니다.
•
‘주문확인’ 상태의 주문만 출하지시 대상이 됩니다.
•
‘자동 주문 확인’을 사용하지 않는 경우에는 수동으로 주문 확인 처리를 하면 자동 출하지시가 적용됩니다.
•
풀필먼트 이용 고객님은 ‘자동 주문 확인’과 함께 활성화하여 사용하실 것을 추천합니다.
•
이 기능은 풀필먼트 서비스 전용입니다. 4.1.4. 일부 항목에 SKU 정보가 없는 경우
풀필먼트 주문을 생성하기 위해서는 판매주문의 모든 상품 정보에 판매자 상품코드 등 SKU를 매칭할 수 있는 데이터가 있어야 합니다. 한 주문에 이 정보가 없는 상품이 섞여 있는 경우 주문을 처리하는 방법을 결정합니다.
•
풀필먼트 주문에 포함 → 풀필먼트 주문으로 생성되나, SKU 정보가 없어 상품 정보 오류 상태가 됩니다. SKU를 매칭하여 출하지시 할 수 있습니다.
•
별도 배송 주문으로 분할 → SKU 정보가 없는 주문만 자동으로 분할하여 판매자 출고 주문으로 생성합니다.
•
풀필먼트 처리 안함 → 전체 주문을 판매자 출고 주문으로 생성합니다.
•
이 기능은 풀필먼트 서비스 전용입니다. •
일부 판매사이트만 지원하며, 기본값은 ‘풀필먼트 주문에 포함’으로 작동합니다.4.1.5. 예상 배송일자 업데이트
•
스마트십을 통해 주문확인을 처리하는 경우, 판매사이트 주문의 ‘예상 배송일’ 정보를 자동으로 업데이트합니다.
•
자동으로 설정하는 예상 배송일은 당일 ~ 3일후까지 지정 가능합니다.
•
일부 판매사이트만 지원합니다. 4.1.6. 재고 동기화 설정
•
SKU의 재고가 변동될 때, SKU에 맵핑된 상품에 대해 판매 사이트의 재고량을 동기화할 수 있습니다.
•
사용함으로 설정하는 경우, 특정 주기마다 재고량이 변동된 상품의 재고를 판매사이트로 동기화합니다.
•
판매 사이트가 재고 동기화를 지원하는 경우, 자동 동기화를 사용하지 않더라도 수동으로 실행할 수 있습니다.
•
일부 판매사이트만 지원합니다. •
일부 판매사이트에서는 마감재고 동기화를 지원합니다. 마감 재고 동기화는 새벽 시간에 풀필먼트 센터의 창고 재고를 판매 사이트로 동기화합니다.4.1.7. 연동 계정 추가 타입
•
API를 통해 주문을 수집은 하되, 처리하지 않는 옵션입니다.
•
세일즈 통계만 작성하려는 경우 사용합니다.
4.1.8. API를 통해 수집되는 주문
API를 통해 수집되는 주문은 몇 가지 조건을 만족해야 합니다.
4.2. 연동 가능한 주문의 상태
•
판매사이트에서 결제 완료된 신규 주문 및 배송 준비 상태의 주문(판매 사이트에서 판매자 확인 처리함)을 수집합니다.
•
취소된 주문은 수집 대상에서 제외됩니다.
•
기본적으로 당일 생성된 주문을 수집합니다.
•
판매 주문 등록일과 결제일이 다른 경우, 결제일 이후에 수집될 수 있습니다.
•
과거 주문의 경우, 수동으로 연동을 실행하여 수집해주세요. 수집 가능한 기간의 범위는 판매사이트가 허용하는 범위 이내입니다. (통상 15~30일)
•
주문량이 많은 경우, 주기 내에 모두 처리되지 못할 수 있습니다. 한 주기 내에 처리되지 못한 주문은 다음 주기에 이어서 처리됩니다.자동 주문 수집은 기본적으로 작동을 시작하는 당일부터의 주문을 수집합니다. 만약 인증 키 만료 등의 사유로 자동 주문이 중지된 후, 재설정하였다면 주문이 수집되지 않은 기간의 주문은 반드시 수동으로 API 주문 연동을 실행해야 수집됩니다.
4.2.1 Ebay Japan(Qoo10 JP)의 연동 가능한 주문의 상태
•
주문 중 “新規注文(신규주문)” & “ 配送準備(배송준비)” 상태의 주문을 가져옵니다.
5. 풀필먼트 상품 연결
풀필먼트 서비스를 이용하시는 경우, 판매사이트의 상품을 SKU로 매칭하여 센터에서 올바른 상품을 출고하기 위한 맵핑 정보가 필요합니다. SKU와의 연결을 위해서는 판매사이트의 상품 정보 관리에서 스마트십 SKU를 식별할 수 있는 구분 값을 각 상품/옵션의 판매자 상품코드에 등록합니다. 상품 매칭을 위한 정보는 다음 중 한 가지 방법을 통해 이루어집니다.
1.
이미 관리중인 판매자 상품코드가 있고, 판매사이트 상품에도 이 코드가 등록되어 있다면, 동일한 코드를 SKU의 “판매자 정의코드”에 등록해주세요.
2.
스마트십에서 부여하는 재고 관리 코드인 SKU no. (7000########-000##)를 판매사이트의 판매자 상품코드에 등록하여, 주문 상품을 해당 재고로 인식하게 해주세요.
5.1. SKU에 판매자 정의코드 등록 방법
스마트십 > 재고 > SKU 관리
1.
SKU 관리 메뉴로 진입합니다.
2.
설정할 SKU를 조회하고 선택해주세요.
3.
상품에 판매자 코드가 있는 경우, 상품 정보의 판매자 정의코드를 등록해주세요.
4.
옵션에 판매자 코드가 있는 경우, 옵션을 선택하고 판매자 정의코드에 판매자 코드를 등록해주세요.
5.2. 판매 사이트 상품에 SKU no.를 등록하는 방법
J-QSM > 商品管理(상품관리) > 商品の照会/修正(상품조회/수정)
1.
Ebay Japan(Qoo10 JP) 상품 등록 화면에서 상품별 코드를 입력합니다.
•
옵션이 없는 단일 상품일 경우는 “販売者商品コード(판매자상품코드)”를 입력합니다.
•
옵션이 있는 선택 상품일 경우에는 옵션 별로 “販売者オプションコード (판매자옵션코드)”를 입력합니다.
6. API 설정 수정하기 (API키 만료)
일반적인 쇼핑 플랫폼에서 발급하는 API 키에는 만료일자가 있습니다. API키가 만료되면 API 호출 권한이 사라져 주문을 수집하거나, 송장을 등록하는 등 정보 연동을 정상적으로 수행할 수 없습니다.
•
API 키의 만료일자는 별도로 관리해주세요.
•
키가 만료되기 전에 쇼핑 사이트 플랫폼에서 API 키를 갱신 또는 재발급 받아야 합니다.
•
API키를 갱신/재발급 받은 경우, 일반적으로 기존 키는 즉시 만료됩니다. 따라서 스마트십의 쇼핑사이트 API 설정 기능을 통해, API 키를 수정해주셔야 합니다.
API키 만료 등으로 API 설정 정보를 수정한 후에는, 주문 수집이 중단된 날부터 수동으로 API 주문 연동을 해주셔야 합니다.
주문 > 쇼핑몰 연동 > 쇼핑몰 주문 연동
1.
쇼핑몰 주문 연동 페이지로 이동
2.
판매사이트 × 샵 항목 선택
3.
지정 주문 연동일의 날짜 범위 선택 (최대 1주일 선택 가능)
4.
[주문 가져오기] 버튼 클릭
6.1 Qoo10 JP API 키 만료 시 갱신 방법
Qoo10 JP 시스템의 특성 상, QSM에서 판매자 로그인 비밀번호를 변경하면 자동으로 기존 API 키가 만료됩니다. QSM에서 판매자 정보를 수정한 후에는, API 설정 페이지에서 연결 테스트를 통해 인증 상태를 꼭 확인해주세요.
주문 > 쇼핑몰 연동 > 쇼핑몰 API 설정
1.
키를 변경할 Ebay Japan(Qoo10 JP) 샵을 선택합니다.
2.
인증 정보란에 있는 [토큰 갱신하기] 버튼을 클릭합니다.
3.
초기 설정할 때와 같이, Ebay Japan(Qoo10 JP)의 인증 창이 열립니다. 여기에 QSM 로그인 아이디와 비밀번호를 입력하여 판매자 계정을 인증합니다.
4.
인증에 성공하면 자동으로 키가 갱신됩니다.
5.
API 통신이 정상적으로 이루어지는지 확인하기 위해, 하단의 [연결 테스트하기] 버튼을 클릭해주세요.
6.
API키가 만료되어 주문이 수집되지 않은 시간 동안의 주문이 누락되지 않도록, API 주문 수집을 수동으로 실행하여 주세요.