HIOBuy API Starter

A minimal open-source Next.js starter for building with the HIOBuy Product API.

Search products from 1688 and Taobao, browse results, open product details, and learn how to integrate HIOBuy APIs into your own application.

HioBuy Starter Live Demo · HioBuy Starter on GitHub · HioBuy Product API Documentation · HioBuy Developer Platform

Features

Demo	HIOBuy API
Keyword search & product listing	POST /v1/products/search
Image search	POST /v1/products/search-by-image
Open Taobao / 1688 product links	POST /v1/products/detail (with url)
Product details & variants	POST /v1/products/detail

The starter keeps your HIOBuy API key on the server using Next.js Route Handlers. The browser never receives your API key. The browser only calls this app’s /api/products/* routes, which proxy to the HIOBuy Product API.

Demo Usage

The public live demo uses a HIOBuy demo application with server-side credentials.

API credentials are never exposed to the browser.

The public demo validates a fresh Cloudflare Turnstile token on every enabled product API request, including product details, image search, product-link lookup and pagination. The server checks the token's hostname and action; expired or reused tokens are rejected before contacting HIOBuy.

The standalone /api/products/parse proxy is disabled on public deployments, even with a valid verification token. The website does not use it: pasted product links go through /api/products/detail with url, so normal link lookup still works. The parse integration example remains available in local development. Trusted operators can explicitly opt in using DEMO_PARSE_ENABLED=true, with the same token and rate checks.

Managed verification runs in the background for normal visitors. A verification panel appears only when Cloudflare requires interaction; normal browsing does not show a verification dialog on every request.

All enabled product routes share per-IP limits: 4 requests per 10 seconds and 15 per minute. IPv6 clients share a /64 counter. Limits use Cloudflare Workers rate limit bindings, whose counters are approximate and local to each Cloudflare location; they are an abuse throttle, not a strict global spending cap. HIOBuy Gateway quotas remain the final usage boundary.

Search is limited to the first 5 pages, at most 20 products per page. Requests also require same-origin JSON and have bounded body sizes (16 KiB normally, 4 MiB for image search). Rejections return a readable error; rate limits include Retry-After.

For development and integration testing, create your own HIOBuy Developer App and API key:

https://developers.hiobuy.com

The public demo is intended for evaluation only and should not be used as an API proxy for production applications.

Quick Start

1. Get a HIOBuy API key

Create a developer account at developers.hiobuy.com, create an App, and obtain an API key.

Make sure your App has access to the marketplace channels you want to use, such as 1688 or Taobao. An API key alone is not enough — the App must also be authorized for those channels.

For development, we recommend using a test or sandbox key where available.

2. Clone the starter

git clone https://github.com/hiobuy/starter.git
cd starter

3. Configure environment variables

cp .env.example .env.local

Add your HIOBuy API key:

HIOBUY_API_KEY=your_api_key_here

Optional:

HIOBUY_DEFAULT_LANGUAGE=en

Never commit .env.local or expose your API key in frontend code.

4. Install and run

pnpm install
pnpm dev

Or with npm:

npm install
npm run dev

Open:

http://localhost:3000

How It Works

Browser
   │
   ▼
Next.js Route Handler  (/api/products/*)
   │
   │  Authorization: Bearer <HIOBUY_API_KEY>
   ▼
HIOBuy Product API

Your API key is stored only in the server environment. Frontend code should call this starter’s proxy routes (for example POST /api/products/search), not the HIOBuy API host directly.

Example browser → proxy request body:

{
  "channel": "1688",
  "keyword": "phone case",
  "page": 1,
  "page_size": 20
}

Project Structure

src/
├── app/
│   ├── page.tsx
│   ├── search/
│   │   └── page.tsx
│   ├── product/
│   │   └── [channel]/[id]/
│   └── api/
│       └── products/
│           ├── search/
│           ├── search-by-image/
│           ├── parse/
│           └── detail/
│
├── components/
│
└── lib/
    └── hiobuy.ts

lib/hiobuy.ts contains the server-side HIOBuy API client.

The routes under app/api/products/ act as a secure proxy between the browser and HIOBuy.

Important Notes

Product IDs

Use the id from search (or parse) results in later product requests. The Product API accepts id directly.

API Keys

Never:

• expose your API key in client-side JavaScript;
• commit API keys to Git;
• include production credentials in public repositories.

Keep credentials in server-side environment variables or a secrets manager.

What This Starter Does Not Include

This project intentionally focuses on the Product API.

It does not include:

• Order creation
• Procurement
• Warehouse fulfillment
• International shipping
• Payment

See other HIOBuy examples for these workflows.

Deployment

The official HIOBuy Starter demo is deployed on Cloudflare Workers:

https://starter.demo.hiobuy.com

This project is a standard Next.js application and does not require Cloudflare for local development or self-hosting.

pnpm preview   # OpenNext build + local Workers runtime (uses .env.local)
pnpm build:cloudflare # production build without local secrets; no deployment
pnpm deploy    # production deploy (does NOT bake .env.local)

Secrets (required for production)

OpenNext can embed Next.js .env* values into the Worker server bundle at build time. That is why a local pnpm deploy with .env.local present may appear to “work” even if you never ran wrangler secret put.

pnpm deploy and pnpm build:cloudflare temporarily move local production .env* files and .dev.vars aside, strip HIOBuy/Turnstile/demo environment values from the build process, and restore files even when a build fails. Set runtime secrets on Cloudflare instead:

wrangler secret put HIOBUY_API_KEY
wrangler secret put TURNSTILE_SECRET_KEY
# optional:
wrangler secret put HIOBUY_DEFAULT_LANGUAGE

Do not put secrets in wrangler.jsonc, Git, or any NEXT_PUBLIC_* variable.

If you already deployed while .env.local was present, rotate that API key in the Developer Portal and redeploy with Cloudflare Secrets.

Configure public demo protection

1. Create a Managed Cloudflare Turnstile widget for your exact production hostname. Use a dedicated widget; do not enable pre-clearance or allow arbitrary hostnames.
2. Set TURNSTILE_SECRET_KEY using the runtime secret command above.
3. In your Cloudflare Worker's Settings → Variables and Secrets, add the public runtime variables TURNSTILE_SITE_KEY (your widget's site key) and DEMO_ALLOWED_HOSTS (your own production hostnames, comma-separated). Keep DEMO_PROTECTION_ENABLED="true" and both ratelimits bindings in wrangler.jsonc, with namespace IDs unique to this demo within your account. The shared repository contains no official demo widget configuration; pnpm deploy uses --keep-vars to preserve the variables configured on your Worker.
4. Deploy and verify keyword/image search, detail, product-link lookup, and pagination in a browser. A direct API call without a valid token must return 403. The standalone /api/products/parse endpoint must return DEMO_ENDPOINT_DISABLED; bursts on enabled product routes are throttled with 429.

The browser obtains the public site key from /api/demo/config; no private key is sent to the browser or embedded in a NEXT_PUBLIC_* variable. There is no reusable verification session. Cloudflare validates each token once. Verification service failures or incomplete production configuration fail closed with 503.

pnpm dev defaults to protection off. For local Workers preview, copy .dev.vars.example to .dev.vars; its explicit opt-out is local only. Production defaults to protection enabled. A private, trusted self-hosted installation can deliberately set DEMO_PROTECTION_ENABLED=false; protected public installations need the Cloudflare rate limit bindings (or an equivalent shared limiter added by the operator).

Same-origin checks are an additional browser boundary; a crawler can forge these headers, so they do not replace token verification or rate limiting. This demo does not guarantee that all automated browsers are blocked. For sustained distributed abuse, add hostname-scoped WAF rules in Cloudflare and keep the HIOBuy demo App's usage quota conservative.

pnpm test                         # security and real route-handler regression tests
pnpm exec tsc --noEmit --incremental false

Documentation

For complete API documentation, authentication, marketplace authorization, request parameters, and response schemas, visit:

HioBuy API Documentation

License

MIT

This project is provided as an integration example for developers building with HIOBuy APIs. It is not intended to be a production-ready storefront.