마켓 추가하기

Hanaro는 다음 3개 마켓을 1차로 지원합니다 (Wave β). 각 마켓의 공식 API 키 또는 OAuth 토큰을 발급받아 등록합니다.

RiskLevel — Hanaro는 마켓의 약관 회색지대(세션 자동화 등) 사용 시 위험도를 명시적으로 표시합니다. 자세한 내용은 FAQ — 공식 API와 세션 자동화의 차이 참조.

스마트스토어

1. 네이버 셀러센터에서 API 권한 받기

1. 네이버 커머스 API 센터에 셀러 계정으로 로그인.
2. 애플리케이션 등록:
   • 애플리케이션 이름: Hanaro (자유)
   • 사용 용도: 주문 조회 / 발송 처리
3. 발급된 클라이언트 ID, 클라이언트 시크릿 복사.

2. Hanaro에서 등록

1. 설정 → 마켓 계정 → + 추가 → 스마트스토어 선택.
2. 입력:
   • 클라이언트 ID
   • 클라이언트 시크릿
   • 판매자 ID (선택, 멀티 셀러 식별용)
3. 연결 테스트 → 성공 시 저장.

3. WebView2 로그인 흐름 (선택)

일부 운영 작업(예: 주문 상태 변경 — 발송준비 → 배송중)은 공식 API로 노출되지 않아 세션 기반 자동화를 사용합니다. 이때 처음 한 번 WebView2 창에 네이버 로그인이 필요합니다.

주의: 세션 자동화는 네이버 약관의 회색지대(위험도: 비공식 연결)에 해당합니다. 이 위험도는 처음 설정할 때 마켓 선택 화면에 배지로 표시됩니다. 자동화를 원치 않으시면 이 마켓을 등록하지 않으시면 되고, 공식 API만으로 운영 가능합니다.

첫 로그인 절차

1. 설정 → 마켓 계정 → + 추가 → 스마트스토어 선택.
2. WebView2 로그인 버튼 클릭 → 네이버 로그인 모달 창이 뜹니다.
3. 모달 안에서 네이버 ID·비밀번호 입력 → 캡차 → 2FA(설정된 경우)까지 진행.
4. 셀러센터(sell.smartstore.naver.com/o/... 또는 /home)에 도달하면 Hanaro가 자동으로 NID_AUT / NID_SES / NSI / NACID 쿠키를 회수하고 모달이 닫힙니다.
5. 회수된 쿠키는 Windows DPAPI로 암호화되어 SQLite(자격증명들 테이블, 키 prefix COOKIE_)에 저장.

쿠키 만료 / 재로그인

• 네이버 세션 쿠키의 만료 주기는 약 2주입니다(네이버 정책).
• Hanaro가 자동화 호출 중 401/302 응답을 받으면 다음 동기화 사이클에서 WebView2 모달을 다시 띄웁니다 — 사용자는 비밀번호만 다시 입력하면 됩니다.
• 자격증명 강제 재발급: 설정 → 마켓 계정 → 스마트스토어 행 → 재인증 → 네이버 계정으로 로그인 다시 클릭.

WebView2 Runtime 사전 요구사항

• Windows 10/11에서 Microsoft Edge WebView2 Runtime이 필요합니다.
  • Windows 11: 기본 포함되어 있습니다.
  • Windows 10: 자동 업데이트 패치로 대부분 설치되어 있으나 부재 시 설치 안내 모달이 표시됩니다.
  • 수동 설치: https://developer.microsoft.com/microsoft-edge/webview2/
• WebView2 사용자 데이터(캐시·쿠키)는 기본적으로 %APPDATA%/Hanaro/WebView2에 저장됩니다. 환경변수 HANARO_WEBVIEW2_USERDATA_FOLDER로 변경 가능.

세션 자격증명은 DPAPI로 암호화되어 SQLite에 저장됩니다. 같은 사용자/머신에서만 복호 가능.

쿠팡

1. Wing OpenAPI 신청

