Importa prodotti

POST /imports esegue la stessa importazione della dashboard di Nembol, in background, con le stesse regole. La tua chiave deve avere products:write.

Importa il catalogo di un canale

curl -X POST https://api.nembol.com/rest/v1/imports \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_account_id": "chac_66f0a1",
       "filters": {"status": "Active", "quantity": {"operator": "gt", "value": 0}}}'

{
  "id": "op_8fd2c1",
  "object": "operation",
  "type": "import.channel",
  "status": "processing",
  "import": {
    "source": "channel",
    "channel_account_id": "chac_66f0a1",
    "filters": { "status": "Active", "quantity": { "operator": "gt", "value": 0 } },
    "warnings": [],
    "processed": 0
  }
}

Cosa entra, esattamente come in un'importazione dalla dashboard:

• Solo articoli nuovi. Gli articoli già importati da quell'account del canale vengono saltati (importazioni da canale; per un CSV vedi sotto), quindi eseguire di nuovo un'importazione porta solo le novità.
• Nessun duplicato per SKU. Un articolo il cui SKU corrisponde esattamente a un solo prodotto già presente in Nembol (con lo stesso numero di varianti) viene collegato a esso, e il prodotto non viene sovrascritto. Le corrispondenze ambigue non vengono importate e sono conteggiate in not_imported.
• Il limite di prodotti del piano blocca la creazione; gli articoli oltre il limite sono conteggiati in not_imported. GET /billing ti dice prima quanto spazio resta.

Filtri per una singola importazione

Senza filters l'importazione usa le impostazioni di importazione dell'account del canale (le stesse della dashboard). filters le sostituisce solo per questa importazione; le impostazioni salvate non cambiano.

L'elenco completo dei valori è nel riferimento API.

Leggi gli avvisi

import.warnings contiene note in linguaggio semplice da riferire alla persona prima che faccia affidamento sul risultato. Ad esempio, con alcuni piani alcuni filtri vengono ignorati, oppure lo store ha già raggiunto il suo limite di prodotti. Il collegamento per SKU funziona con ogni piano.

Importa un CSV

Invia il contenuto del file come testo:

curl -X POST https://api.nembol.com/rest/v1/imports \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @- <<'JSON'
{"csv": "id,title,description,quantity,price,sku\nMUG-1,Blue mug,A blue mug,5,12.50,MUG-BLUE\n"}
JSON

Colonne obbligatorie: price e quantity (oppure solo sku-code, per aggiornare varianti esistenti per SKU: cambiano solo le colonne che invii). Vengono verificate prima di iniziare: un file senza di esse risponde 422 validation_failed con error.details.missing_columns. id, title, description e il resto sono facoltativi; senza id una riga ne riceve uno derivato dal suo contenuto, così ricaricando lo stesso file si ritrovano gli stessi prodotti. Vengono riconosciute anche le esportazioni di Shopify, eBay e inkFrog; le colonne non riconosciute sono elencate in import.warnings.

Righe reimportate, una sola regola: una riga il cui id corrisponde a un prodotto dello store (il suo id prod_… da un'esportazione, o l'id della riga che lo ha creato) lo aggiorna (updated), senza mai creare un duplicato; una riga senza nulla di nuovo viene conteggiata come unchanged. Per un CSV, import.total è noto fin dall'inizio.

Segui l'avanzamento

Interroga GET /operations/{id}, oppure iscriviti a operation.completed:

{
  "id": "op_8fd2c1",
  "type": "import.channel",
  "status": "succeeded",
  "import": {
    "processed": 342,
    "created": 310,
    "linked": 32,
    "requires_attention": 3,
    "not_imported": 4,
    "error": null
  }
}

processed cresce mentre l'importazione è in corso. Per un'importazione da canale conta i prodotti creati finora (gli articoli collegati a un prodotto esistente vengono conteggiati alla fine), per un CSV le righe elaborate. created, updated, linked e not_imported vengono impostati al termine. È in corso una sola importazione alla volta per account del canale (e un solo CSV): una seconda richiesta risponde 409 import_already_running.

requires_attention conta gli articoli che potrebbero già esistere in Nembol ma senza certezza: entrano in pausa (to_verify) finché qualcuno non decide (vedi Duplicati).

Annulla un'importazione

L'annullamento rimuove prodotti da Nembol, quindi richiede la stessa conferma in due passaggi di ogni azione irreversibile. La prima chiamata risponde 409 confirmation_required con un confirmation.token; mostra il suo riepilogo alla persona e, se è d'accordo, ripeti la stessa richiesta con il token:

curl -X POST https://api.nembol.com/rest/v1/imports/op_8fd2c1/undo \
  -H "Authorization: Bearer $NEMBOL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Nembol-Confirmation: cfm_3kTq9Xb2"

Invia {"include_modified": true} come corpo per rimuovere anche i prodotti creati e modificati dopo l'importazione.

{
  "import": {
    "undone_at": "2026-10-08T10:12:00.000Z",
    "undo": {
      "removed": 309,
      "unlinked": 32,
      "kept": { "live_on_a_channel": 1, "modified_after_import": 0 }
    }
  }
}

L'annullamento rimuove da Nembol ciò che l'importazione ha aggiunto (i prodotti che ha creato e i collegamenti che ha aggiunto ai prodotti esistenti) e non tocca mai nulla sul canale: le tue inserzioni eBay o Etsy restano esattamente come sono. Nell'API, le inserzioni dei prodotti rimossi spariscono con loro: escono da GET /listings e rispondono 404 per id.

• I prodotti ora attivi su un canale vengono sempre mantenuti.
• I prodotti modificati dopo l'importazione vengono mantenuti, a meno che tu non passi "include_modified": true.
• Ogni importazione può essere annullata una sola volta, dopo che è terminata.

Dopo un annullamento, importare di nuovo riporta gli stessi articoli.

Buone pratiche per gli agenti

• Controlla GET /billing (spazio disponibile nel piano) prima di una grande importazione, e di' quanti prodotti lo store può ancora aggiungere.
• Spiega alla persona cosa farà l'importazione (solo articoli nuovi, collegamento per SKU, i filtri che hai impostato) e riferiscile import.warnings.
• Conserva l'id dell'operazione: è ciò che ti serve per annullare.

Ultimo aggiornamento il 20 ottobre 2026