WooCommerce 11.2: import CSV i audyt EAN przed aktualizacją

W WooCommerce 11.2 import CSV po GTIN, EAN lub ISBN ma aktualizować istniejący produkt, gdy w wierszu nie ma ID ani SKU i zaznaczysz Update existing products. Takie dopasowanie zapowiadają oficjalne notatki przedpremierowe. Żeby ograniczyć ryzyko duplikatów, polecam przed importem sprawdzić puste i powtórzone kody, porównać je z katalogiem oraz wykonać próbę na kopii sklepu.

Najważniejsza pułapka: scalony kod zmiany importera rozróżnia nieznany identyfikator niepusty po normalizacji WooCommerce od kodu pustego po normalizacji. Pierwszy ma powodować pominięcie wiersza, z wyjątkiem nowych wariantów spełniających warunki importu, natomiast kod pusty po normalizacji, także zapisany jako n/a, jest traktowany jako brak identyfikatora i może prowadzić do utworzenia produktu. Samo zaznaczenie aktualizacji nie zastępuje kontroli pliku.

Stan źródeł sprawdziłem 6 października 2026. Zapowiedź opublikowana 21 września opisuje wersję beta i wskazuje tydzień wydania datą 6 października 2026; poniższą procedurę traktuj jako przygotowanie do zapowiedzianej wersji.

W skrócie

• Polecam wybrać jeden sposób identyfikacji dla konkretnej aktualizacji: ID, SKU albo kod produktu.
• Przed importem po EAN usuń z pliku aktualizacji niejasności: puste kody, powtórzenia i rozbieżności z katalogiem.
• Warianty sprawdzaj osobno. Próbę zakończ porównaniem identyfikatorów produktów, cen i liczby pozycji, a potem ponów ten sam import na kopii sklepu.

WooCommerce 11.2: import CSV wymaga jasnego klucza dopasowania

Zapowiedziana kolejność dopasowania to ID, następnie SKU, następnie Global Unique ID. Dopasowanie po ostatnim polu działa przy braku ID i SKU. Jeśli chcesz sprawdzić aktualizację produktów po EAN, polecam przygotować osobny plik bez tych dwóch wcześniejszych kluczy.

GTIN oznacza globalny identyfikator produktu. GS1 wyjaśnia, że GTIN-13 jest również nazywany EAN, a GTIN-12 jest nazywany UPC. Dla osoby zarządzającej katalogiem najważniejsze jest ustalenie, który kod z pliku dostawcy odpowiada konkretnemu produktowi w sklepie.

Poniższe sytuacje dotyczą aktualizacji po kodzie, bez ID i SKU. Zalecenia w ostatniej kolumnie służą przygotowaniu pliku.

Nie poprawiaj pominiętych pozycji przez przypadkowe wyłączanie trybu aktualizacji. Polecam najpierw ustalić przyczynę, a świadome dodawanie nowych produktów zaplanować jako oddzielne zadanie.

Audyt pliku: co sprawdzić przed otwarciem importera

Proponuję następującą kontrolę roboczą. To zalecana procedura przygotowania danych, a nie dodatkowe ustawienia WooCommerce.

1. Zachowaj oryginał pliku dostawcy. Pracuj na kopii, żeby móc porównać każdą poprawkę.
2. Ustal zakres aktualizacji. Jeśli zmieniasz tylko ceny, przygotuj plik zawierający identyfikator i kolumnę ceny. Ogranicz zakres pierwszej próby do kilku produktów.
3. Porównaj kody z aktualnym katalogiem. Dla każdej wybranej pozycji sprawdź, czy kod wskazuje oczekiwany produkt. Powtórzenia w katalogu skieruj do ręcznego wyjaśnienia.
4. Sprawdź zapis kodów. Polecam traktować identyfikatory jako tekst i zachować zera na początku. Nie zmieniaj automatycznie długości kodu ani zapisu ISBN bez porównania z danymi sklepu.
5. Oddziel wiersze wymagające wyjaśnienia. Puste kody, niepuste zapisy stające się puste po normalizacji WooCommerce, powtórzenia i niezgodny typ produktu przenieś do osobnej listy kontrolnej.

