Ecommerce

준비

대상 환경에 ecommerce를 활성화하고 공개 상품·variant·option·market 배정을 준비하세요. Catalog는 Publishable Key로 조회하며 Secret Key와 특권 주문·재고 작업은 서버에 둡니다. 공개 조회와 별개로 신규 고객 계정은 Customers를 사용하세요.

예제는 공개 SDK 0.65.1, Next.js 16.3.8 App Router, React 19.2.4, Node 24.15.0 조합입니다. 자신의 앱에 npm install @01.software/sdk@0.65.1로 설치하세요. force-dynamic으로 SDK 호출을 build가 아닌 요청 때 실행합니다. cacheComponents와 static export를 쓰지 않는 구성입니다. 컴파일과 통제된 로컬 transport 검사는 hosted 제공 여부나 원격 tenant admission의 증거가 아닙니다.

Catalog에서 선택까지 구현

완결된 상품 listing, 상품 상세, 읽기 오류 boundary를 복사하세요. /products에서 카드와 swatch·선택 링크를 따라가고 reload 후에도 같은 상품·variant를 선택하는지 확인합니다. 두 레시피는 공개 패키지로 실행하며 후속 참조 분할 페이지를 기다리지 않습니다.

정상·빈 결과·실패

빈 catalog, 공개 상품 한 개, unlisted direct detail, 없는·비공개 detail을 확인하세요. 빈 listing은 성공이고 없는 detail은 표준 404입니다. async route params는 await합니다. stable-ID 선택 왕복, 오래된 선택, credential·feature 오류와 tenant denial을 raw collection 우회 없이 검사합니다. 네트워크·서버 실패는 읽기 재시도 UI로 표시하며 재고 0이나 상품 0으로 바꾸지 마세요.

공개 DTO는 raw 재고를 제외합니다. Catalog availability는 오래될 수 있고 stock check는 예약이 아니며 최종 주문 생성에서 재고·판매 가능성을 다시 검사합니다. Catalog 표시만으로 결제 준비가 확인되지 않습니다.

다음 액션

기존 SDK의 cart·checkout·PaymentSession 안내로 이어갑니다. 작업의 typed reason과 retry·idempotency 의미를 유지하며 write를 무조건 반복하거나 catalog 클릭으로 결제를 시작하지 마세요. Checkout·결제 구현은 이 작업 범위 밖입니다. 상품 소유권·provider 설정·출시는 커머스 운영, 연동과 키 관리, 배포를 따릅니다.