Duplicati: Da controllare e Stesso prodotto

Quando un'importazione da un canale trova un elemento che potrebbe essere un prodotto già presente in Nembol (ma senza certezza), non tira a indovinare e non lo scarta: l'elemento entra in pausa, con stato to_verify ("Da controllare" nella dashboard). Non viene pubblicato, sincronizzato né collegato finché qualcuno non decide.

Trova cosa è da controllare

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

Ogni prodotto spiega il motivo in 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"
  }
}

Le importazioni riportano quanti elementi sono entrati in questo modo (import.requires_attention nell'operazione). Finché un prodotto è to_verify, le scritture sulle inserzioni rispondono 409 product_requires_attention e le scritture di inventario per SKU lo saltano.

Risolvi

Due vie d'uscita:

• È lo stesso articolo di un prodotto esistente → uniscili con POST /products/merge (sotto). Questo lo risolve anche.
• Altrimenti → POST /products/{id}/resolve:

I motivi Etsy (etsy_shared_quantity, etsy_processing_profiles) sono impostazioni del canale, non duplicati: per questi keep_independent risponde 409 resolution_not_applicable.

Le inserzioni ignorate sono elencate da GET /ignored_listings; DELETE /ignored_listings/{id} smette di ignorarne una, e la successiva importazione di quel canale la porta di nuovo dentro.

Unisci due prodotti (Stesso prodotto)

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}'

• Il prodotto superstite mantiene il suo id; gli altri vengono archiviati con merged_into e le loro inserzioni passano al superstite. Da quel momento un unico stock per variante è condiviso da tutti i canali.
• Invia sempre prima dry_run: true e mostra l'anteprima: title, variants e cosa mostrerà ogni canale (listings).
• choices indica, campo per campo, da quale prodotto arriva un valore (predefinito: il superstite): title, description, sku, barcode, price, quantity, photos, tags, category. Ad esempio: "choices": {"photos": {"from": "prod_7c1e"}, "quantity": {"values": {"var_1": 5}}}. Scegliere photos porta anche le immagini delle varianti di quel prodotto. I canali mantengono i propri titoli e descrizioni.
• I prodotti che non si somigliano sono elencati in looks_different: per unirli serve confirm_different: true.
• Rifiutata quando due prodotti sono attivi sullo stesso account del canale (422 same_channel_account).
• Annullabile per 30 giorni con POST /actions/{id}/undo (l'id è nell'header Nembol-Action-Id).

Varianti che non corrispondono

Le varianti vengono abbinate per SKU, poi per valori delle opzioni. Quando non basta, l'unione risponde 422 variants_differ con error.details.matching: entrambi gli elenchi di varianti e un suggestion. Se manual_allowed è true (il prodotto assorbito è attivo solo su Etsy, Shopify o WooCommerce, con lo stesso numero di varianti), abbinale tu e invia di nuovo l'unione:

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

La mappa deve essere completa e biunivoca. Dopo l'unione le varianti del canale prendono i nomi di Nembol (e gli SKU, dove il canale lo consente).

Eventi

Un'unione emette product.updated per il superstite (data.merged) e product.deleted per ogni prodotto assorbito (data.merged_into). Una risoluzione emette product.updated (product.deleted per ignore).

Buone pratiche per gli agenti

• Non risolvere né unire mai di tua iniziativa: mostra alla persona i prodotti in conflitto uno accanto all'altro e lascia scegliere a lei.
• Usa dry_run prima di ogni unione, e conserva l'id dell'azione per annullare.

Ultimo aggiornamento il 20 ottobre 2026