템플릿으로 쇼핑몰 열기

코드를 받지 않고 템플릿을 골라 바로 쇼핑몰을 엽니다. 쇼핑몰은 sayren이 호스팅하고 주소는 {슬러그}.sayren.co입니다. 코드를 직접 고쳐 내 서버에 올리려면 MCP 연결하기부터 보십시오.

준비

• 소유자(OWNER) 또는 관리자(ADMIN) 역할. 상점 플랫폼 왼쪽 레일의 스토어프론트 공간은 이 두 역할에게만 보입니다.
• API로 다룰 때는 스코프 storefront:r(조회)·storefront:rw(쓰기)가 있는 토큰. 이 스코프가 생기기 전에 만든 토큰에는 없으니 새로 만드십시오.

만들기

상점을 만들어도 쇼핑몰은 생기지 않습니다. 쇼핑몰이 필요할 때 템플릿을 골라 만듭니다.

스토어프론트 공간에 들어가면 사이트가 없을 때 스토어프론트 만들기 화면이 열립니다. 만들기를 마칠 때까지 이 공간의 메뉴는 보이지 않습니다. 왼쪽 레일로 다른 공간(상점 관리·설정 등)에는 언제든 갈 수 있습니다.

1. 템플릿 선택: 템플릿을 고릅니다. 업종으로 거를 수 있습니다.
2. 주소 입력: 주소 슬러그를 정합니다. 영문 소문자·숫자·하이픈 3~30자이고 하이픈으로 시작하거나 끝나거나 연달아 쓸 수 없습니다. 기본값은 상점 코드입니다. **[배포 시작]**을 누르기 전까지는 앞 단계로 돌아갈 수 있습니다.
3. 배포: 사이트를 만들고 v1을 발행한 뒤 공개 주소에 반영합니다. 단계(사이트 만들기·버전 올리기·주소 연결·발행)와 기록이 실시간으로 보입니다. 화면을 닫아도 배포는 계속되고, 다시 들어오면 이 단계에서 이어서 보입니다. 실패하면 사유와 **[다시 시도]**가 보입니다.

배포가 끝나면 공개 주소가 보이고 메뉴가 돌아옵니다. 공개 상태는 오픈 준비중이라 방문자에게는 준비 중 안내가 보입니다.

템플릿은 만들 때만 고릅니다. 만든 뒤에는 바꿀 수 없습니다. 만든 뒤의 화면은 편집으로 고칩니다. 다른 템플릿으로 처음부터 시작하려면 호스팅을 끄고 다시 만듭니다(만들기 한도에 들어갑니다).

상점당 사이트는 하나입니다. 사이트는 상점마다 30일에 3번까지 만들 수 있습니다(409 STOREFRONT_SITE_CREATE_LIMIT).

curl -X POST https://api.sayren.app/v1/storefront/site \
  -H "Authorization: Bearer $SAYREN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "templateId": "basic", "slug": "mystore" }'

템플릿 목록은 GET /v1/storefront/templates, 슬러그 사용 가능 여부는 GET /v1/storefront/slug-availability?slug=입니다.

만들기는 곧바로 201로 답하고 공개 주소 반영은 그 뒤에 합니다. 진행은 GET /v1/storefront/site/deployment를 몇 초 간격으로 조회해 status가 SUCCEEDED가 될 때까지 봅니다. 응답에는 단계(steps: SITE·UPLOAD·PUBLISH)와 기록(log)이 있습니다. 템플릿 사이트는 미리 빌드한 템플릿을 올리므로 빌드 단계가 없습니다. status가 FAILED이면 errorCode가 사유이고, 자동 재시도를 기다리지 않으려면 POST /v1/storefront/site/deployment/retry(202)를 부릅니다.

반영 상태

만들기·발행·주소 변경·공개 전환은 저장한 즉시 응답하고 쇼핑몰 반영은 그 뒤에 합니다. 응답의 provisioning.status가 반영 상태입니다.

SYNCED가 된 뒤에도 방문자에게 보이기까지 1분 안쪽이 더 걸릴 수 있습니다.

공개 전 미리보기

오픈 준비 중인 사이트는 방문자에게 준비 중 안내만 보입니다. 구성원은 개요의 **[미리보기 열기]**로 실제 화면을 봅니다.

• 링크는 5분 안에 한 번 엽니다. 연 브라우저에서 12시간 동안 오픈 준비 중인 화면을 볼 수 있습니다.
• 링크는 상점 플랫폼에 로그인한 소유자·관리자만 받습니다(POST /v1/storefront/site/preview-link). 액세스 토큰·에이전트는 받을 수 없습니다.
• 링크를 받은 사람은 누구든 볼 수 있으니 공유하지 마십시오.

