HomeiCloud文档Hub Gateway API
Apply to List
A distributor applies to list a B2B product.
POST /api/hub/applicationsUse Case
A distributor applies to list a product. This find-or-creates the distributor's
reseller record (by hubCustomerId), then upserts a product authorization in
applied status for a B2B admin to review. Only publish-gated (visible + priced)
products can be applied to. Idempotent — safe to re-fire.
Header Parameters
| Parameter | Data Type | Required | Description |
|---|---|---|---|
x-hub-api-key | string | true | Shared Hub service key. |
Content-Type | string | true | application/json. |
Request Body Parameters
| Parameter | Data Type | Required | Description |
|---|---|---|---|
hubCustomerId | string | true | The Hub customer / company id. |
productId | string | true | Must be publish-gated (visible + priced). |
name | string | false | Distributor company name (per-reseller, max 200). |
email | string | false | Distributor contact email (max 320). |
name / email are stored on the reseller, not per-product, and are only
refreshed when supplied — an omitted field keeps the prior value. Do not
pass a product title as name; it will overwrite the distributor name shown in
the admin queue.
Example Request
curl -X POST "https://<your-b2b-host>/api/hub/applications" \
-H "x-hub-api-key: $HUB_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"hubCustomerId": "hub_cust_1",
"productId": "prod_123",
"name": "Acme Distributors",
"email": "buyer@acme.com"
}'Response Parameters
| Parameter | Data Type | Description |
|---|---|---|
productId | string | Echoed product id. |
status | string | applied, or the current status of an existing row. |
Example Response
{ "productId": "prod_123", "status": "applied" }Success & Error Responses
| Status | Body | When |
|---|---|---|
201 | { "productId": "prod_123", "status": "applied" } | New application created. |
200 | { "productId": "prod_123", "status": "applied" } | Re-opened a previously rejected application. |
200 | { "productId": "prod_123", "status": "<current>" } | Existing applied / authorized row returned unchanged. |
404 | { "error": "Product not found" } | Not visible / not priced. |
400 | { "error": "Invalid request body" } | Schema validation failure. |
401 | { "error": "Unauthorized" } | Bad or missing API key. |
500 | { "error": "Failed to submit application" } | Unhandled server error. |