API per Quick Order Form

Questa pagina descrive la Public API per la famiglia di funzioni Quick Order Form. Un unico endpoint gestisce tutti e tre i tipi di record correlati, distinti da un campo type:

• quick_order_page: una pagina Quick Order Form autonoma.
• quick_buy_collection: la funzione Quick Buy nelle pagine delle collezioni e nelle schede prodotto.
• quick_buy_variant: la Variant Table in una pagina prodotto.

Tutte e 4 le operazioni condividono lo stesso URL di base, le stesse intestazioni e la stessa autenticazione descritte in API pubbliche.

Crea un record

Endpoint

POST https://wholesale.samita.io/api/v1/quick-order-forms

Intestazioni della richiesta

Header	Descrizione	Obbligatorio
X-SAMITA-API-KEY	Chiave API fornita nell’app Wholesale	Sì
X-SAMITA-SHOP-URL	Dominio del negozio Shopify nel formato xxx.myshopify.com	Sì
CONTENT-TYPE	Deve essere application/json	Sì

Questa API richiede l’autorizzazione Create sulla chiave API, per lo specifico type che stai creando.

Campi comuni (tutti i tipi)

Campo	Tipo	Obbligatorio	Descrizione
title	stringa, max 255	Sì	Il nome del record nell’app.
status	booleano	Sì	Indica se è attivo.
type	stringa	Sì	quick_order_page, quick_buy_collection o quick_buy_variant.

Gli altri campi obbligatori dipendono da type:

Campo	Tipo	Note
apply_product	oggetto (obbligatorio)	type: products o collections.
apply_product.product_ids	array	Obbligatorio quando type è products.
apply_product.collection_ids	array	Obbligatorio quando type è collections.
display_on_page	stringa (obbligatorio)	L’handle della pagina Shopify in cui viene mostrato questo modulo.
pagination	oggetto (obbligatorio)	type: pagination o load_more_button; per_page: numero da 1 a 50.
columns	oggetto (obbligatorio)	product_stock: booleano, mostra o nasconde la colonna della disponibilità.

Esempio:

{
  "title": "Wholesale Order Form",
  "status": true,
  "type": "quick_order_page",
  "apply_product": {
    "type": "collections",
    "collection_ids": [123456789]
  },
  "display_on_page": "wholesale-order-form",
  "pagination": {
    "type": "pagination",
    "per_page": 20
  },
  "columns": {
    "product_stock": true
  }
}

Campo	Tipo	Note
apply_product	oggetto (obbligatorio)	type: all, products, collections o product-tags, con i corrispondenti product_ids / collection_ids / product_tags.
exclude_product	oggetto (obbligatorio)	type: none, products o collections, con i relativi ID.
apply_customer	oggetto (obbligatorio)	type: all, logged, non-logged o customer-tags, con tags quando applicabile.
exclude_customer	oggetto (obbligatorio)	type: none o customer-tags, con tags quando applicabile.
display_on_pages	array (obbligatorio)	Uno qualsiasi tra index, collection, search, another_page.
columns	oggetto (obbligatorio)	Booleani: stock_status, quantity, variant, volume_discount, add_to_cart.

Esempio:

{
  "title": "Quick Buy on Collections",
  "status": true,
  "type": "quick_buy_collection",
  "apply_product": { "type": "all", "product_ids": [], "product_tags": [], "collection_ids": [] },
  "exclude_product": { "type": "none", "product_ids": [], "collection_ids": [] },
  "apply_customer": { "type": "customer-tags", "tags": ["wholesale"] },
  "exclude_customer": { "type": "none", "tags": [] },
  "display_on_pages": ["collection", "index"],
  "columns": {
    "stock_status": true,
    "quantity": true,
    "variant": true,
    "volume_discount": true,
    "add_to_cart": true
  }
}

Campo	Tipo	Note
apply_product	oggetto (obbligatorio)	Stessa struttura di quick_buy_collection.
exclude_product	oggetto (obbligatorio)	Stessa struttura di quick_buy_collection.
apply_customer	oggetto (obbligatorio)	Stessa struttura di quick_buy_collection.
exclude_customer	oggetto (obbligatorio)	Stessa struttura di quick_buy_collection.
template	stringa (obbligatorio)	default o matrix-column.
columns	oggetto (obbligatorio)	stock: booleano, mostra o nasconde la colonna della disponibilità.

Esempio:

{
  "title": "Variant Table",
  "status": true,
  "type": "quick_buy_variant",
  "apply_product": { "type": "all", "product_ids": [], "product_tags": [], "collection_ids": [] },
  "exclude_product": { "type": "none", "product_ids": [], "collection_ids": [] },
  "apply_customer": { "type": "logged", "tags": [] },
  "exclude_customer": { "type": "none", "tags": [] },
  "template": "default",
  "columns": {
    "stock": true
  }
}

Nota

Gli oggetti apply_product/exclude_product/apply_customer/exclude_customer controllano le stesse regole di targeting che imposteresti nell’interfaccia dell’app. Stile, ordine delle colonne e altre impostazioni di visualizzazione usano valori predefiniti sensati alla creazione: per modificarli, aggiorna il record in seguito o modificalo nell’app.

Risposta

200 – Success restituisce il record creato. Vedi l’esempio in Recupera un record più sotto.

Aggiorna un record

PUT https://wholesale.samita.io/api/v1/quick-order-forms/{id}

Stesse intestazioni di Crea. Invia solo i campi che vuoi modificare: title, status, configs e product_configs sono tutti facoltativi; i campi non specificati mantengono il valore attuale. Questa API richiede l’autorizzazione Update.

Recupera un record

GET https://wholesale.samita.io/api/v1/quick-order-forms/{id}

Stesse intestazioni di Crea, nessun corpo della richiesta. Questa API richiede l’autorizzazione View.

Esempio di 200 – Success (type: quick_order_page):

{
  "id": 1,
  "title": "Wholesale Order Form",
  "status": true,
  "type": "quick_order_page",
  "apply_product": {
    "type": "collections",
    "product_ids": [],
    "collection_ids": [123456789]
  },
  "display_on_page": "wholesale-order-form",
  "pagination": {
    "type": "pagination",
    "per_page": 20
  },
  "columns": {
    "product": true,
    "product_stock": true,
    "quantity": true,
    "action": true
  },
  "created_at": "2026-01-15T10:00:00",
  "updated_at": "2026-01-15T10:00:00"
}

Elimina un record

DELETE https://wholesale.samita.io/api/v1/quick-order-forms/{id}

Stesse intestazioni di Crea. Passa un parametro ids, un elenco di ID dei record da eliminare separati da virgola (come parametro della query string o come campo del corpo JSON), ad esempio ids=1,2,3. Questa API richiede l’autorizzazione Delete.

200 – Success:

{
  "success": true
}

Risposte di errore

Tutti e 4 gli endpoint condividono le stesse risposte di errore del resto della Public API: consulta API pubbliche per 401 Unauthorized, 403 Forbidden e 429 Too Many Requests.