Doublons : À vérifier et Même produit

Quand un import depuis un canal trouve un élément qui pourrait être un produit déjà présent dans Nembol (sans certitude), il ne devine pas et ne le rejette pas : l'élément arrive en pause, avec le statut to_verify (« À vérifier » dans le tableau de bord). Il n'est ni publié, ni synchronisé, ni lié tant que quelqu'un n'a pas décidé.

Trouver ce qui demande votre attention

curl "https://api.nembol.com/rest/v1/products?status=to_verify" \
  -H "Authorization: Bearer $NEMBOL_API_KEY"

Chaque produit en explique la raison dans requires_attention :

{
  "id": "prod_7c1e",
  "status": "to_verify",
  "requires_attention": {
    "reason": "ambiguous_match",
    "message": "The SKU matches more than one product in Nembol",
    "channel": "etsy",
    "conflicting_product_ids": ["prod_51aa", "prod_51ab"],
    "detected_at": "2026-10-13T10:00:00.000Z"
  }
}

Les imports indiquent combien d'éléments sont arrivés ainsi (import.requires_attention dans l'opération). Tant qu'un produit est to_verify, les écritures sur ses annonces répondent 409 product_requires_attention et les écritures d'inventaire par SKU l'ignorent.

Le résoudre

Deux issues possibles :

• C'est le même article qu'un produit existant → fusionnez-les avec POST /products/merge (ci-dessous). Cela le résout aussi.
• Sinon → POST /products/{id}/resolve :

Les motifs Etsy (etsy_shared_quantity, etsy_processing_profiles) sont des réglages du canal, pas des doublons : keep_independent répond 409 resolution_not_applicable pour ceux-ci.

Les annonces ignorées sont listées par GET /ignored_listings ; DELETE /ignored_listings/{id} cesse d'en ignorer une, et le prochain import de ce canal la ramène.

Fusionner deux produits (Même produit)

curl -X POST https://api.nembol.com/rest/v1/products/merge \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_ids": ["prod_51aa", "prod_7c1e"], "survivor_id": "prod_51aa", "dry_run": true}'

• Le produit conservé garde son id ; les autres sont archivés avec merged_into et leurs annonces passent au produit conservé. Un seul stock par variante est alors partagé par tous les canaux.
• Envoyez toujours d'abord dry_run: true et montrez l'aperçu : title, variants et ce que chaque canal affichera (listings).
• choices indique, champ par champ, de quel produit provient une valeur (par défaut : le produit conservé) : title, description, sku, barcode, price, quantity, photos, tags, category. Par exemple : "choices": {"photos": {"from": "prod_7c1e"}, "quantity": {"values": {"var_1": 5}}}. Prendre photos apporte aussi les images des variantes de ce produit. Les canaux gardent leurs propres titres et descriptions.
• Les produits qui ne se ressemblent pas sont listés dans looks_different : les fusionner exige confirm_different: true.
• Refusé quand deux produits sont en ligne sur le même compte de canal (422 same_channel_account).
• Annulable pendant 30 jours avec POST /actions/{id}/undo (l'id se trouve dans l'en-tête Nembol-Action-Id).

Variantes qui ne correspondent pas

Les variantes sont associées par SKU, puis par valeurs d'option. Quand cela échoue, la fusion répond 422 variants_differ avec error.details.matching : les deux listes de variantes et une suggestion. Si manual_allowed vaut true (le produit absorbé est en ligne uniquement sur Etsy, Shopify ou WooCommerce, avec le même nombre de variantes), associez-les vous-même et renvoyez la fusion :

{
  "product_ids": ["prod_51aa", "prod_7c1e"],
  "survivor_id": "prod_51aa",
  "variant_maps": { "prod_7c1e": { "var_e1": "var_a1", "var_e2": "var_a2" } }
}

La correspondance doit être complète et bijective. Après la fusion, les variantes du canal prennent les noms de Nembol (et les SKU quand le canal le permet).

Événements

Une fusion émet product.updated pour le produit conservé (data.merged) et product.deleted pour chaque produit absorbé (data.merged_into). Une résolution émet product.updated (product.deleted pour ignore).

Bonnes pratiques pour les agents

• Ne résolvez ni ne fusionnez jamais de votre propre chef : montrez à la personne les produits en conflit côte à côte et laissez-la choisir.
• Utilisez dry_run avant chaque fusion, et gardez l'id de l'action pour pouvoir annuler.

Dernière mise à jour le 20 octobre 2026