Groupes de produits

Les groupes de produits relient les produits qui représentent un même modèle ou une même famille. Un groupe définit des axes d'options stables, par exemple la couleur ou la matière. Chaque appartenance produit renseigne la valeur choisie pour ces axes.

Utilisez les groupes lorsque l'assistant doit comprendre que plusieurs produits du catalogue sont des alternatives dans une même famille. Les collections répondent à un autre besoin : elles organisent les produits pour le merchandising et les périmètres de recommandation.

Ordre de synchronisation recommandé

1. Créez ou mettez à jour les groupes de produits.
2. Créez ou mettez à jour les produits avec group_memberships.
3. Supprimez les groupes obsolètes seulement après avoir envoyé les nouvelles appartenances.

Une écriture produit qui référence un groupe absent renvoie 422 product_group_not_found. Une option absente renvoie 422 product_group_option_not_found.

L'objet ProductGroup

Champ	Type	Requis	Description
external_id	string	Oui	Votre identifiant stable. Il sert de clé d'upsert et de référence dans les produits.
humind_id	string	Renvoyé seulement	ObjectId Humind interne de 24 caractères.
name	string	Oui	Nom d'affichage, 500 caractères maximum.
handle	string	Non	Handle en minuscules séparé par des tirets, unique par company. Humind dérive api-<external_id-slug> s'il est omis à la création.
options	object[]	Non	Jusqu'à 50 axes d'options. Omettez ce champ lors d'un upsert pour conserver les options actuelles. Envoyez [] pour toutes les supprimer.
created_at	ISO 8601	Renvoyé seulement	Timestamp de création en UTC.
updated_at	ISO 8601	Renvoyé seulement	Timestamp de dernière modification en UTC.

Chaque option contient :

Champ	Type	Requis	Description
external_id	string	Oui	Identifiant stable utilisé dans les appartenances produit, par exemple color.
name	string	Oui	Libellé d'affichage, par exemple Couleur. Il peut être renommé sans changer l'identifiant.

Les external_id et les noms d'options doivent chacun être uniques dans le groupe.

Créer ou upserter

POST /product-groups crée un groupe ou met à jour celui qui possède le même external_id.

Scope requis : catalog:write

curl -X POST https://api.thehumind.com/public/v1/product-groups \
  -H "Authorization: Bearer hmd_live_..." \
  -H "Idempotency-Key: 96e32e41-2dac-4338-b071-150d30641eb5" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "canape-modele-1",
    "name": "Canapé modèle 1",
    "handle": "canape-modele-1",
    "options": [
      { "external_id": "color", "name": "Couleur" },
      { "external_id": "material", "name": "Matière" }
    ]
  }'

La réponse est 201 Created pour un nouveau groupe et 200 OK pour une mise à jour.

Rattacher un produit

Ajoutez group_memberships à tout payload produit accepté par POST /products, POST /products/batch, PUT /products/{id}, PATCH /products/{id} ou par un import produit NDJSON.

{
  "external_id": "canape-modele-1-bleu-velours",
  "title": "Canapé modèle 1, velours bleu",
  "group_memberships": [
    {
      "group_external_id": "canape-modele-1",
      "selected_options": [
        { "option_external_id": "color", "value": "Bleu" },
        { "option_external_id": "material", "value": "Velours" }
      ]
    }
  ],
  "variants": [
    {
      "external_id": "canape-modele-1-bleu-velours-default",
      "price": 1290,
      "currency": "EUR"
    }
  ]
}

Omettre group_memberships conserve les appartenances existantes gérées par l'API publique. Envoyer group_memberships: [] les retire toutes pour ce produit. Humind conserve les appartenances gérées par Shopify et les autres connecteurs internes.

Lister et récupérer

Méthode	Chemin	Scope	Description
GET	/product-groups	catalog:read	Liste paginée par curseur. Accepte handle, limit et cursor.
GET	/product-groups/{id}	catalog:read	Récupère par api:<external_id> ou humind_id.

Seuls les groupes créés par l'API publique sont renvoyés. Les groupes gérés par les connecteurs ne sont pas exposés.

Remplacer et patcher

Méthode	Chemin	Scope	Description
PUT	/product-groups/{id}	catalog:write	Remplace avec un payload ProductGroup complet.
PATCH	/product-groups/{id}	catalog:write	Met à jour uniquement les champs fournis.

Quand external_id est présent dans un body PUT ou PATCH, il doit correspondre au groupe identifié par l'URL. Supprimer une option retire aussi les sélections de cette option sur les produits membres.

Upsert par batch

POST /product-groups/batch accepte de 1 à 500 groupes sous forme de tableau direct ou { "items": [...] }. Les éléments sont traités indépendamment et l'endpoint renvoie 207 Multi-Status.

Si un external_id apparaît plusieurs fois, seul le premier élément est traité. Les doublons suivants renvoient duplicate_external_id_in_batch.

Supprimer

DELETE /product-groups/{id} supprime définitivement le groupe géré par l'API publique et retire cette appartenance de tous les produits. Les produits eux-mêmes ne sont jamais supprimés.

Scope requis : catalog:write

L'endpoint renvoie 204 No Content.