From a keyword to a full category walk
Keyword search gives a quick sample but no second page. Start with `post-1688-search` and a Chinese term in `body.query`, pick a relevant row and read its `category_ids`, which are ordered from broad to leaf. Pass one of those ids as `body.category_id` to `post-1688-category-offers` and raise `body.page` one step at a time while `has_next` stays true, up to the maximum page of 200; each page holds 30 offers.
Vetting a factory before contact
Run `post-1688-supplier-search` with the product keyword. Compare rows on the returned figures, such as `workers`, `floor_area_sqm`, `repeat_buyer_rate` and `third_party_audit`, then take ids from `offer_ids` and pass them one at a time as `body.offer_id` to `post-1688-product-detail` for prices and variants, and to `post-1688-product-reviews` for buyer feedback.
Browsing in another language
For readers who do not read Chinese, call `post-1688-categories` with `body.language` set to, for example, `ru` and `body.depth` set to 1 to get a compact top level, then fetch the deeper levels only when needed; the full tree is about 2.4 MB. Each node keeps its Chinese name in `name_zh`, which helps when matching a category to Chinese search terms.
Pitfalls specific to this data
Calling `post-1688-search` again with the same keyword does not page further: it rotates within roughly 38 distinct offers, so do not treat repeated calls as new coverage. Offer search rows also carry no MOQ or price ladder, and the keyword results are largely promoted listings. An empty factory list from `post-1688-supplier-search` is a real answer that repeating will not change. `review_count` is a lower bound where 1688 shows 100+, and an offer with no reviews yields an empty list with a zero count from `post-1688-product-reviews`. Only the contract names are accepted, so send `body.query` rather than `q` or `keyword`.
[
{
"body": {
"query": "蓝牙耳机"
}
},
{
"body": {
"category_id": "1031910",
"page": 2
}
},
{
"body": {
"offer_id": "864971848115",
"max_rotations": 4
}
}
]Server-side request template
This server-side template shows authentication and request identity using the first operation of this API. Choose the operation for your use case and check its current availability and price on the API page. After a timeout, resend the unchanged request with the same Idempotency-Key.
The gateway request is always POST.
Use a JSON object with the documented path, query, headers and body locations; omit unused locations. input.headers is schema-validated data, not browser request headers. Do not put credentials here. Keep body arrays, scalar values and null as documented; omission is different from null.
# Server-side only. Set ATLAS_API_KEY in your secret manager.
# Set ATLAS_API_ORIGIN to your configured deployment origin.
# Every gateway operation is called with POST.
# Only operations shown as enabled on the API page can be called.
# Generate once per intent; retain the same value on status checks.
REQUEST_ID="$(uuidgen)"
curl --request POST 'https://apigate.vercel.app/api/v1/alibaba-1688/post-1688-categories' \
--header "Content-Type: application/json" \
--header "x-api-key: $ATLAS_API_KEY" \
--header "Idempotency-Key: $REQUEST_ID" \
--data '{"body":{"depth":1,"language":"ru"}}'Integration checklist
- The API key is stored in a server-side secret manager and never sent to a browser.
- Each request carries its own Idempotency-Key, kept until the request has a final answer.
- The integration reads ok and error.code and handles each error code as the error table describes.
- An uncertain POST is inspected using its original identity, never blindly repeated with a new one.
- The operation’s current availability and price have been checked on its API page.