스페이스를 직접 만들거나 개발자·파트너에게 제작을 맡길 때 보는 문서입니다. HTML, CSS, JavaScript 기본 지식이 있으면 바로 만들 수 있습니다.
스페이스에서 부를 수 있는 API의 목록과 경로·파라미터·응답 형식은 모두 이 문서에서 확인해 주세요. 이 페이지에는 만드는 방법만 있습니다.
한눈에 보기
① zip 파일
spec.json과 페이지 파일을 하나로 묶습니다.
② 사이드바 메뉴
올리면 커스텀 그룹에 메뉴가 생기고, 누르면 페이지가 열립니다.
③ 데이터 불러오기
인증 정보를 받아 커머스 데이터와 커스텀 DB를 불러옵니다.
1.
정적 웹 페이지(HTML·CSS·JS)를 만들어 zip 파일 하나로 묶습니다.
2.
zip을 올리면 사이드바 커스텀 그룹에 메뉴가 생기고, 누르면 스토어 매니저 안에서 열립니다.
3.
페이지는 스토어 매니저에서 인증 정보를 받아 상품·주문·재고 같은 커머스 데이터와 커스텀 DB 데이터를 불러옵니다.
1. 패키지 구조
zip 최상위에 spec.json과 index.html을 두고, 하위 페이지는 폴더마다 index.html로 만듭니다.
my-space.zip ← 패키지 ID: my-space
├── spec.json ← 필수
├── index.html ← "/" 첫 페이지 (필수)
├── icon.svg ← 선택. 사이드바 아이콘
├── assets/ ← 선택. 공통 스크립트·스타일
│ ├── sixshop.js
│ └── style.css
└── orders/
└── index.html ← "/orders/" 페이지
Plain Text
복사
폴더를 통째로 압축하면 zip 안에 폴더가 한 겹 더 생겨 업로드에 실패합니다. 폴더 안의 파일들을 선택해 압축해 주세요.
macOS 터미널이라면 폴더 안에서 아래처럼 묶으면 됩니다.
zip -r ../my-space.zip . -x '.*'
Bash
복사
2. spec.json 작성하기
스페이스 이름과 하위 메뉴를 적는 파일입니다. pages 순서대로 하위 메뉴가 만들어집니다.
{
"name": "샘플 스페이스",
"pages": [
{ "name": "대시보드", "url": "/" },
{ "name": "주문 목록", "url": "/orders/" }
]
}
JSON
복사
항목 | 규칙 |
zip 파일 이름 (패키지 ID) | 영문, 숫자, -, _ 30자 이내 |
name | 사이드바에 보이는 스페이스 이름 (필수) |
pages[].name | 하위 메뉴 이름, 30자 이내 |
pages[].url | /로 시작. 폴더 페이지는 끝에 /를 붙입니다 (/orders/ → orders/index.html) |
icon.svg | zip 최상위에 두면 메뉴 아이콘으로 쓰입니다. 없으면 기본 아이콘 |
파일 경로 | /assets/style.css처럼 패키지 최상위 기준으로 쓰면 하위 페이지에서도 같은 파일을 읽습니다 |
/orders처럼 끝의 /를 빼면 하위 메뉴를 눌러도 첫 페이지가 보입니다. 꼭 /orders/로 적어 주세요.
3. 인증 정보 받기
페이지는 스토어 매니저에 인증 정보를 요청하고, 받은 값으로 데이터를 불러옵니다. 인증 정보는 주소나 쿠키가 아니라 postMessage로 주고받습니다.
1.
페이지가 스토어 매니저에 SIXSHOP_APP_PAGE_AUTH_REQUEST를 보냅니다.
2.
스토어 매니저가 SIXSHOP_APP_PAGE_AUTH로 storeName, userId, userToken을 돌려줍니다.
3.
페이지는 받은 값을 헤더 3개에 넣어 /call/{API 경로}로 데이터를 요청합니다.
방향 | type | payload |
페이지 → 스토어 매니저 | SIXSHOP_APP_PAGE_AUTH_REQUEST | 없음 |
스토어 매니저 → 페이지 | SIXSHOP_APP_PAGE_AUTH | storeName, userId, userToken |
•
페이지가 열릴 때도 한 번 보내므로 같은 메시지를 두 번 받을 수 있습니다. 처음 받은 값을 쓰면 됩니다.
•
userToken은 이 스토어에서만 쓰는 토큰입니다. 화면·콘솔에 남기거나 다른 서버로 보내지 마세요.
•
새 탭에서 열면 인증 정보를 받을 수 없습니다. 10초 안에 받지 못하면 안내 문구를 보여 주세요.
그대로 복사해 쓸 수 있는 코드입니다. 샘플 파일의 assets/sixshop.js에도 들어 있습니다.
function getAuth() {
return new Promise(function (resolve, reject) {
var timer = setTimeout(function () {
reject(new Error('스토어 매니저 안에서 열어 주세요.'));
}, 10000);
window.addEventListener('message', function (event) {
if (!event.data || event.data.type !== 'SIXSHOP_APP_PAGE_AUTH') return;
clearTimeout(timer);
resolve(event.data.payload); // { storeName, userId, userToken }
});
window.parent.postMessage({ type: 'SIXSHOP_APP_PAGE_AUTH_REQUEST' }, '*');
});
}
JavaScript
복사
4. 데이터 불러오기
{요청 호스트}/call/{API 경로} 주소로 부르고, 받은 인증 정보를 헤더 3개로 넣습니다. 요청 호스트는 페이지 주소에서 맨 앞 부분을 빼서 만듭니다(p123.cp.sixshop.io → cp.sixshop.io). 이렇게 하면 주소를 코드에 적지 않아도 됩니다.
var PROXY_HOST = 'https://' + location.hostname.split('.').slice(1).join('.');
getAuth().then(function (auth) {
return fetch(PROXY_HOST + '/call/commerce/v1/orders?limit=20&page=1', {
headers: {
'ss-store-id': auth.storeName,
'ss-user-id': auth.userId,
'ss-user-token': auth.userToken,
},
});
});
JavaScript
복사
쓸 수 있는 API
스페이스에서 부를 수 있는 API는 커스텀 스페이스 API 문서에 있는 것들입니다. 문서에 적힌 경로를 /call/ 뒤에 붙여 부르고, 파라미터와 응답 형식도 문서를 따라 주세요.
외부 공개 API 함께 쓰기
날씨·공휴일·환율처럼 누구나 쓸 수 있는 공개 API도 페이지에서 바로 부를 수 있습니다. 스토어 데이터가 없어도 동작하는 화면을 만들거나, 스토어 데이터와 엮어 보여 줄 때 유용합니다. 샘플 운영 도구함이 이 방식으로 만들어져 있습니다.
예시 | 공개 API | 주소 예시 |
날씨 | Open-Meteo | https://api.open-meteo.com/v1/forecast?latitude=37.57&longitude=126.98&daily=weather_code&timezone=Asia%2FSeoul |
한국 공휴일 | https://date.nager.at/api/v3/PublicHolidays/2026/KR | |
환율 | Frankfurter | https://api.frankfurter.dev/v1/latest?base=EUR&symbols=KRW,USD,JPY |
•
브라우저에서 바로 부를 수 있는(CORS를 허용하는) API만 쓸 수 있습니다.
•
인증 토큰과 주문·고객 정보 같은 스토어 데이터는 외부 API로 보내지 마세요.
•
API 키가 필요한 서비스는 페이지 코드에 키가 그대로 드러나므로, 키 없이 쓰는 공개 API를 권장합니다.
5. 할 수 있는 것과 없는 것
스페이스 페이지는 스토어 매니저와 분리된 영역에서 열려, 스토어 매니저 화면 자체는 바꿀 수 없습니다.
 할 수 있는 것 |  할 수 없는 것 |