공개하기

홈의 **[상점 공개]**나 개요의 **[공개로 전환]**을 누르면 누구나 주소로 들어와 쇼핑몰을 봅니다. 공개 전에 남은 샘플 상품·상점 정보·결제 상태를 알려 줍니다.

• 판매 중인 상품(상점을 만들 때 넣은 샘플 제외)이 1개 이상이어야 공개합니다. 없으면 409 STOREFRONT_NOT_READY입니다.
• 결제는 공개의 조건이 아닙니다. 사용 중인 결제수단이 없으면 쇼핑몰은 상품만 보여 주고 주문을 받지 않습니다.
• 공개한 쇼핑몰은 테스트 결제를 받지 않습니다. 결제가 샌드박스 모드뿐이면 공개 뒤에는 주문을 받지 않으니 라이브 전환을 하십시오. 이 판정은 상점 단위라 직접 호스팅하는 스토어프론트에도 같이 적용됩니다. 테스트 주문은 공개 전 미리보기에서 합니다.
• 스토어프론트는 GET /storefront/v1/store의 checkoutAvailable로 주문 버튼을 정합니다(상점 공개 설정).

curl -X PUT https://api.sayren.app/v1/storefront/site/visibility \
  -H "Authorization: Bearer $SAYREN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "visibility": "PUBLIC", "expectedVisibility": "COMING_SOON" }'

expectedVisibility를 주면 지금 값이 같을 때만 바꿉니다. 다른 곳에서 먼저 바꿨으면 409 STOREFRONT_SITE_CHANGED입니다. 준비 중으로 되돌릴 때는 COMING_SOON을 보냅니다.

버전·되돌리기

발행은 버전 단위입니다. 버전은 v1, v2처럼 번호가 늘고 지금 방문자에게 보이는 버전은 하나입니다. 새 버전은 편집으로 만듭니다.

• 발행: 버전 메뉴에서 발행할 버전을 고릅니다(POST /v1/storefront/site/versions/{versionId}/publish). 이미 그 버전이면 바꾸지 않고 성공으로 답합니다.
• 되돌리기: 이전 버전을 다시 발행합니다(POST /v1/storefront/site/rollback). 버전을 주지 않으면 지금 버전 직전에 발행했던 버전입니다. 새로 만들지 않고 이전 버전을 다시 가리킵니다. 다른 변경처럼 반영 상태를 거쳐 1분 안쪽에 방문자에게 보입니다.

발행·되돌리기에 expectedPublishedVersionId(화면에서 본 발행 버전 id)를 주면 그 사이 다른 사람이 바꿨을 때 409 STOREFRONT_SITE_CHANGED로 막습니다.

사이트 편집

편집 메뉴에서 사이트 코드를 고쳐 새 버전을 만듭니다. 상점 플랫폼에서는 파일을 직접 고치지 않고 AI 도구로 고칩니다. 순서와 도구는 설치 없이 MCP 연결하기의 「AI로 사이트 고치기」에 있습니다. 소스를 내 컴퓨터로 받아 직접 고치려면 CLI로 호스팅 사이트 고치기를 봅니다. 세 경로 모두 같은 파일을 고칩니다.

• 편집 환경: **[편집 시작]**을 누르면 미리보기 서버가 열리고 고친 파일이 미리보기에 바로 반영됩니다(POST /v1/storefront/site/editing). 15분 동안 쓰지 않으면 잠들고, 파일 쓰기·검사·버전 만들기가 30분 동안 없으면 미리보기를 보고 있어도 닫힙니다. 닫히기 5분 전부터 편집 화면에 안내가 보입니다. 고친 파일은 잠들거나 닫혀도 남습니다. 동시에 열 수 있는 편집 환경 수에는 상한이 있어 자리가 없으면 409 EDIT_CAPACITY_FULL과 다시 시도할 때까지의 시간(retryAfterSeconds)을 받습니다.
• 발행 전 검사: 규칙 검사(POST /v1/storefront/site/verify)는 바로 결과를 줍니다. 타입 검사·lint·테스트 (POST /v1/storefront/site/checks)는 편집 환경 없이 돌고 202로 검사 id(checkId)만 받습니다. 결과는 GET /v1/storefront/site/checks/{checkId}로 끝날 때까지 조회합니다(상태 QUEUED·RUNNING → PASSED·FAILED·TIMED_OUT·UNKNOWN). 처음 검사하면 30초 넘게 걸릴 수 있고 150초를 넘으면 TIMED_OUT입니다. 사이트마다 검사는 한 번에 하나이고, 다른 검사가 돌고 있으면 409 CHECK_RUNNING입니다. UNKNOWN은 결과를 확인하지 못한 것이니 새로 검사합니다.
• 버전 만들기: 지금 파일로 버전을 만들면 의존성 검사 → 규칙 검증 → 타입 검사 → 빌드를 거쳐 발행할 수 있는 버전이 됩니다 (POST /v1/storefront/site/versions, 결과는 GET /v1/storefront/site/builds/{buildId}). 공개 사이트는 발행해야 바뀝니다.
• 기준 템플릿 버전: 버전의 templateVersion은 그 버전 파일의 package.json sayren.templateVersion입니다. 템플릿 0.2.14부터 템플릿이 이 값을 싣습니다. 새 템플릿 파일을 병합해 갱신했다면 package.json의 sayren 필드도 함께 가져오면 버전에 그 템플릿 버전이 적힙니다(package.json은 CLI로 바꿉니다). 값이 없으면 지금 발행 버전의 값을 이어받습니다.

