Přechod z Primárního EAN na nový systém Kódů v Mailship

Tento návod vás provede procesem přechodu z používání Primárního EAN (productSku) na nový systém Kódů (codes) u vašich produktů v Mailship. Kódy nabízejí větší flexibilitu – zejména možnost přiřadit jednomu produktu více identifikačních kódů.

Proč přejít na Kódy?

Primární EAN umožňuje ke každému produktu (Internímu SKU) přiřadit pouze jeden identifikační kód. Nový systém Kódů přináší tyto výhody:

• Více kódů na jednom produktu – Jeden produkt (Interní SKU) může mít přiřazeno více kódů současně.

• Lepší podpora různých typů čárových kódů – Ke každému kódu se ukládá jeho typ (EAN8, EAN13, EAN14, UPC-A, UPC-E).

Důležité podmínky

Než začnete s přechodem, mějte na paměti:

Kódy nelze používat společně s Primárním EAN.

Systém neumožňuje mít na produktu vyplněný Primární EAN a současně používat Kódy. Pokud odešlete API požadavek obsahující obě pole (productSku i codes), dostanete chybovou odpověď:

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

Přechod na Kódy je možný pouze přes API.

Kódy lze spravovat (přidávat, upravovat) pouze prostřednictvím API. V portálu Mailship je sice možné Kódy zobrazit i editovat, nicméně jiné synchronizace prozatím Kódy nepodporují a proto je vhodné zůstávat u používání Primárního EAN.

Změna primárního kódu je možná jen při nulové skladové zásobě.

Pokud máte na produktu skladovou zásobu, nelze měnit ani mazat primární kódy. V takovém případě je potřeba nejprve zásobu vyskladnit. Pokud se pokusíte o update produktu se skladovou zásobou, dostanete chybovou odpověď:

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

Postup přechodu krok za krokem (API)

Krok 1: Zjistěte aktuální stav produktu

Nejprve si ověřte, jaký Primární EAN je na produktu aktuálně nastaven.

API požadavek:

GET /api/product/{product_id}

V odpovědi najdete pole productSku (Primární EAN) a codes (Kódy). Pokud produkt používá Primární EAN, bude pole productSku vyplněné a pole codes bude prázdné ([]).

Krok 2: Ověřte skladovou zásobu

Pokud chcete na produktu změnit primární kód (což při přechodu z Primárního EAN na Kódy děláte), ujistěte se, že produkt nemá skladovou zásobu, případně zásobu vyskladněte.

Pokud produkt skladovou zásobu má a přesto chcete provést přechod, kontaktujte zákaznickou podporu.

Krok 3: Smažte Primární EAN a přidejte Kódy v jednom požadavku

Přechod provedete jedním API požadavkem typu PUT, ve kterém současně:

1. Nastavíte productSku na null (smažete Primární EAN).

2. Přidáte nové Kódy do pole codes, přičemž alespoň jeden z nich musí být označen jako primary: true.

API požadavek:

PUT /api/product/{product_id}

Tělo požadavku (příklad):

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

V tomto příkladu:

• Primární EAN (productSku) se smaže (nastaví na null).

• Přidají se dva nové kódy – EAN13 jako primární kód a EAN8 jako sekundární.

Tip: Pokud chcete zachovat hodnotu starého Primárního EAN jako jeden z nových Kódů, jednoduše ji přidejte do pole codes:

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

This way, the existing EAN is effectively "moved" from the productSku field into the new Codes system.

Tímto způsobem se stávající EAN „přesune" z pole productSku do nového systému Kódů.

Krok 4: Ověřte výsledek

Po úspěšném provedení požadavku (odpověď 200 OK) ověřte, že:

• Pole productSku je null.

• Pole codes obsahuje váš nový kód/kódy.

• Jeden z kódů má příznak primary: true.

GET /api/product/{product_id}

Pravidla pro práci s Kódy

Při práci s Kódy dodržujte tato pravidla:

• Alespoň jeden primární kód – Mezi kódy produktu musí být vždy alespoň jeden kód označený jako primary: true.

• Unikátnost kódů – Hodnoty kódů musí být unikátní v rámci jednoho produktu. Stejný kód nemůže být přiřazen jako primární kód dvou různých produktů v jedné organizaci.

• Kódy vs. productSku jiného produktu – Hodnota kódu nesmí být stejná jako productSku (Primární EAN) jiného existujícího produktu v organizaci.

• Podporované typy kódů – ean8, ean13, ean14, upcA, upcE, unknown.

Přidávání a odebírání Kódů u existujícího produktu

Přidání dalšího kódu

Jakmile produkt používá Kódy, můžete přidat další kódy pomocí API požadavku PUT. Do pole codes uveďte všechny kódy (stávající i nové).

Příklad – přidání dalšího kódu k produktu, který již má jeden kód:

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

Odebrání kódu

Kód odeberete tak, že ho jednoduše vynecháte z pole codes v PUT požadavku.

Pozor: Odebírání kódů je možné pouze pokud má produkt nulovou skladovou zásobu. Pokud má produkt zásobu a pokusíte se odebrat kód, dostanete chybovou odpověď: „There are items already in stock."

Časté otázky

Musím vyplňovat typ kódu?

Nemusíte, pokud si nejste jistí, jaký typ kódu produkt má, stačí zvolit typ kódu ‘unknown’.

Mohu přejít zpět z Kódů na Primární EAN?

Ano, stačí v PUT požadavku nastavit productSku na požadovanou hodnotu a nevkládat pole codes. Doporučujeme to ale nedělat – systém Kódů je novější řešení a Primární EAN je funkce, která bude postupně nahrazena.

Musím migrovat všechny produkty najednou?

Ne, přechod můžete provádět postupně, produkt po produktu. Každý produkt může nezávisle používat buď Primární EAN, nebo Kódy.

Mohu editovat Kódy z portálu Mailship?

Pokud nemají skladovou zásobu, je možné přidávat nové Kódy přes portál Mailship. Editovat stávající je možné následně pouze přes zákaznickou podporu nebo přes API.

Potřebujete pomoc?

Pokud si nejste jistí, jak přechod provést, nebo potřebujete pomoci s migrací většího počtu produktů, kontaktujte naši zákaznickou podporu.