외부 시스템에서 윈셀링의 기능과 데이터를 활용하기 위한 Open API 의 목적과 사용 사례를 안내합니다.
오픈 API 란?
외부 시스템(ERP · 관리툴 · 자체 개발 서비스 등)에서 윈셀링 판매자 서비스의 상품 · 주문 · 정산 데이터를 조회하거나 조작할 수 있도록 열려 있는 API 입니다. 인증 정보(API Key + Secret Key)만 있으면 브라우저 로그인 없이 프로그램적으로 데이터에 접근할 수 있습니다.
어떤 데이터에 접근할 수 있나요?
상품 · SKU — 등록 · 수정 · 재고 · 옵션 조회
주문 · 클레임 — 수집된 주문 및 취소/반품/교환 조회
정산 내역 — 예정 · 완료 · 채널별 집계
상품·주문 상태 — 진열/판매/재고 상태 확인
지원 엔드포인트 · 요청/응답 스펙은 아래 개발 가이드 에서 확인합니다.
어떤 경우에 사용하나요?
자체 ERP 또는 관리 대시보드에서 주문·재고를 주기적으로 동기화 할 때
외부 광고 · 마케팅 툴에서 상품 정보를 자동 반입 할 때
회계 시스템에 정산 데이터를 자동 연동 할 때
ℹ️
브라우저에서 사용하는 판매자 서비스 화면(윈셀링 관리자) 은 오픈 API 없이도 사용 가능합니다. 외부 시스템과 연동할 때만 필요합니다.
보안 원칙
🔐
Secret Key 는 외부에 노출되지 않도록 관리해야 합니다. 서버 환경변수 · 안전한 비밀 저장소에 보관하고, 소스코드에 하드코딩하거나 클라이언트(브라우저)에 노출하지 마세요.
Key 노출이 의심되면 즉시 재발급 (기존 Key 사용 중지)
허용 IP 를 지정해 접근 가능한 서버 대역을 제한
발급된 Key 는 유효기간 만료 전에 갱신 필요 (윈윈프라이스 회원은 무기한)
최초 발급 · 유효기간 · 만료 임박 안내를 확인하는 방법을 안내합니다.
발급 위치
설정 › API 관리 › OPEN API 페이지 상단의 ＋ Open API 발급 버튼으로 최초 발급합니다. 한 계정당 1세트(API Key + Secret Key) 가 유지됩니다.
발급 흐름
페이지 상단 ＋ Open API 발급 버튼을 누릅니다.
확인 다이얼로그에서 발급 을 선택합니다.
즉시 API Key 와 Secret Key 가 생성되며 인증 정보 카드에 표시됩니다.
💡
발급 직후 Secret Key 는 화면에 노출된 상태에서 한 번 복사 해두는 것을 권장합니다. 이후에는 마스킹 상태로 표시됩니다.
유효기간
구분
유효기간
비고
일반 회원
발급일 기준 지정 기간
만료 전 재발급 으로 갱신
윈윈프라이스 회원
무기한
KPI 카드에 PRICE 배지 표시
KPI 카드로 상태 확인
페이지 상단 유효기간 KPI 카드로 만료까지 남은 일수를 한눈에 확인합니다.
D-31 이상 — 정상 (녹색)
D-30 이하 — 만료 임박 (주황) — 재발급 권장
만료됨 — Key 사용 불가 (빨강) — 즉시 재발급
만료 임박 · 만료 시 대응
⚠️
만료된 Key 로는 API 호출이 거부됩니다. 만료 전에 아래 재발급 흐름으로 갱신하세요. 재발급 시 새 Key 가 발급되고 기존 Key 는 그레이스 기간 동안 병행 유효합니다.
API Key 와 Secret Key 를 확인하고 안전하게 복사·재발급하는 방법을 안내합니다.
인증 정보 카드
발급 완료된 계정의 API Key 와 Secret Key 는 인증 정보 카드에 표시됩니다. 두 키는 요청 인증 시 함께 사용됩니다.
키 복사하기
각 키 오른쪽의 복사 버튼을 누릅니다.
클립보드에 저장되며 "복사되었습니다" 안내가 잠시 표시됩니다.
붙여넣기(Ctrl+V) 로 원하는 곳에 사용합니다.
💡
Secret Key 는 보안상 일부만 노출 되어 표시됩니다. 복사 시에는 전체 값이 복사 됩니다.
재발급 흐름
Key 노출이 의심되거나 유효기간이 가까워졌을 때 재발급합니다.
인증 정보 카드 하단의 🔄 재발급 버튼을 누릅니다.
확인 다이얼로그에서 재발급을 승인합니다.
새 API Key 와 Secret Key 가 즉시 생성됩니다.
연동 중인 외부 시스템의 인증 정보를 새 Key 로 교체 합니다.
그레이스 기간 (병행 유효)
⏳
재발급 후 일정 기간 동안 이전 Key 도 함께 유효 합니다. 새 Key 로의 교체를 완료할 수 있는 여유 시간을 제공합니다. 그레이스 만료 시각은 인증 정보 카드에 표시됩니다.
Key 를 안전하게 다루는 팁
공용 저장소 · GitHub 등 공개된 곳에 저장하지 않기
서버 환경변수(.env) · 시크릿 매니저 에 보관
운영/개발 환경별로 Key 분리는 지원하지 않음 — 한 계정 하나
노출 의심 시 즉시 재발급
API 요청을 허용할 IP 화이트리스트를 등록하고 관리하는 방법을 안내합니다.
왜 필요한가요?
허용 IP 를 등록하면 지정된 서버에서만 Open API 를 호출 할 수 있습니다. Key 가 유출돼도 IP 가 다르면 요청이 거부되므로 보안이 크게 강화됩니다.
🛡️
허용 IP 를 하나도 등록하지 않으면 모든 IP 에서 접근 이 가능합니다. 운영 환경에서는 최소 1개 이상 등록을 권장합니다.
새 IP 추가
페이지 하단 허용 IP 관리 카드의 ＋ 신규 IP 추가 영역을 확인합니다.
등록할 서버 IP 를 입력합니다. (예 : 222.111.10.5)
필요하면 메모 를 입력합니다. (예 : "본사 ERP 서버")
추가 버튼을 누르면 즉시 등록됩니다.
등록된 IP 목록
등록된 IP 는 카드 하단 목록에 표시됩니다. 총 개수는 헤더 옆의 숫자 배지 로 확인할 수 있습니다.
항목
설명
IP
등록된 IP 주소
메모
관리용 설명 (선택)
등록일시
추가한 날짜·시각
삭제
더 이상 사용하지 않는 IP 를 목록에서 제거
IP 삭제
목록에서 삭제할 IP 행의 ✕ 삭제 버튼을 누릅니다.
확인 다이얼로그에서 삭제를 승인합니다.
즉시 목록에서 제거되고, 해당 IP 에서의 요청은 이후 거부됩니다.
IP 확인 팁
서버의 공인(외부) IP 를 등록해야 합니다. 내부 IP(192.168.x.x, 10.x.x.x) 는 동작하지 않습니다.
클라우드(AWS · GCP 등) 사용 시 NAT · 로드밸런서의 외부 IP 로 확인
서버에서 curl ifconfig.me 등으로 현재 나가는 IP 를 확인할 수 있습니다.
Open API 사용 로그 조회와 개발자를 위한 개발 가이드 이용 방법을 안내합니다.
최근 활동 카드
페이지 중앙의 최근 활동 카드에 최근 Key 발급 · 재발급 · 허용 IP 변경 등 관리 이력 이 최신순으로 요약됩니다. 상세는 별도 사용 로그 페이지에서 확인합니다.
사용 로그 열기
페이지 상단 우측의 📊 사용 로그 버튼을 누릅니다.
OPENAPI 연동 로그 페이지가 열립니다.
기간·엔드포인트·상태 필터로 조회 범위를 좁힐 수 있습니다.
개발 가이드 열기
엔드포인트 목록 · 요청/응답 스펙 · 인증 방법 등 개발자용 상세 문서 는 별도 페이지에서 확인합니다.
페이지 상단 우측의 📘 개발 가이드 버튼을 누릅니다.
OPENAPI 개발 가이드 페이지가 열립니다.
로그로 문제 진단하기
증상
확인 지점
401 인증 실패
API Key · Secret Key 오타 · 그레이스 만료 확인
403 접근 거부
허용 IP 목록에 요청 서버 IP 등록 여부 확인
응답 없음
유효기간 만료 여부 · KPI 카드 확인
속도 저하
사용 로그의 응답시간 · 동시 요청 수 확인
💡
대부분의 문제는 사용 로그의 응답 코드 · 응답 본문 으로 즉시 원인을 파악할 수 있습니다.