의존성

사이트는 npm에 공개된 패키지를 의존성으로 쓸 수 있습니다. 빌드와 타입 검사·lint·테스트는 시작하기 전에 package.json과 pnpm-lock.yaml의 설치 트리 전체를 검사합니다. 의존성이 있으면 pnpm-lock.yaml(pnpm 9 이상이 만든 잠금 파일)이 필요하고, 잠금 파일은 package.json과 맞아야 합니다. 보안 권고가 있는 버전만 빼고 모두 쓸 수 있습니다. 다음 경우에는 빌드하지 않습니다.

• 심각도 high·critical 보안 권고가 있는 버전입니다. 악성 코드 권고가 있는 패키지는 모든 버전을 쓸 수 없습니다. 심각도 moderate 이하 권고는 빌드를 막지 않고 경고로 알립니다.
• 호스팅에서 쓸 수 없도록 따로 정한 패키지나 버전입니다(거절 목록).
• 설치할 패키지를 확인할 수 없습니다. 잠금 파일이 없거나 package.json과 맞지 않거나 읽을 수 없는 형식인 경우, 파일·git·URL 등 npm 레지스트리 밖에서 받는 의존성이 그렇습니다.

다음은 빌드를 막지 않고 경고로 알립니다.

• 루트 package.json의 scripts에 설치할 때 자동으로 실행되는 스크립트(preinstall·install·postinstall·prepare)가 있습니다. 호스팅 빌드는 실행하지 않지만 받은 소스를 직접 설치하면 실행됩니다(INSTALL_SCRIPT).
• package.json에 설치 방식을 바꾸는 필드(pnpm·overrides·resolutions·packageManager·devEngines·workspaces)가 있습니다. 호스팅 빌드는 잠금 파일대로만 설치합니다(INSTALL_CONFIG).
• 설치 스크립트가 있는 의존성(INSTALL_SCRIPT)과 패키지 안에 묶여 오는 의존성(BUNDLED_DEPENDENCIES)입니다.

설치할 때 패키지의 설치 스크립트는 실행하지 않습니다. 네이티브 빌드가 필요한 패키지는 쓸 수 없습니다. 패키지 안에 묶여 오는 의존성 (bundledDependencies)은 보안 권고 검사 대상이 아닙니다. 설치한 의존성의 크기, 빌드 결과물 (서버 번들 10MiB, 정적 파일 하나 25MiB·합계 100MiB)과 빌드 시간(10분)에는 상한이 있습니다.

의존성 검사에서 막히면 빌드는 status: FAILED, failureStage: DEPENDENCIES, errorCode: DEPENDENCY_REJECTED입니다. 빌드 응답의 dependencies.rejected에 패키지·버전·사유(reason)·설명(detail)과 보안 권고(advisory)가 있고, 경고는 dependencies.warnings에 있습니다. 사유는 ADVISORY(보안 권고)·MALWARE(악성 코드)·DENYLISTED(거절 목록)·UNSUPPORTED_SOURCE(레지스트리 밖)·INVALID_MANIFEST(파일 형식)이고, 경고에만 나오는 사유는 INSTALL_SCRIPT(설치 스크립트)·INSTALL_CONFIG(설치 방식 필드)·BUNDLED_DEPENDENCIES(묶인 의존성)입니다. 권고가 없는 버전으로 올리거나 다른 패키지로 바꾼 뒤 버전을 다시 만드십시오. 보안 권고를 확인하지 못하면 빌드는 기다렸다가 다시 확인하고, 30분 동안 확인하지 못하면 DEPENDENCY_CHECK_UNAVAILABLE로 끝납니다.

