상품 상세
5 크레딧/v1/sephora/productP번호 또는 sephora.com/product URL 1건의 미국 상품 상세입니다. 제목, 브랜드, 가격, 평점, 이미지, 성분이 포함됩니다. 고급 티어(5 크레딧)입니다.
product_id or url
Sephora APISephora 상품·매장 데이터 API
SocialCrawl API 키로 Sephora 미국 상품 상세, 리뷰, 검색, 카테고리, 브랜드, 매장, 매장 재고를 구조화 JSON으로 가져옵니다. 공유 커머스 스키마입니다. 호출은 크레딧으로 과금됩니다.
/v1/sephora
활성 엔드포인트는 11개입니다. 1·5 크레딧 티어입니다.
- GET /v1/sephora/product
- GET /v1/sephora/reviews
- GET /v1/sephora/search
- GET /v1/sephora/search/suggestions
- GET /v1/sephora/category
- GET /v1/sephora/categories
- GET /v1/sephora/category/data
- GET /v1/sephora/brands
- GET /v1/sephora/brand/products
- GET /v1/sephora/stores
- GET /v1/sephora/availability
Sephora 엔드포인트
Sephora 미국 읽기 엔드포인트는 11개입니다. 상품 상세, 리뷰, 키워드 검색, 자동완성, 카테고리 목록, 분류, 브랜드, 브랜드 카탈로그, 매장 검색, SKU 재고를 제공합니다. 데이터 API만 지원합니다.
상품 리뷰
5 크레딧/v1/sephora/reviewsSephora 상품 아이디 리뷰입니다. 평점, 본문, 작성자, 선택 page가 있습니다. 고급 티어(5 크레딧)입니다.
product_id or url, page
키워드 검색
5 크레딧/v1/sephora/search쿼리에 맞는 Sephora 상품입니다. 페이지당 60건이며 페이지네이션이 정확합니다. 결과가 없으면 빈 목록이고 과금되지 않습니다. 고급 티어(5 크레딧)입니다.
query, page, page_size
검색 제안
1 크레딧/v1/sephora/search/suggestions검색어 일부에 대한 자동완성입니다. 표준 티어(1 크레딧)입니다.
query
카테고리 목록
5 크레딧/v1/sephora/categorycategory_id 안의 상품 목록입니다. page를 선택할 수 있습니다. 고급 티어(5 크레딧)입니다.
category_id, page
카테고리 분류
1 크레딧/v1/sephora/categoriesSephora 최상위 카테고리입니다. category 상품 목록에 쓸 id를 여기서 얻습니다. 표준 티어(1 크레딧)입니다.
(none)
카테고리 하위
1 크레딧/v1/sephora/category/data카테고리 하나와 하위 분류입니다. 표준 티어(1 크레딧)입니다.
id
브랜드 목록
1 크레딧/v1/sephora/brandsSephora 브랜드 짧은 이름입니다. brand/products에 넣습니다. 표준 티어(1 크레딧)입니다.
(none)
브랜드 카탈로그
5 크레딧/v1/sephora/brand/products브랜드 짧은 이름 하나의 상품 목록입니다. page를 선택할 수 있습니다. 고급 티어(5 크레딧)입니다.
id, page
매장 검색
1 크레딧/v1/sephora/stores위도,경도 근처 Sephora 매장을 찾습니다. PlaceList 형태입니다. 표준 티어(1 크레딧)입니다.
location_coordinate
매장 재고
5 크레딧/v1/sephora/availability좌표 근처 한 SKU의 매장 재고입니다. 고급 티어(5 크레딧)입니다.
sku, location_coordinate
Sephora API11개 엔드포인트 지원
문서 보기Products
Reviews
Search
Reference
Stores
Sephora 상품을 아이디 또는 URL로 조회해 제목, 브랜드, 설명, 가격, 평점, 이미지, 성분, 재고 여부를 반환합니다.
상품 아이디(P427414)나 sephora.com/product URL이 있을 때 사용합니다. 찾을 때는 search 또는 category에서 시작합니다.
5크레딧
GET/v1/sephora/product?product_id=P427414
$ curl https://www.socialcrawl.dev/v1/sephora/product?product_id=P427414 \
-H "x-api-key: sc_YOUR_API_KEY"대기 중
// 실제 실행에는 API 키가 필요합니다. "실행해보기"를 누르면 예시 응답을 표시합니다Sephora API 동작
Sephora도 다른 SocialCrawl 데이터 엔드포인트와 같습니다. API 키로 GET /v1/sephora/… 를 호출하고 캐시 미스에 크레딧을 쓰며 동일한 JSON 봉투를 받습니다.
호출 인증
x-api-key 헤더에 키를 보냅니다. 공개 읽기에 Sephora OAuth 앱은 필요 없습니다. SocialCrawl 전 플랫폼에 같은 키를 사용합니다.
GET과 쿼리 파라미터
Sephora 라우트는 모두 GET입니다. product_id, query, category_id, location_coordinate, sku를 쿼리로 전달합니다. 과금 전에 형식을 검증합니다.
크레딧 과금
카탈로그 경로는 5 크레딧입니다. 분류, 브랜드, 자동완성, 매장은 1 크레딧입니다. 캐시 히트는 0 크레딧입니다.
JSON 봉투
응답 형태는 success, data, credits_used, credits_remaining, request_id, cached로 동일합니다. 페이지가 있는 목록 응답은 페이지네이션 필드를 가집니다.
연동 순서
대부분 제품은 검색 또는 목록 후 필요할 때만 상세, 리뷰, 매장 재고를 깊게 봅니다.
01검색
GET /v1/sephora/search?query=…P번호가 있는 ProductList
키워드에서 product_id를 확정합니다.
02상품
GET /v1/sephora/product?product_id=…P번호 전체 Product
상품 1건을 깊게 봅니다.
03리뷰
GET /v1/sephora/reviews?product_id=…P번호 ReviewList
해당 상품 고객 언어입니다.
04재고
GET /v1/sephora/availability?sku=…SKU 매장 재고
좌표 근처 매장 수량을 봅니다.
요청
GET /v1/sephora/search?query=moisturizer
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here
GET /v1/sephora/product?product_id=P427414
GET /v1/sephora/reviews?product_id=P427414응답 봉투
{
"success": true,
"data": {
"product": {
"id": "P427414",
"title": "Natural Moisturizing Factors + Hyaluronic Acid Daily Moisturizer",
"brand": "The Ordinary",
"price": { "current": 12.5, "currency": "USD" },
"rating": { "average": 4.09, "count": 2841 }
}
},
"credits_used": 5,
"credits_remaining": 9995,
"request_id": "req_…",
"cached": false
}data 형태
아키타입이 맞는 범위에서 필드 이름은 SocialCrawl 나머지와 같습니다. 한 번 파싱해 플랫폼에 재사용합니다.
Productproduct, availability
id (P번호), title, brand, price, rating, images
ProductListsearch, category, brand/products
items[]에 product id, title, price
ReviewListreviews
items[]에 rating, text, author
Analytics / PlaceListcategories, brands, stores
분류 행 또는 좌표 근처 매장
게이트웨이 내부
다른 /v1 플랫폼 엔드포인트와 같은 요청 수명주기입니다. Sephora는 사이드카가 아닙니다.
- 01
엣지가 호출을 받음
Next.js catch-all이 Hono 소셜 API로 라우팅합니다. request_id를 만들고 키를 인증한 뒤 분당 600회, 키당 동시 50개 한도를 적용합니다.
- 02
검증 후 차감
레지스트리에서 sephora/product (또는 reviews, search, stores)를 찾습니다. 필수 파라미터와 형식 검사를 먼저 합니다. 잘못된 입력은 과금 없이 400입니다. 유효 호출은 업스트림 전에 티어 비용을 원자적으로 차감합니다.
- 03
캐시 또는 수집
platform + resource + params로 캐시 키를 만듭니다. 히트면 credits_used = 0으로 즉시 반환합니다. 미스면 Sephora 카탈로그 경로를 호출합니다. 소스가 불안정하면 5xx/네트워크 재시도와 서킷 브레이커를 사용합니다.
- 04
정규화 후 반환
업스트림 JSON을 Product, ProductList, ReviewList, PlaceList 등 커머스 아키타입으로 매핑하고 Zod로 검증한 뒤 성공 봉투로 감싸 과금 감사 로그를 남깁니다.
운영에서 중요한 과금 규칙
- product / reviews / search / category / brand/products / availability: 5 크레딧
- suggestions / categories / category/data / brands / stores: 1 크레딧
- 캐시 히트: 0 크레딧
- 빈 검색 / 하드 실패: 자동 환불
- 잘못된 파라미터: 400, 과금 없음
- 크레딧 부족: 402, 과금 없음
- 상품 심화 키는 product_id
- 미국 카탈로그만 제공
- landings.platformBrief.platforms.sephora.api.billingRules.8
데이터 수집 방식
Sephora는 공개 읽기 데이터입니다. SocialCrawl 스키마로 정규화하므로 별도 벤더 SDK를 배울 필요가 없습니다.
이 API에서 Sephora의 의미
공개 미국 상품, 리뷰, 검색, 카테고리 분류, 브랜드, 매장 위치, SKU 매장 재고입니다. 읽기 전용입니다.
SocialCrawl 수집 경로
통합 /v1 봉투 뒤의 Sephora 카탈로그 경로입니다.
엣지에서 나가는 형태
Product, ProductList, ReviewList, PlaceList, 분류 analytics 형태입니다.
라이브로 제공하지 않는 것
장바구니, Beauty Insider, 유럽 카탈로그 경로는 없습니다.
필드 매핑
product row→ product.*title, brand, price, rating
review pages→ ReviewList선택 page 파라미터
taxonomy / stores→ Analytics / PlaceList카테고리 id; 매장 위치
이 API의 활용 분야
이 API가 가장 많이 사용되는 작업입니다.
11active Sephora endpoints in the registry
1 / 5분류·매장과 카탈로그 경로 크레딧 구간
구색, 리뷰, 매장 재고
호출은 검색 또는 분류 후 후보 상품의 상세·리뷰·재고 심화에 몰립니다. P번호 상품·리뷰 5 크레딧, 분류·매장 1 크레딧, SocialCrawl 동일 키입니다.
라이브 미스는 보통 수 초입니다. 일부 경로는 콜드 캐시에서 더 걸릴 수 있습니다.
활용 사례
이 데이터를 활용하는 대표적인 방식과 각 방식에서 주로 사용하는 스택입니다.
뷰티 머천다이저
Python, BIsearch 또는 categories 후 category 목록, product로 P번호 사실을 확인합니다.
VoC 팀
Node, warehousesproduct_id별 reviews로 고객 언어를 모읍니다.
로컬 운영
scripts, maps좌표로 stores와 availability 재고를 확인합니다.
두 줄로 호출
product, search, reviews는 5 크레딧입니다. 분류와 stores는 1 크레딧입니다. 캐시 히트는 무료입니다.
curl "https://www.socialcrawl.dev/v1/sephora/product?product_id=P427414" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/sephora/search?query=moisturizer" \
-H "x-api-key: sc_your_api_key_here"엔드포인트
Sephora API는 어떤 데이터를 돌려주나요
모든 엔드포인트가 같은 응답 구조의 JSON을 보내드려요. 엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때만 참여율·콘텐츠 카테고리 같은 계산 필드가 포함돼요.
ProductGet a Sephora product by id or URLReviewsGet Sephora product reviewsSearchSearch Sephora products by keywordSearch SuggestionsGet Sephora search suggestionsCategoryBrowse Sephora products in a categoryCategoriesList Sephora root categoriesCategory DataGet a Sephora category and its childrenBrandsList Sephora brandsBrand ProductsList Sephora products for a brandStoresFind Sephora stores near a coordinateAvailabilityGet Sephora in-store availability for a sku
자주 묻는 질문
자주 묻는 질문
API, 요금제, 기능에 대한 질문과 답변입니다.
문의하기Sephora API 비용은 얼마인가요?
Sephora 엔드포인트는 호출한 만큼 크레딧으로 계산해요. 스탠다드 1크레딧, 어드밴스드 5크레딧, 프리미엄 10크레딧이고, Sephora에서는 호출당 1~5크레딧이에요. 가입하면 100크레딧을 무료로 드리고, 구독 없이 쓴 만큼만 내면 돼요.
Sephora 데이터 스크래핑, 법적으로 괜찮을까요?
SocialCrawl은 누구나 볼 수 있는 공개 Sephora 데이터만 돌려드리고, 로그인이 필요한 비공개 콘텐츠에는 접근하지 않아요. 다만 실제 적법성은 활용 목적과 국가별 법률에 따라 달라져요. Sephora 이용약관과 GDPR·CCPA 같은 개인정보 보호 법규를 지키는 책임은 이용자에게 있어요. 이 답변은 일반 안내일 뿐, 법률 자문은 아니에요.
Sephora 스크래핑 API와 공식 Sephora API는 뭐가 다른가요?
SocialCrawl은 앱 심사나 승인 대기가 없어요. 가입 직후 x-api-key 하나로 Sephora 엔드포인트를 바로 호출할 수 있고, 응답은 다른 모든 플랫폼과 같은 통합 스키마로 와요. 요금도 플랫폼별 쿼터 대신 크레딧으로 계산해요. 글 게시 같은 쓰기 작업이 필요하다면 공식 API가 맞아요. SocialCrawl은 읽기 전용 데이터만 다뤄요.