Plik zapisz jako CSV w UTF-8. Dokumentacja WooCommerce zaleca ten format i zwraca uwagę, że arkusze kalkulacyjne mogą zmieniać formatowanie lub kodowanie podczas zapisu.

Skrypt wykrywający puste i powtórzone kody

Przy większym pliku polecam prostą kontrolę lokalną. Poniższy skrypt korzysta z modułu csv i klasy DictReader opisanych w dokumentacji Pythona, aby odczytać wartości według nazw kolumn.

Przykład celowo zawiera powtórzony kod oraz pustą komórkę. Służy do sprawdzenia raportu, więc nie importuj go do sklepu. Utwórz plik aktualizacja.csv:

EAN,Regular price
0123456789012,39.90
0123456789012,42.00
,29.90

EAN jest tutaj własnym nagłówkiem pliku. W importerze trzeba przypisać tę kolumnę do pola GTIN, UPC, EAN, or ISBN; taką opcję oraz pole Regular price zawiera oficjalny kod mapowania WooCommerce.

Utwórz plik sprawdz_kody.py:

import csv
import re
import sys
from collections import defaultdict

if len(sys.argv) != 3:
    raise SystemExit("Użycie: python3 sprawdz_kody.py plik.csv EAN")

plik, kolumna = sys.argv[1:]
kody = defaultdict(list)
problemy = 0

with open(plik, encoding="utf-8-sig", newline="") as dane:
    czytnik = csv.DictReader(dane)
    if kolumna not in (czytnik.fieldnames or []):
        raise SystemExit(f"Brak kolumny: {kolumna}")
    for rekord, wiersz in enumerate(czytnik, start=2):
        surowy = wiersz.get(kolumna) or ""
        kod = surowy.strip()
        if not kod:
            print(f"Pusty kod: rekord {rekord}")
            problemy += 1
            continue
        if not re.sub(r"[^0-9Xx\-]", "", kod):
            print(f"Kod pusty po normalizacji WooCommerce: rekord {rekord}")
            problemy += 1
            continue
        kody[kod].append(rekord)
        if surowy != kod:
            print(f"Spacje przy kodzie: rekord {rekord}")
            problemy += 1

for kod, rekordy in kody.items():
    if len(rekordy) > 1:
        print(f"Powtórzony kod {kod}: rekordy {rekordy}")
        problemy += 1

print(f"Liczba problemów: {problemy}")
sys.exit(1 if problemy else 0)

Potrzebujesz Pythona 3. Zapisz oba pliki w jednym folderze roboczym i uruchom w tym folderze:

python3 sprawdz_kody.py aktualizacja.csv EAN

Dla podanego przykładu skrypt powinien wypisać:

Pusty kod: rekord 4
Powtórzony kod 0123456789012: rekordy [2, 3]
Liczba problemów: 2

Numeracja liczy nagłówek jako pierwszą pozycję. Skrypt porównuje tekst po usunięciu spacji z początku i końca oraz zgłasza takie spacje jako problem. Dodatkowo, za pomocą funkcji re.sub, zgłasza niepuste kody, które po normalizacji WooCommerce stają się puste. Kontrola obejmuje jeden plik; zgodność kodów z katalogiem i poprawność cyfr kontrolnych sprawdź osobno.

Dla własnego CSV zastąp nazwę pliku i argument EAN rzeczywistą nazwą kolumny. Warto wykonać tę samą kontrolę dla eksportu katalogu, podając nagłówek występujący w tym eksporcie.

Import próbny w WooCommerce krok po kroku

Polecam najpierw przygotować kopię zapasową oraz sklep testowy, czyli kopię sklepu przeznaczoną do prób. Taki sposób przygotowania większego importu zaleca również dokumentacja WooCommerce.

Dla przygotowanego pliku wykonaj następujące kroki zgodnie z procedurą aktualizacji produktów. Nazwy przycisków podaję w języku dokumentacji.

