상품 상세
1 크레딧/v1/tiktokshop/product상품 URL로 TikTok Shop 상품 1건을 가져옵니다. 가격, 평점, 리뷰 수, 판매자, 이미지가 포함됩니다. 상품 조회는 업스트림 기준으로 미국(US)만 지원합니다.
url or product_id, region
TikTok Shop APITikTok Shop 데이터 API
SocialCrawl API 키로 TikTok Shop 상품, 리뷰, 스토어 목록, 크리에이터 쇼케이스를 구조화 JSON으로 가져옵니다. Amazon, Walmart와 같은 커머스 스키마입니다. 호출은 크레딧으로 과금됩니다.
/v1/tiktokshop
활성 엔드포인트는 5개입니다. 모두 표준 티어입니다.
- GET /v1/tiktokshop/product
- GET /v1/tiktokshop/product/reviews
- GET /v1/tiktokshop/products
- GET /v1/tiktokshop/search
- GET /v1/tiktokshop/user/showcase
TikTok Shop 엔드포인트
TikTok Shop 읽기 엔드포인트는 5개입니다. 상품 상세, 리뷰, 스토어 목록, 키워드 검색, 크리에이터 쇼케이스를 제공합니다. 커머스 데이터만 지원하며 결제, 재고 쓰기, 판매자 대시보드는 포함되지 않습니다.
상품 리뷰
1 크레딧/v1/tiktokshop/product/reviews샵 상품 리뷰를 반환합니다. 평점, 본문, 작성자, 시각이 포함됩니다. 1페이지만 반환합니다. url 또는 product_id를 사용합니다.
url or product_id, cursor, region
샵 상품 목록
1 크레딧/v1/tiktokshop/products샵 또는 스토어 URL의 상품 목록입니다. 제목, 커버, 가격, 판매 수, 리뷰, 평점이 포함됩니다. sort_by는 top 또는 new_releases입니다.
url, cursor, sort_by, region
샵 검색
1 크레딧/v1/tiktokshop/searchTikTok Shop 전체를 키워드로 검색합니다. 가격, 평점, 판매자 정보가 있는 상품을 반환합니다. region과 page를 선택합니다.
query, cursor, region
크리에이터 쇼케이스
1 크레딧/v1/tiktokshop/user/showcase크리에이터 공개 쇼케이스에 올라온 상품입니다. 제목, 가격, 이미지, 샵 정보가 포함됩니다. 이 조회는 US 리전만 지원합니다.
handle, region, cursor
TikTok Shop API5개 엔드포인트 지원
문서 보기TikTok Shop 상품 하나를 돌려줍니다: 상세 설명, 가격과 할인, 별점, 리뷰 수, 브랜드, 재고, 배송, 판매자 정보.
상품 URL이나 product_id 하나를 조회할 때 사용하세요. 조회가 미국 리전에서 처리되므로 다른 시장에서만 파는 상품은 404가 납니다.
1크레딧
GET/v1/tiktokshop/product?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fpdp%2Fgoli-ashwagandha-gummies-with-vitamin-d-ksm-66-vegan-non-gmo%2F1729587769570529799&product_id=1729587769570529799
$ curl https://www.socialcrawl.dev/v1/tiktokshop/product?url=https%3A%2F%2Fwww.tiktok.com%2Fshop%2Fpdp%2Fgoli-ashwagandha-gummies-with-vitamin-d-ksm-66-vegan-non-gmo%2F1729587769570529799&product_id=1729587769570529799 \
-H "x-api-key: sc_YOUR_API_KEY"대기 중
// 실제 실행에는 API 키가 필요합니다. "실행해보기"를 누르면 예시 응답을 표시합니다TikTok Shop API 동작
TikTok Shop도 다른 SocialCrawl 커머스 엔드포인트와 같습니다. API 키로 GET /v1/tiktokshop/… 를 호출하고 캐시 미스에 크레딧을 쓰며 동일한 JSON 봉투를 받습니다. TikTok Shop 판매자 OAuth는 없습니다.
호출 인증
x-api-key 헤더에 키를 보냅니다. 공개 읽기에 TikTok Shop OAuth 앱은 필요 없습니다. SocialCrawl 전 플랫폼에 같은 키를 사용합니다.
GET과 쿼리 파라미터
TikTok Shop 라우트는 모두 GET입니다. url, query, handle, product_id, region, page, sort_by, cursor를 쿼리로 전달합니다. 과금 전에 형식을 검증합니다.
크레딧 과금
TikTok Shop 라우트는 모두 표준 티어입니다. 라이브 미스는 1 크레딧입니다. 캐시 히트는 0 크레딧입니다. 빈 응답과 하드 실패는 환불됩니다.
JSON 봉투
응답 형태는 success, data, credits_used, credits_remaining, request_id, cached로 동일합니다. 페이지가 있는 목록 응답은 페이지네이션 필드를 가집니다.
연동 순서
대부분 제품은 검색 후 상품을 깊게 보고 리뷰를 가져옵니다. 쇼케이스는 크리에이터 카탈로그용입니다.
01검색
GET /v1/tiktokshop/search?query=…가격, 평점, 판매자 정보가 있는 상품 결과
상품 URL이 없을 때 키워드로 목록을 찾습니다.
02상품
GET /v1/tiktokshop/product?url=…상품 상세: 가격, 평점, 판매자, 이미지
검색만으로 부족할 때 한 상품을 깊게 봅니다.
03리뷰
GET /v1/tiktokshop/product/reviews?url=…평점, 본문, 작성자, 시각이 있는 ReviewList
VoC 텍스트는 product가 아니라 reviews 라우트에 있습니다.
04쇼케이스
GET /v1/tiktokshop/user/showcase?handle=…핸들에서 홍보 중인 상품 카드
제휴·크리에이터 커머스는 프로필 쇼케이스에서 시작합니다.
요청
GET /v1/tiktokshop/search
?query=phone+case
®ion=US
Host: www.socialcrawl.dev
x-api-key: sc_your_api_key_here
# deepen a product
GET /v1/tiktokshop/product?url=https://www.tiktok.com/shop/pdp/…
GET /v1/tiktokshop/product/reviews?url=…응답 봉투
{
"success": true,
"data": {
"items": [
{
"product": {
"id": "1729587769570529799",
"title": "Example product",
"price": { "current": 19.99, "currency": "USD" },
"rating": 4.7,
"url": "https://www.tiktok.com/shop/pdp/…"
}
}
]
},
"credits_used": 1,
"credits_remaining": 9999,
"request_id": "req_…",
"cached": false
}data 형태
필드 이름은 다른 SocialCrawl 커머스 플랫폼과 같습니다. Amazon 상품을 파싱하면 TikTok Shop도 같은 아키타입에서 같습니다.
Productproduct
id, title, price, rating, review count, seller, images, url, ext (region)
ProductList / PostListproducts, search, user/showcase
items[]에 title, cover, price, sold/rating, shop 또는 creator 컨텍스트
ReviewListproduct/reviews
items[]에 author, content.text, rating, published_at
SearchResultsearch
상품 카드와 판매자 정보가 있는 키워드 결과
게이트웨이 내부
다른 /v1 플랫폼 엔드포인트와 같은 요청 수명주기입니다. TikTok Shop은 사이드카가 아닙니다.
- 01
엣지가 호출을 받음
Next.js catch-all이 Hono 소셜 API로 라우팅합니다. request_id를 만들고 키를 인증한 뒤 분당 600회, 키당 동시 50개 한도를 적용합니다.
- 02
검증 후 차감
레지스트리에서 tiktokshop/search (or product, reviews, showcase)를 찾습니다. 필수 파라미터와 형식 검사를 먼저 합니다. 잘못된 입력은 과금 없이 400입니다. 유효 호출은 업스트림 전에 티어 비용을 원자적으로 차감합니다.
- 03
캐시 또는 수집
platform + resource + params로 캐시 키를 만듭니다. 히트면 credits_used = 0으로 즉시 반환합니다. 미스면 TikTok Shop 경로를 실시간으로 읽습니다. 소스가 불안정하면 5xx/네트워크 재시도와 서킷 브레이커를 사용합니다.
- 04
정규화 후 반환
업스트림 JSON을 Product, ProductList, ReviewList, SellerList, App, PlaceList 등 커머스 아키타입으로 매핑하고 Zod로 검증한 뒤 성공 봉투로 감싸 과금 감사 로그를 남깁니다.
운영에서 중요한 과금 규칙
- 표준 라이브 미스: 1 크레딧
- 샵 라우트 5개: 각 1 크레딧
- 캐시 히트: 0 크레딧
- 빈 응답 / 하드 실패: 자동 환불
- 잘못된 파라미터: 400, 과금 없음
- 크레딧 부족: 402, 과금 없음
- 상품·쇼케이스 조회: US 외 리전은 무료 거절
- 검색·상품 목록: 업스트림이 허용하면 다국가
- 판매자 쓰기·결제 라우트 없음
데이터 수집 방식
TikTok Shop은 공개 커머스 데이터입니다. SocialCrawl 스키마로 정규화하므로 별도 샵 SDK를 배울 필요가 없습니다.
이 API에서 TikTok Shop의 의미
공개 상품, 리뷰, 스토어 카탈로그, 검색, 크리에이터 쇼케이스입니다. 읽기 전용이며 결제, 재고 관리, 판매자 인증은 없습니다.
SocialCrawl 수집 경로
TikTok Shop 경로를 요청 시점에 실시간으로 읽어 엣지에서 정규화합니다. 공개 파사드는 소셜 TikTok 분리 이후 /v1/tiktokshop/* 입니다.
엣지에서 나가는 형태
success, data, credits_used, request_id, cached JSON 봉투입니다. 상품과 리뷰는 Amazon, Walmart와 같은 커머스 아키타입을 공유합니다.
라이브로 제공하지 않는 것
쓰기 엔드포인트는 없습니다. 상품·쇼케이스 조회는 업스트림이 넓히기 전까지 US만 지원합니다. 리뷰 전체 다중 페이지네이션은 없습니다.
필드 매핑
shop product card→ product.*title, price, rating, images, seller
review rows→ ReviewList items[]rating, text, author, timestamp
creator showcase→ PostList / product cards크리에이터가 홍보하는 핸들 범위 상품
이 API의 활용 분야
이 API가 가장 많이 사용되는 작업입니다.
5active TikTok Shop endpoints in the registry
1 credit모든 샵 라우트 라이브 읽기당 과금
크리에이터 커머스와 샵 상품 조사
호출은 검색 → 상품 → 리뷰 흐름과 제휴 모니터링용 크리에이터 쇼케이스에 몰립니다. 소셜 TikTok과 같은 키로 샵 라우트를 씁니다. 판매자 앱 없이 상품, 리뷰, 스토어, 검색, 쇼케이스를 제공합니다.
샵 읽기는 라이브 미스 기준 보통 수 초입니다. 다른 /v1 플랫폼과 같은 게이트웨이 한도를 씁니다.
TikTok Shop API 활용 사례
TikTok Shop 데이터가 가장 많이 쓰이는 작업입니다. 각 항목에서 엔드포인트 순서와 과금 방식을 확인합니다.
활용 사례
이 데이터를 활용하는 대표적인 방식과 각 방식에서 주로 사용하는 스택입니다.
크리에이터 커머스 팀
Node, cron, sheets핸들 집합의 쇼케이스 상품을 모은 뒤 SKU가 움직일 때 상품 상세를 깊게 봅니다.
경쟁 가격 데스크
Python, notebooks리전별로 카테고리 키워드를 검색하고 상품 상세와 리뷰로 가격·평점 변화를 샘플링합니다.
백엔드 제품 작업
Go, workers, Explorer검색 → 상품 → 리뷰를 파이프라인에 연결합니다. 캐시 히트로 반복 실행 비용을 낮춥니다. SocialCrawl 전 구간과 같은 키입니다.
두 줄로 호출
표준 티어는 라이브 호출당 1 크레딧입니다. 캐시 히트는 무료입니다.
curl "https://www.socialcrawl.dev/v1/tiktokshop/search?query=phone+case®ion=US" \
-H "x-api-key: sc_your_api_key_here"curl "https://www.socialcrawl.dev/v1/tiktokshop/product?url=https://www.tiktok.com/shop/pdp/goli-ashwagandha-gummies-with-vitamin-d-ksm-66-vegan-non-gmo/1729587769570529799®ion=US" \
-H "x-api-key: sc_your_api_key_here"엔드포인트
TikTok Shop API는 어떤 데이터를 돌려주나요
모든 엔드포인트가 같은 응답 구조의 JSON을 보내드려요. 엔드포인트가 해당 지표를 지원하고 계산에 필요한 원본 값이 있을 때만 참여율·콘텐츠 카테고리 같은 계산 필드가 포함돼요.
자주 묻는 질문
자주 묻는 질문
API, 요금제, 기능에 대한 질문과 답변입니다.
문의하기TikTok Shop API로 무엇을 할 수 있나요?
SocialCrawl은 TikTok Shop 엔드포인트 5종을 제공해요. 상품 상세, 상품 리뷰, 스토어 전체 상품 목록, 키워드 상품 검색, 크리에이터 쇼케이스를 모두 같은 통합 스키마로 받아볼 수 있어요.
TikTok Shop 데이터는 어떻게 받나요?
x-api-key와 함께 GET /v1/tiktokshop/<리소스>를 호출하면 돼요. 엔드포인트에 따라 샵·상품 URL, 핸들, 검색어를 넘기면 되고, 공개 샵 데이터는 셀러 계정이나 로그인 없이 바로 읽을 수 있어요.
어떤 지역의 TikTok Shop을 지원하나요?
검색, 스토어 상품 목록, 상품 리뷰는 US, GB, DE, FR, IT, ID, MY, MX, PH, SG, ES, TH, VN, BR, JP, IE 등 16개 지역을 지원해요. region 파라미터에 2자리 ISO 코드를 넘기면 되고, 생략하면 기본값은 US예요. 상품 상세와 크리에이터 쇼케이스 조회는 업스트림 제약으로 지금은 US에서만 제공돼요.
TikTok Shop API는 요금이 얼마인가요?
모든 TikTok Shop 엔드포인트는 요청당 1 크레딧이에요(스탠다드 티어). 한 페이지에 담기는 상품·리뷰 수와 상관없이 동일하고, 새 계정은 신용카드 없이 100 크레딧을 무료로 받아요.
TikTok API와 같은 건가요?
TikTok Shop은 /v1/tiktokshop/* 경로의 별도 플랫폼이에요. 소셜 TikTok 엔드포인트에서 분리됐고, 기존 통합을 위해 예전 /v1/tiktok/shop/* 경로도 계속 작동하지만 새 코드는 tiktokshop 경로를 쓰시는 게 좋아요.
TikTok Shop 데이터 스크래핑, 법적으로 괜찮을까요?
SocialCrawl은 누구나 볼 수 있는 공개 TikTok Shop 데이터만 돌려드리고, 로그인이 필요한 비공개 콘텐츠에는 접근하지 않아요. 다만 실제 적법성은 활용 목적과 국가별 법률에 따라 달라져요. TikTok Shop 이용약관과 GDPR·CCPA 같은 개인정보 보호 법규를 지키는 책임은 이용자에게 있어요. 이 답변은 일반 안내일 뿐, 법률 자문은 아니에요.
TikTok Shop 스크래핑 API와 공식 TikTok Shop API는 뭐가 다른가요?
SocialCrawl은 앱 심사나 승인 대기가 없어요. 가입 직후 x-api-key 하나로 TikTok Shop 엔드포인트를 바로 호출할 수 있고, 응답은 다른 모든 플랫폼과 같은 통합 스키마로 와요. 요금도 플랫폼별 쿼터 대신 크레딧으로 계산해요. 글 게시 같은 쓰기 작업이 필요하다면 공식 API가 맞아요. SocialCrawl은 읽기 전용 데이터만 다뤄요.
AI에게 SocialCrawl을 물어보세요