스크립트 실행, 폼 제출, alert·confirm | 스토어 매니저 화면 이동 (window.top.location 변경) |
localStorage, 같은 스페이스 안 페이지 이동 | 스토어 매니저 화면 요소·쿠키 접근 |
새 창 열기 (target="_blank"), 파일 다운로드, 외부 공개 API 호출 | 새 탭에서 열었을 때 인증 정보 받기 |
•
pages[].url에 다른 도메인을 적으면 메뉴에서 빠집니다.
•
하위 메뉴 주소는 pages 순번으로 만들어집니다. 순서를 바꾸면 저장해 둔 주소가 다른 페이지를 가리킵니다.
•
화면은 고정 폭 대신 본문 너비에 맞춰 늘어나게 만들고, 넓은 표는 가로 스크롤로 감싸 주세요.
•
주문·고객 데이터에는 고객 이름·연락처·주소가 들어 있습니다. 필요한 항목만 보여 주고 따로 저장하지 마세요.
6. 올리기 전 체크리스트
zip 파일 이름이 영문·숫자·-·_ 30자 이내다
zip 최상위에 spec.json과 index.html이 있다 (폴더로 한 번 더 감싸지 않았다)
pages[].url이 /로 시작하고, 폴더 페이지는 /로 끝난다
pages[].name이 30자 이내다
인증 정보(SIXSHOP_APP_PAGE_AUTH)를 받은 뒤에 데이터를 부른다
요청 호스트를 페이지 주소에서 만든다
토큰을 화면·콘솔·다른 서버로 내보내지 않는다
불러오는 중·데이터 없음·불러오기 실패 때 화면에 안내가 나온다
7. 문제 해결
증상 | 원인과 해결 |
하위 메뉴를 눌러도 첫 페이지가 보인다 | pages[].url 끝에 /가 없습니다. /orders → /orders/ |
인증 정보를 받지 못한다 | 스토어 매니저 밖에서 열었거나 type 값이 틀렸습니다 |
403 APP-IVP-017 | 스페이스에서 쓸 수 없는 API입니다. API 문서에 있는 API인지 확인해 주세요 |
400 CO-APP-005 | 경로가 틀렸습니다. API 문서의 경로를 확인해 주세요 |
400 "xxx" is not allowed | 쓸 수 없는 파라미터입니다. API 문서에 있는 파라미터만 써 주세요 |
업로드 실패 | 커스텀 스페이스 앱 화면의 경고 아이콘에서 사유를 확인하고 고쳐서 다시 올려 주세요. 예: spec.json pages[1].url must start with / |
메뉴 아이콘이 기본 아이콘이다 | zip 최상위에 icon.svg가 있는지 확인해 주세요 |
해결되지 않으면 패키지 ID, 스토어 ID, 호출한 API 경로와 응답 내용을 함께 고객센터로 알려 주세요.
부록. 최소 템플릿
파일 2개로 만드는 '최근 주문 10건' 스페이스