Guida alla migrazione dall'EAN primario ai Codici in Mailship

Questa guida vi accompagnerà nel processo di migrazione dall'utilizzo dell'EAN primario (productSku) al nuovo sistema di Codici per i vostri prodotti in Mailship. I Codici offrono una maggiore flessibilità - in particolare, la possibilità di assegnare più codici di identificazione a un singolo prodotto.

Perché passare ai Codici?

L'EAN primario consente di assegnare un solo codice di identificazione a ciascun prodotto (SKU interno). Il nuovo sistema di Codici offre i seguenti vantaggi:

• Più codici per prodotto - A un singolo prodotto (SKU interno) possono essere assegnati più codici contemporaneamente.

• Migliore supporto per diversi tipi di codice a barre - Ogni codice memorizza il proprio tipo (EAN8, EAN13, EAN14, UPC-A, UPC-E).

Condizioni importanti

Prima di iniziare la migrazione, tenete presente quanto segue:

I Codici non possono essere utilizzati insieme all'EAN primario.

Il sistema non consente che un prodotto abbia l'EAN primario compilato e allo stesso tempo utilizzi i Codici. Se inviate una richiesta API contenente entrambi i campi (productSku e codes), riceverete una risposta di errore:

"Provide product either via 'productSku' field or 'codes' field, not both at the same time."

La migrazione ai Codici è possibile solo tramite API.

I Codici possono essere gestiti (aggiunti, modificati) solo tramite l'API. Sebbene sia possibile visualizzare e modificare i Codici nel portale Mailship, le altre sincronizzazioni non supportano ancora i Codici, quindi è consigliabile rimanere con l'EAN primario per quelle.

La modifica del codice primario è possibile solo quando la quantità in magazzino è zero.

Se un prodotto ha scorte disponibili, i codici primari non possono essere modificati o eliminati. In tal caso, le scorte devono prima essere esaurite. Se tentate di aggiornare un prodotto che ha scorte, riceverete una risposta di errore:

"Not possible to update 'productSku'. There are items already in stock."

Processo di migrazione passo per passo (API)

Passo 1: Verificare lo stato attuale del prodotto

Per prima cosa, verificate quale EAN primario è attualmente impostato sul prodotto.

Richiesta API:

GET /api/product/{product_id}

Nella risposta troverete il campo productSku (EAN primario) e il campo codes (Codici). Se il prodotto utilizza l'EAN primario, il campo productSku sarà compilato e il campo codes sarà vuoto ([]).

Passo 2: Verificare la quantità in magazzino

Se volete modificare il codice primario del prodotto (cosa che state facendo quando migrate dall'EAN primario ai Codici), assicuratevi che il prodotto non abbia scorte disponibili, oppure esaurite prima le scorte.

Se il prodotto ha scorte e desiderate comunque procedere con la migrazione, contattate l'assistenza clienti.

Passo 3: Eliminare l'EAN primario e aggiungere i Codici in un'unica richiesta

La migrazione viene eseguita con un'unica richiesta API PUT, nella quale contemporaneamente:

• Impostate productSku su null (eliminazione dell'EAN primario).

• Aggiungete nuovi Codici all'array codes, con almeno uno di essi contrassegnato come primary: true.

Richiesta API:

PUT /api/product/{product_id}

Corpo della richiesta (esempio):

{
    "productSku": null,
    "codes": [
        {
            "value": "8594012345678",
            "type": "ean13",
            "primary": true
        },
        {
            "value": "1234567",
            "type": "ean8",
            "primary": false
        }
    ]
}

In questo esempio:

• L'EAN primario (productSku) viene eliminato (impostato su null).

• Vengono aggiunti due nuovi codici - EAN13 come codice primario ed EAN8 come codice secondario.

Suggerimento: Se volete mantenere il valore del vecchio EAN primario come uno dei nuovi Codici, aggiungetelo semplicemente all'array codes:

{
    "productSku": null,
    "codes": [
        {
            "value": "ORIGINAL-EAN-VALUE",
            "type": "ean13",
            "primary": true
        }
    ]
}

In questo modo, l'EAN esistente viene effettivamente "spostato" dal campo productSku al nuovo sistema di Codici.

Passo 4: Verificare il risultato

Dopo una richiesta riuscita (risposta 200 OK), verificate che:

• Il campo productSku sia null.

• Il campo codes contenga i vostri nuovi codici.

• Uno dei codici abbia il flag primary: true.

GET /api/product/{product_id}

Regole per lavorare con i Codici

Quando lavorate con i Codici, seguite queste regole:

• Almeno un codice primario - Deve sempre esserci almeno un codice contrassegnato come primary: true tra i codici del prodotto.

• Unicità del codice - I valori dei codici devono essere unici all'interno di un singolo prodotto. Lo stesso codice non può essere assegnato come codice primario di due prodotti diversi all'interno della stessa organizzazione.

• Codici vs. productSku di un altro prodotto - Il valore di un codice non deve essere uguale al productSku (EAN primario) di un altro prodotto esistente nell'organizzazione.

• Tipi di codice supportati - ean8, ean13, ean14, upcA, upcE, unknown.

Aggiunta e rimozione di Codici su un prodotto esistente

Aggiunta di un codice aggiuntivo

Una volta che un prodotto utilizza i Codici, potete aggiungere altri codici tramite una richiesta API PUT. Includete tutti i codici (esistenti e nuovi) nell'array codes.

Esempio - aggiunta di un codice aggiuntivo a un prodotto che ha già un codice:

{
    "codes": [
        {
            "value": "8594012345678",
            "primary": true
        },
        {
            "value": "9876543210123",
            "type": "ean13",
            "primary": false
        }
    ]
}

Rimozione di un codice

Per rimuovere un codice, omettetelo semplicemente dall'array codes nella richiesta PUT.

Nota: La rimozione dei codici è possibile solo quando il prodotto ha scorte pari a zero. Se il prodotto ha scorte e tentate di rimuovere un codice, riceverete una risposta di errore: "There are items already in stock."

Domande frequenti

Devo compilare il tipo di codice?

No - se non siete sicuri del tipo di codice a barre del prodotto, selezionate semplicemente unknown come tipo di codice.

Posso tornare dai Codici all'EAN primario?

Sì - impostate semplicemente productSku sul valore desiderato nella richiesta PUT e non includete il campo codes. Tuttavia, lo sconsigliamo - il sistema di Codici è la soluzione più recente e l'EAN primario è una funzionalità che verrà gradualmente eliminata.

Devo migrare tutti i prodotti contemporaneamente?

No - la migrazione può essere effettuata gradualmente, prodotto per prodotto. Ogni prodotto può utilizzare indipendentemente l'EAN primario o i Codici.

Posso modificare i Codici dal portale Mailship?

Se un prodotto non ha scorte, è possibile aggiungere nuovi Codici tramite il portale Mailship. La modifica dei codici esistenti è successivamente possibile solo tramite l'assistenza clienti o tramite l'API.

Hai bisogno di aiuto?

Se non sei sicuro di come procedere con la migrazione, o hai bisogno di assistenza per migrare un numero elevato di prodotti, contatta il nostro team di assistenza clienti.