메인 콘텐츠로 건너뛰기

​
인증

모든 API 요청은 Authorization 헤더에 Bearer 토큰을 통한 인증이 필요합니다. 
Authorization: Bearer sk_test_your_api_key

​
API 키 유형

접두사: sk_live_* 또는 sk_test_*Admin API와 Storefront API 모두에 전체 접근 권한을 가진 서버 사이드 키입니다. 클라이언트 사이드 코드에 절대 노출하면 안 됩니다.
curl https://api.headlesscommerce.io/v1/admin/products \
  -H "Authorization: Bearer sk_test_your_secret_key"

​
테스트 vs 라이브 모드

API 키가 데이터 모드를 자동으로 결정합니다:
모드키 접두사설명
테스트sk_test_*, pk_test_*샌드박스 데이터, 실제 결제 처리 없음
라이브sk_live_*, pk_live_*프로덕션 데이터, 실제 트랜잭션
두 모드 모두 동일한 API Base URL을 사용합니다. 키 접두사가 모드를 결정합니다.
항상 테스트 모드 키로 개발 및 테스트를 먼저 진행하세요. 프로덕션 준비가 완료된 후에만 라이브 키로 전환하세요.

​
고객 인증 (Storefront)

고객 신원 확인이 필요한 Storefront 엔드포인트(/customers/me, /orders): Step 1. 서버에서 Admin API를 사용하여 고객 토큰을 생성합니다: 
curl -X POST https://api.headlesscommerce.io/v1/admin/customers/{id}/token \
  -H "Authorization: Bearer sk_test_your_secret_key"
Step 2. 응답에 JWT 토큰이 포함됩니다: 
{
  "token": "eyJhbGciOiJIUzI1NiIs...",
  "expires_at": "2025-01-16T10:30:00Z"
}
Step 3. 클라이언트에서 X-Customer-Token 헤더로 이 토큰을 전달합니다: 
curl https://api.headlesscommerce.io/v1/storefront/customers/me \
  -H "Authorization: Bearer pk_test_your_key" \
  -H "X-Customer-Token: eyJhbGciOiJIUzI1NiIs..."

​
비회원 장바구니

장바구니는 고객 인증 없이 session_id로 생성할 수 있습니다. 비회원 고객이 로그인하면 POST /storefront/carts/{id}/merge를 사용하여 비회원 장바구니를 계정에 병합하세요.