1. 쿠팡 Wing 로그인 후 좌측 메뉴 설정 → OPEN API 또는 직접 쿠팡 OPEN API 포털 접속.
2. API 신청 → 사용 범위 선택:
   • 주문 조회 (필수)
   • 발송 처리 (필수)
   • 반품 / 교환 (선택)
3. 승인 완료 후 VendorId, AccessKey, SecretKey 발급.

승인까지 영업일 1~3일 소요됩니다. 미리 신청해두세요.

2. Hanaro에서 등록

1. 설정 → 마켓 계정 → + 추가 → 쿠팡 선택.
2. 입력:
   • VendorId (예: A00012345)
   • AccessKey
   • SecretKey
   • WING 로그인 아이디 (선택 — 아래 설명)
3. 연결 테스트 → 응답 코드 200 확인 → 저장.

3. WING 로그인 아이디 (문의 답변용, 선택)

AI 직원이 쿠팡 상품문의에 답변을 등록할 때, 쿠팡은 답변자가 누구인지를 함께 보내라고 요구합니다. 쿠팡 공식 API 문서가 이 항목을 “응답자 셀러포탈(WING) 아이디” 라고 적고 있어, Hanaro는 쿠팡 WING에 로그인할 때 쓰시는 아이디를 여기에 넣도록 했습니다 (비밀번호는 입력하지 않습니다). API 키와 달리 조회할 방법이 없어 셀러가 직접 적어 주셔야 합니다. 입력한 값은 다른 자격증명과 똑같이 Windows DPAPI로 암호화되어 이 컴퓨터에만 저장됩니다.

정직하게 적습니다: 이 항목은 아직 실제 쿠팡 계정으로 답변을 등록해 확인하지 못했습니다 (근거는 쿠팡 공식 문서 문구뿐입니다). 혹시 답변이 계속 실패하면 하나로 고객센터로 알려 주세요.

• 비워 두어도 됩니다. 주문 수집·송장 전송은 WING 아이디 없이 그대로 동작합니다.
• 비워 두면 문의 답변 등록만 쓸 수 없습니다. 승인함에서 답변을 승인하면 “쿠팡 WING 아이디가 설정되지 않아 답변을 등록할 수 없습니다”라고 안내되고, 답변은 마켓으로 나가지 않습니다. (그 답변은 쿠팡 WING에서 직접 등록하시면 됩니다.)
• 오타가 있어도 저장은 그대로 됩니다 — 확인할 API가 없어 입력 시점에는 맞는지 알 수 없고, 나중에 답변이 실패(권한 없음·거절)할 때에만 드러납니다.
• 이미 등록해 둔 쿠팡 계정에 나중에 추가하실 때는 재인증을 누르면 Vendor ID·Access Key는 채워진 채로 열리고, Secret Key는 비워 두면 저장된 값으로 연결을 확인합니다 — WING 아이디만 넣고 저장하면 됩니다. (저장된 Secret Key는 보안상 화면에 다시 채워 넣지 않습니다. Vendor ID나 Access Key를 바꾸면 키 쌍이 달라지므로 Secret Key를 새로 입력해야 합니다.)
• 나중에 채워 넣거나 바꾸면 다음 답변부터 바로 적용됩니다 — 앱을 다시 켤 필요가 없습니다.
• 칸을 비우고 저장하면 저장해 둔 아이디가 삭제되고, 답변 등록은 다시 쓰이지 않습니다.

4. 쿠팡 특이사항

• 쿠팡은 HMAC-SHA256 서명을 모든 요청에 요구합니다 — Hanaro가 자동 처리.
• 분당 요청 제한(Rate Limit) 60회 — Polly 정책으로 자동 백오프.

카페24

카페24는 셀러 본인이 카페24 개발자센터에서 만든 앱으로 연결합니다. 앱을 한 번 만들어 두면 그 뒤로는 하나로가 주문 조회·송장 전송에 필요한 인증을 자동으로 갱신합니다.

1. 카페24 개발자센터에서 앱 만들기