주소 바꾸기

주소 메뉴에서 슬러그를 바꿉니다(PUT /v1/storefront/site/slug).

• 옛 주소는 90일 동안 보류됩니다. 그동안 옛 주소로 들어온 방문자는 새 주소로 이동하고, 다른 상점은 그 주소를 가져갈 수 없습니다.
• 슬러그는 상점마다 30일에 3번까지 바꿀 수 있습니다(409 STOREFRONT_SLUG_CHANGE_LIMIT). 호스팅을 끄고 다시 만들어도 횟수는 이어서 셉니다. 남은 횟수는 사이트의 slugChangesRemaining입니다.
• 다른 상점이 쓰거나 보류 중인 주소는 409 STOREFRONT_SLUG_TAKEN입니다.

대표 주소는 상점의 storefrontUrl에도 실립니다. 결제 복귀·소셜 로그인·방문 분석의 허용 도메인 목록을 등록해 두었다면 운영 중인 사이트 주소 (기본 주소와 연결된 내 도메인)는 따로 넣지 않아도 허용됩니다. 내 도메인이 대표 주소이면 기본 주소는 내 도메인으로 이동합니다.

내 도메인 연결

가진 도메인(예: www.mystore.co.kr)을 쇼핑몰 주소로 연결합니다. 주소 메뉴의 내 도메인에서 **[도메인 연결]**을 누르거나 POST /v1/storefront/site/domains에 hostname을 보냅니다. 목록과 DNS 안내는 GET /v1/storefront/site/domains입니다.

연결 순서

1. 추가 — 도메인을 추가하면 상태가 PENDING_DNS(DNS 설정 대기)이고 응답의 dnsRecords에 DNS에 넣을 레코드 두 줄이 실립니다.
2. DNS 설정 — 도메인을 산 곳(등록 대행사·DNS 관리 서비스)의 DNS 설정에 두 레코드를 넣습니다.
3. 소유 확인 — sayren이 TXT 레코드를 주기적으로 확인합니다. 확인되면 도메인이 이 상점에 잡히고 상태가 PENDING_VALIDATION(인증서 발급중)입니다.
4. 인증서 발급 — CNAME이 sayren을 가리키면 HTTPS 인증서가 자동으로 발급됩니다.
5. 연결됨 — 상태가 ACTIVE이면 그 도메인으로 쇼핑몰이 열립니다. 기본 주소가 대표 주소였다면 이 도메인이 대표 주소가 됩니다.

기다리지 않고 바로 확인하려면 **[재확인]**을 누르십시오(POST /v1/storefront/site/domains/{domainId}/verify).

• DNS 관리 화면에 따라 이름 칸에는 뒤의 도메인 부분을 빼고 넣습니다. 예를 들어 www.mystore.co.kr의 TXT 이름은 _sayren-verify.www입니다.
• TXT 값은 도메인을 추가할 때마다 새로 만들어집니다. 예전에 넣어 둔 값으로는 확인되지 않습니다.
• www 같은 하위 도메인을 권장합니다. 루트 도메인(mystore.co.kr)은 CNAME을 받지 않는 DNS가 많습니다. CNAME 평탄화(ALIAS·ANAME)를 지원하는 DNS에서만 루트 도메인을 연결하고, 그렇지 않으면 www를 연결한 뒤 DNS 관리 서비스의 전달 기능으로 루트를 www로 넘기십시오.
• 인증서 발급은 보통 몇 분이면 끝납니다. DNS 변경이 퍼지는 데는 최대 48시간이 걸릴 수 있습니다.
• 7일 안에 TXT를 찾지 못하면 상태가 FAILED(failureCode: DNS_NOT_CONFIGURED)로 바뀝니다. DNS를 고친 뒤 **[재확인]**을 누르면 처음부터 다시 확인합니다.
• 인증서를 발급하지 못하면 FAILED(CERTIFICATE_FAILED·VALIDATION_TIMEOUT)입니다. CNAME과 도메인의 CAA 레코드를 확인한 뒤 재확인하십시오.

대표 주소

기본 주소가 대표 주소일 때 처음 연결된 내 도메인은 자동으로 대표 주소가 됩니다. 연결된 도메인을 대표 주소로 지정하면(POST /v1/storefront/site/domains/{domainId}/primary) 상점의 storefrontUrl과 사이트의 url이 그 도메인이 됩니다. 대표가 아닌 주소(기본 주소 {슬러그}.sayren.co 포함)로 들어온 방문자는 대표 주소로 이동합니다(301). 기본 주소를 다시 대표로 지정할 수도 있습니다. 목록에서 kind가 PLATFORM인 항목의 domainId를 쓰십시오.

