API pour Quick Order Form

Cette page présente l’API publique de la famille de fonctionnalités Quick Order Form. Un seul point de terminaison gère les trois types d’enregistrements associés, distingués par un champ type :

• quick_order_page : une page Quick Order Form autonome.
• quick_buy_collection : la fonctionnalité Quick Buy sur les pages de collection et les fiches produit.
• quick_buy_variant : le tableau des variantes sur une page produit.

Les 4 opérations partagent la même URL de base, les mêmes en-têtes et la même authentification, décrits dans API publiques.

Créer un enregistrement

Point de terminaison

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

En-têtes de la requête

En-tête	Description	Obligatoire
X-SAMITA-API-KEY	Clé d’API fournie dans l’application Wholesale	Oui
X-SAMITA-SHOP-URL	Domaine de la boutique Shopify au format xxx.myshopify.com	Oui
CONTENT-TYPE	Doit être application/json	Oui

Cette API nécessite l’autorisation Create sur la clé d’API, pour le type précis que vous créez.

Champs communs (tous les types)

Champ	Type	Obligatoire	Description
title	chaîne, 255 caractères max.	Oui	Le nom de l’enregistrement dans l’application.
status	booléen	Oui	Indique s’il est actif.
type	chaîne	Oui	quick_order_page, quick_buy_collection ou quick_buy_variant.

Les autres champs obligatoires dépendent de type :

Champ	Type	Remarques
apply_product	objet (obligatoire)	type : products ou collections.
apply_product.product_ids	tableau	Obligatoire lorsque type vaut products.
apply_product.collection_ids	tableau	Obligatoire lorsque type vaut collections.
display_on_page	chaîne (obligatoire)	Le handle de la page Shopify sur laquelle ce formulaire s’affiche.
pagination	objet (obligatoire)	type : pagination ou load_more_button ; per_page : nombre de 1 à 50.
columns	objet (obligatoire)	product_stock : booléen, pour afficher ou masquer la colonne de stock.

Exemple :

{
  "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
  }
}

Champ	Type	Remarques
apply_product	objet (obligatoire)	type : all, products, collections ou product-tags, avec product_ids / collection_ids / product_tags correspondants.
exclude_product	objet (obligatoire)	type : none, products ou collections, avec les identifiants correspondants.
apply_customer	objet (obligatoire)	type : all, logged, non-logged ou customer-tags, avec tags le cas échéant.
exclude_customer	objet (obligatoire)	type : none ou customer-tags, avec tags le cas échéant.
display_on_pages	tableau (obligatoire)	Une ou plusieurs valeurs parmi index, collection, search, another_page.
columns	objet (obligatoire)	Booléens : stock_status, quantity, variant, volume_discount, add_to_cart.

Exemple :

{
  "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
  }
}

Champ	Type	Remarques
apply_product	objet (obligatoire)	Même structure que quick_buy_collection.
exclude_product	objet (obligatoire)	Même structure que quick_buy_collection.
apply_customer	objet (obligatoire)	Même structure que quick_buy_collection.
exclude_customer	objet (obligatoire)	Même structure que quick_buy_collection.
template	chaîne (obligatoire)	default ou matrix-column.
columns	objet (obligatoire)	stock : booléen, pour afficher ou masquer la colonne de stock.

Exemple :

{
  "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
  }
}

Note

Les objets apply_product, exclude_product, apply_customer et exclude_customer contrôlent les mêmes règles de ciblage que celles que vous définiriez dans l’interface de l’application. Le style, l’ordre des colonnes et les autres paramètres d’affichage utilisent des valeurs par défaut adaptées à la création : pour les modifier, mettez ensuite l’enregistrement à jour ou modifiez-le dans l’application.

Réponse

200 – Success renvoie l’enregistrement créé. Consultez l’exemple sous Get a record ci-dessous.

Mettre à jour un enregistrement

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

Mêmes en-têtes que pour la création. N’envoyez que les champs à modifier : title, status, configs et product_configs sont tous facultatifs ; les champs non précisés conservent leur valeur actuelle. Cette API nécessite l’autorisation Update.

Obtenir un enregistrement

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

Mêmes en-têtes que pour la création, sans corps de requête. Cette API nécessite l’autorisation View.

Exemple de réponse 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"
}

Supprimer un enregistrement

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

Mêmes en-têtes que pour la création. Transmettez un paramètre ids, une liste d’identifiants d’enregistrements à supprimer séparés par des virgules (en paramètre de la chaîne de requête ou en champ du corps JSON), par exemple ids=1,2,3. Cette API nécessite l’autorisation Delete.

200 – Success :

{
  "success": true
}

Réponses d’erreur

Les 4 points de terminaison partagent les mêmes réponses d’erreur que le reste de l’API publique. Consultez API publiques pour 401 Unauthorized, 403 Forbidden et 429 Too Many Requests.