1. 카페24 개발자센터에 카페24 계정으로 로그인한 뒤 새 앱을 만듭니다.

2. 앱 설정의 Redirect URI에 아래 주소를 글자 하나 다르지 않게 등록합니다. 하나로 연결 화면에도 같은 주소와 [복사] 버튼이 있습니다.

   https://hanaro-docs.pages.dev/cafe24-app-callback/
   

   마지막 /까지 그대로 넣어 주세요. 주소가 조금이라도 다르면 [허용]을 누른 뒤 연결이 실패합니다.

3. 앱 권한(scope) 에서 주문 읽기·쓰기 — mall.read_order, mall.write_order — 를 선택합니다.
4. 발급된 Client ID와 Client Secret을 확인합니다. Client Secret은 비밀번호처럼 다루고 다른 사람에게 알려 주지 마세요.

2. 하나로에서 연결하기

1. 설정 → 마켓 계정 → + 추가 → 카페24 선택.
2. Mall ID를 입력합니다. 카페24 관리자 주소 mystore.cafe24.com의 앞부분(mystore)입니다.
3. Client ID와 Client Secret을 입력합니다.
4. 카페24 연결하기 클릭 → 인증 창에서 카페24에 로그인 → [허용] → 창이 자동으로 닫힙니다.
5. 토큰과 Client ID/Secret은 이 컴퓨터에서만 풀 수 있도록 암호화되어 저장됩니다 (만료 전 자동 갱신).

버튼이 회색으로 눌리지 않으면 버튼 아래 문구에 무엇이 빠졌는지 표시됩니다. 연결 직후 “주문 조회 확인에 실패했습니다”가 보이면 문구에 적힌 사유(예: 앱의 API 버전)를 운영팀에 알려 주세요.

이미 연결해 둔 카페24 계정

• 기존 방식(하나로 공용 앱)으로 연결해 둔 계정은 그대로 동작합니다. 다시 연결해야 할 때는 [재인증] → Client ID/Secret을 비운 채 카페24 연결하기를 누르면 기존 방식으로 연결됩니다.

• 본인 앱으로 바꾸려면 [재인증]에서 Client ID/Secret을 입력하고 연결을 끝까지 완료하세요. 앱을 바꾸면 기존 연결은 새 앱으로 갱신되지 않으므로, 중간에 그만두면 주문 수집이 멈춥니다.

  한 번 본인 앱으로 바꾸면 기존 방식(하나로 공용 앱)으로는 되돌릴 수 없습니다. 되돌리려면 계정을 지우고 새로 등록해야 하는데, 새 등록도 본인 앱이 필요합니다. 또 개발자센터에서 그 앱을 지우면 연결이 끊기니 앱을 지우지 마세요.

• 본인 앱으로 연결한 계정을 다시 연결할 때 Client ID가 같다면 Client Secret은 비워 두어도 됩니다.
• 계정을 삭제하고 다시 등록하지 마세요. 같은 몰을 새로 등록하면 주문 이력이 두 계정으로 나뉩니다.

등록 후 확인

설정 → 마켓 계정에서 등록된 마켓 목록을 확인할 수 있습니다.

자격증명을 다시 입력하려면 계정의 [재인증] → 새 값 입력 → 저장. 기존 데이터는 보존됩니다.

• 네이버 아이디, 쿠팡 Vendor ID·Access Key, 카페24 Mall ID는 저장된 값이 미리 채워집니다.
• 비밀번호·Secret Key는 채워지지 않습니다. 비워 두면 저장된 값을 그대로 씁니다. 바꿀 때만 입력하세요.
• 네이버 아이디나 쿠팡 Vendor ID·Access Key를 바꾸면 비밀번호·Secret Key도 새로 입력해야 합니다.

다음

• 첫 동기화 → 온보딩에서 자동으로 시작됨 (수동: 주문 화면 F2 → [마켓 동기화])
• 송장 일괄 처리 → 송장 전송
• 마켓 자격증명 보안 → FAQ