해제

**[해제]**를 누르면(DELETE /v1/storefront/site/domains/{domainId}) 곧바로 연결이 끊겨 그 도메인으로 쇼핑몰에 들어올 수 없습니다.

• 결제 복귀·소셜 로그인·방문 분석의 허용 주소에서도 곧바로 빠집니다. 그 도메인에서 진행 중인 결제는 완료 화면으로 돌아오지 못할 수 있으니 주문이 적은 시간에 해제하십시오.
• 대표 주소였다면 기본 주소가 대표 주소가 됩니다.
• DNS의 CNAME·TXT 레코드는 sayren이 지우지 않습니다. 쓰지 않으면 DNS에서도 지우십시오.
• 연결된 뒤 DNS를 다른 곳으로 돌리면 failureCode가 DNS_NOT_POINTING이 되고 대표 주소였다면 기본 주소가 대표가 됩니다. 그동안 그 도메인은 결제 복귀·소셜 로그인·방문 분석의 허용 주소에서 빠지고 대표 주소로 지정할 수 없습니다. 이 상태가 7일 넘게 이어지면 연결이 자동으로 해제됩니다.
• 호스팅을 끄거나 상점을 폐쇄하면 내 도메인 연결도 곧바로 해제됩니다.

알아 둘 것

• 상점마다 연결할 수 있는 도메인 수가 정해져 있습니다(목록의 limit, 넘으면 409 STOREFRONT_DOMAIN_LIMIT). 해제한 도메인은 세지 않고, 실패한 도메인은 해제할 때까지 셉니다.
• 다른 상점이 이미 연결했거나 소유 확인을 마친 도메인은 추가할 수 없습니다(409 STOREFRONT_DOMAIN_TAKEN). 소유 확인 전에는 도메인을 잡지 않으므로 남이 먼저 추가만 해 둔 도메인도 TXT 확인을 먼저 통과한 상점이 연결합니다.
• sayren.co·sayren.app 등 sayren 주소, IP 주소, co.kr 같은 공용 접미사, 와일드카드(*.mystore.co.kr)는 연결할 수 없습니다 (400 STOREFRONT_DOMAIN_INVALID, error.details.reason). 한글 도메인은 punycode(xn--…)로 바뀌어 저장됩니다.
• 연결된 도메인은 결제 복귀·소셜 로그인·방문 분석에서 자동으로 허용됩니다. 허용 도메인 목록에 따로 넣지 않아도 됩니다.

호스팅 끄기

개요 아래 위험 구역에서 **[호스팅 끄기]**를 누르고 지금 슬러그를 똑같이 입력합니다(POST /v1/storefront/site/disable, confirmSlug). 사이트는 닫히고 방문자에게 영업 종료 안내가 보입니다. 주소는 30일 보류됩니다. 다시 만들 수 있지만 만들기 한도(30일 3번)를 셉니다.

상점을 폐쇄하면 사이트도 함께 닫힙니다.

닫은 사이트는 30일 동안 영업 종료 안내를 보인 뒤 지워집니다. 그 사이트의 버전과 편집한 파일도 함께 지워지고 되살릴 수 없습니다. 편집한 파일이 필요하면 끄기 전에 파일 API(GET /v1/storefront/site/files)나 MCP 도구로 읽어 두십시오. 끈 뒤에는 읽을 수 없습니다. 다시 만든 사이트는 새 사이트이고 닫은 사이트의 파일을 이어받지 않습니다.

사이트 정지

운영 정책을 어긴 사이트는 sayren이 정지할 수 있습니다. 상점이 정지되면 사이트도 함께 정지됩니다. 정지된 사이트는 status가 SUSPENDED이고 suspension.reason에 정지 사유가 실립니다. 상점 플랫폼 개요에도 사유가 보입니다.

• 방문자에게는 정지 안내가 보입니다.
• 발행·되돌리기·공개 전환·주소 변경·호스팅 끄기·편집은 409 STOREFRONT_SITE_NOT_ACTIVE입니다.
• 셀러가 직접 풀 수 없습니다. 고객센터로 문의하십시오.

AI 에이전트로 다루기

MCP 에이전트의 발행·되돌리기·공개 전환·주소 변경·내 도메인 추가·대표 주소 지정·도메인 해제·호스팅 끄기는 승인이 필요합니다. 구매자가 보는 화면과 주소를 바꾸기 때문입니다. 호스팅 끄기는 소유자만 승인할 수 있습니다. 승인 흐름은 에이전트 쓰기 승인을 보십시오.

오류