API Documentation

Base URL: https://api.yoursite.com

Authentication

All endpoints (except /v1/health) require an API key passed via the X-Api-Key header.

X-Api-Key: sk_live_your_key_here

You can also use Authorization: Bearer sk_live_... as an alternative.

Proxy (Required)

All scraping endpoints require a proxy field in the request body. You must provide your own residential/mobile proxy. Format: http://user:pass@host:port or socks5://user:pass@host:port

{"url": "https://shopee.com.br/...", "proxy": "http://user:pass@proxy.example.com:8080"}

Product Data

POST /v1/product

Fetch product details from a Shopee product URL.

Request Body

Field	Type	Description
`url` required	string	Full Shopee product URL

Example

curl -X POST https://api.yoursite.com/v1/product \
  -H "X-Api-Key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"url": "https://shopee.com.br/product-i.123.456"}'

Response

{
  "success": true,
  "data": {
    "product": {
      "name": "Product Name",
      "description": "...",
      "product_id": "456",
      "image": "https://...",
      "offer": {"price": "29.90", "currency": "BRL"},
      "rating": {"value": "4.8", "count": "1250"},
      "seller": {"name": "ShopName", "url": "..."},
      "categories": ["Electronics", "Phones"]
    }
  },
  "request_id": "req_abc123",
  "latency_ms": 420
}

Shipping Rates

POST /v1/shipping

Get available shipping channels and prices for a product.

Request Body

Field	Type	Description
`url`	string	Product URL (extracts shop_id + item_id)
`item_id`	string	Item ID (alternative to url)
`shop_id`	string	Shop ID (alternative to url)
`zipcode` required	string	Buyer's zipcode
`city`	string	City name
`state`	string	State code
`region`	string	Region code: br, my, th, id, ph, sg, vn, tw, ar, mx, la, kh

Reviews

POST /v1/reviews

Fetch product reviews with pagination.

Request Body

Field	Type	Description
`url`	string	Product URL
`item_id`	string	Item ID (alternative to url)
`shop_id`	string	Shop ID (alternative to url)
`limit`	int	Results per page (max 50, default 20)
`offset`	int	Pagination offset
`type`	int	Star filter: 0=all, 1-5=specific star
`region`	string	Region code

Shop Detail

POST /v1/shop

Get shop profile and stats.

Request Body

Field	Type	Description
`url`	string	Product URL (extracts shop_id)
`shop_id`	string	Shop ID directly
`region`	string	Region code

Usage Stats

GET /v1/usage

Get your current usage, billing estimate, and rate limit status. Requires API key.

Health Check

GET /v1/health

Public health check endpoint. No authentication required.

Error Handling

All errors return JSON with a consistent format:

{
  "success": false,
  "error": "description of what went wrong"
}

Code	Meaning
400	Invalid request (missing fields, bad JSON)
401	Missing or invalid API key
403	Key revoked or account suspended
429	Rate limit exceeded (check Retry-After header)
502	Upstream scraper error

Rate Limits

Rate limits are enforced per user (not per key). Response headers include:

Header	Description
`X-RateLimit-Limit`	Max requests per minute for your tier
`X-RateLimit-Remaining`	Remaining requests this minute
`Retry-After`	Seconds until rate limit resets (on 429)