1. Przejdź do Products > All Products i wybierz Import.
2. Kliknij Choose File i wybierz CSV.
3. Zaznacz Update existing products.
4. Kliknij Continue i sprawdź ekran Column mapping.
5. Dopasuj kolumny. Dla kodu wybierz GTIN, UPC, EAN, or ISBN, zgodnie z opcją mapowania importera. Niepotrzebne kolumny oznacz jako Do not import.
6. Kliknij Run the importer. Poczekaj na zakończenie, bez odświeżania strony i przechodzenia do innego widoku.

Po próbie polecam porównać ID produktów, kody i zmienione ceny z zapisanym stanem początkowym. Następnie ponownie zaimportuj ten sam plik na kopii sklepu i sprawdź, czy otrzymujesz oczekiwany wynik bez dodatkowych pozycji.

Jeśli wiersze zostały pominięte lub import się nie powiódł, WooCommerce zaleca rozpocząć od dziennika importu. Zapisz przyczynę dla każdej problematycznej pozycji, zamiast poprawiać cały plik na podstawie jednego błędu.

Poniższy diagram przedstawia zalecany obieg kontroli:

flowchart TD
    A[CSV i dane katalogu] --> B[Kontrola kodów]
    B --> C{Są problemy?}
    C -->|Tak| D[Wyjaśnij i popraw]
    D --> B
    C -->|Nie| E[Import na kopii sklepu]
    E --> F[Porównaj wynik i ponów próbę]
    F --> G[Aktualizacja katalogu]

Warianty: aktualizacja może również dodawać pozycje

Od WooCommerce 11.1 import z zaznaczonym Update existing products może tworzyć nowe warianty istniejącego produktu. Dokumentacja migracji produktów opisuje wszystkie warunki: brak ID w wierszu, obecność SKU albo zmapowanego GTIN, UPC, EAN lub ISBN, dopasowanie Parent do istniejącego produktu z wariantami poza koszem oraz zgodność każdego atrybutu i jego wartości z ofertą produktu nadrzędnego.

Uwaga: Jeśli planujesz wyłącznie aktualizację istniejących wariantów, polecam osobno sprawdzić każdy wiersz bez dopasowania. W próbie porównaj także listę wariantów, a nie tylko cenę produktu nadrzędnego.

Przykładowo dla koszulki sprawdź oddzielnie warianty rozmiaru i koloru. W arkuszu kontrolnym zapisz oczekiwane warianty przed importem i porównaj je z wynikiem próby.

FAQ

Czy można aktualizować produkty po EAN bez SKU?

Takie zachowanie zapowiada WooCommerce 11.2: w trybie aktualizacji importer ma dopasowywać kod przy braku ID i SKU. Polecam zacząć od produktu, którego kod w sklepie i w CSV został ręcznie porównany.

Do jakiego pola przypisać ISBN w importerze WooCommerce?

W mapowaniu wybierz wspólne pole GTIN, UPC, EAN, or ISBN, widoczne w kodzie importera WooCommerce. Jeśli aktualizujesz książki, polecam sprawdzić zgodność ISBN dla konkretnego wydania przed próbą.

Czy importer usunie duplikaty, które już są w katalogu?

Nie traktuj importu jako procedury porządkowania istniejących duplikatów. Opis zmiany przewiduje deterministyczne dopasowanie przy powtórzonych identyfikatorach. Polecam najpierw wyjaśnić, który produkt powinien mieć dany kod, i dopiero później uruchomić aktualizację.

Co zrobić z pustym EAN w pliku aktualizacji?

Polecam wyłączyć taki wiersz z przygotowywanej aktualizacji i sprawdzić dane dostawcy. Scalony kod zmiany importera traktuje kod pusty po normalizacji WooCommerce, także niepusty zapis n/a, jako brak identyfikatora, co przy braku ID i SKU może prowadzić do utworzenia produktu. Nie zastępuj brakującego kodu przypadkową wartością.

Co dalej

Po kontroli identyfikatorów uporządkuj nazwy, opisy i warianty. Kolejny temat to przygotowanie produktów WooCommerce dla asystenta AI, który pomoże zaplanować dalszą pracę nad katalogiem.