↑↓ wybierzEnter otwórzEsc zamknij

    1. Elbuz
    2. Stare API Elbuz (v1): klucz i przejście na API v2

    Co stare API v1 robi z produktami, cenami i dokumentami

    12 min czytaniaZaktualizowano

    API v1 zapisuje dane od razu, bez zatwierdzania, i według własnych zasad: które pola nadpisze mimo ręcznych poprawek, co zostanie po przerwaniu pakietu, czyja cena wygra. Znając je przed uruchomieniem, nie stracisz ręcznych poprawek i usuniesz nieudany przebieg.

    Kiedy to się przyda:

    • Handlowiec ustawia własne ceny, a system księgowy przysyła swoje — „Stała cena” chroni tylko przy dodawaniu z aktualizacją istniejących.
    • Pakiet na 10 000 produktów został przerwany — powtórzenie nie zdubluje produktów, ale nie doda zdjęć.
    • Pakiet utworzył zbędne produkty — znajdzie je filtr po „Źródło: kod”.
    • Strona powtarza zamówienie po awarii sieci — drugi dokument nie powstanie.

    Od czego zacząć: co nadpisze ręczne poprawki.

    Co warto wiedzieć przed uruchomieniem

    Co nadpisze ręczne poprawki

    api/scope/update dla produktów nadpisuje dokładnie te pola, które są w zapytaniu, a pozostałych nie rusza. Produkt jest wyszukiwany tylko po product_id: wiersz z identyfikatorem, którego nie ma w bazie, jest pomijany bez błędu i nie wchodzi do total_item_update.

    Flagi karty „Nie aktualizuj” i „Stała cena” nie blokują aktualizacji przez API. Jeśli handlowiec poprawił ręcznie nazwę lub cenę i zaznaczył flagę, następny update z tym polem i tak nadpisze wartość. Flagi chronią przed aktualizacją katalogu z cenników i przed narzutami, ale nie przed bezpośrednim zapisem przez API.

    Osobno o listach zagnieżdżonych w aktualizacji pakietowej:

    • jeśli rekord zawiera image_list, wszystkie zdjęcia produktu są usuwane i zastępowane przesłanymi; flaga „Nie aktualizuj zdjęć” tego nie blokuje. Nie ma image_list — zdjęcia zostają bez zmian;
    • jeśli jest attribute_list, cechy produktu są kasowane i zapisywane z pakietu. Tu flagi działają: produkt z „Nie aktualizuj” lub „Nie aktualizuj atrybutów” zachowuje stare cechy.

    Pola oznaczone w rejestrze pól jako „tylko do odczytu” pakiet pomija bez błędu. Pole, którego w rejestrze w ogóle nie ma, odrzuca cały pakiet z komunikatem „Nieznane pole” i jego nazwą. Sprawdzane są nazwy pól pierwszego rekordu pakietu.

    Jak zabezpieczyć własną wartość:

    SytuacjaCo zrobić
    Pole prowadzi człowiek w Elbuz, integracja nie może go ruszaćnie przekazuj tego pola w update. W pojedynczej aktualizacji (bez item_list) wartość -1 też oznacza „nie ruszaj pola”
    Trzeba uzupełniać dane, nie kasując wypełnionychzamiast update wysyłaj api/scope/add z parametrem update_exist_product=1 — jego zasady poniżej

    Dodawanie z update_exist_product=1 znajduje istniejące produkty tak samo jak ochrona przed duplikatami (poniżej) i aktualizuje je według innych zasad niż update:

    • pusta wartość lub zero w pakiecie nie kasuje wypełnionego pola. Wyjątek — pola, w których zero oznacza działanie: quantity, status, sort_order, subtract_quantity, shipping i wszystkie pola flag_*;
    • ceny (price, price_rrp, price_old, price_cost, price_special) nie zmieniają się w produktach ze „Stała cena”;
    • produkty z „Nie aktualizuj” są pomijane w całości.

    Bez update_exist_product dodawanie nie aktualizuje pól istniejących produktów: znajduje je i pomija. Dopisuje im tylko przypisania do kategorii z listy category_list.

    Zamiast flagi można przekazać field_list_update_exist_product — listę pól do aktualizacji:

    • zapisywane są tylko te pola, z pominięciem produktów z „Nie aktualizuj” i cen produktów ze „Stała cena”;
    • price_special ten tryb nie chroni;
    • nazwy, których nie ma wśród pól produktu, są pomijane bez błędu — reszta listy jest aktualizowana.

    Co będzie po przerwaniu pakietu i powtórzeniu

    Pakiet na 10 000 produktów serwer przetwarza jako ciąg osobnych zapisów do bazy, bez transakcji: najpierw kategorie i producenci, potem same produkty, potem kategorie produktów, cechy, zdjęcia, rabaty. Jeśli przetwarzanie przerwie się w połowie, w bazie zostaje to, co zdążyło się zapisać.

    Powtórzenie tego samego pakietu nie dubluje produktów. Przed zapisem każdy wiersz jest wyszukiwany wśród istniejących produktów:

    • jeśli wiersz ma uuid — po nim;
    • jeśli uuid jest pusty — po zgodności trzech pól łącznie: mpn, nazwy i ext_url (bez uwzględniania wielkości liter i spacji na brzegach).

    Znaleziony produkt nie jest tworzony ponownie. Ale zdjęcia i cechy przy dodawaniu zapisują się tylko nowo utworzonym produktom. Jeśli przerwanie nastąpiło po utworzeniu produktów, a przed zapisem zdjęć, powtórzenie nie doda zdjęć — produkt uważa się już za istniejący. Brakujące cechy powtórzenie dopisze, jeśli przekażesz update_existing_attr[product_values]=1: brakujące wartości są dodawane, istniejące pozostają nietknięte. Zdjęcia trzeba będzie dosłać przez api/scope/update z image_list.

    Przekazuj w każdym produkcie własny stały uuid. Wtedy powtórzenie jednoznacznie znajdzie produkt, nawet jeśli między próbami zmieniłeś nazwę.

    Bez błędu pakiet pomija dwa rodzaje wierszy i widać to tylko po tym, że total_item_add jest mniejszy niż liczba wysłanych:

    • wiersz bez nazwy — odrzucany przed zapisem;
    • nowy produkt bez kategorii — nie jest tworzony. Kategorię pakiet ustala po category_id, po pełnej ścieżce w category_name_full (części rozdzielone /; jeśli żadnej części ścieżki nie ma w bazie, tworzony jest łańcuch kategorii, w przeciwnym razie produkt trafia do najgłębszej znalezionej po nazwie) albo po liście category_list. Nie udało się żadnym sposobem — produkt nie jest zapisywany. Parametr category_create_by_source=1 umieszcza takie produkty w osobnej kategorii technicznej z kodem źródła w nazwie; jest ona tworzona jako wyłączona i bez eksportu.
    Los jednego wiersza pakietu. Lewa gałąź — produkt, który już istnieje: bez update_exist_product jego pola się nie zmieniają. Prawa — nowy produkt: bez nazwy lub bez kategorii nie jest tworzony i nie trafia do total_item_add
    NieTakTakTakNieNieTakNieTakNieTakNieWiersz pakietu api/scope/addWiersz ma nazwę?Wiersz jest pomijany bez błędu,nie wchodzi do total_item_addProdukt już istnieje?Po uuid, a bez uuid — po mpn,nazwie i ext_url łączniePrzekazanoupdate_exist_product=1lub field_list_update_exist_product?Pola są aktualizowane.Pola produktów z „Nie aktualizuj” sięnie zmieniająPola produktu się nie zmieniają.Dopisywane są tylko kategorie zcategory_listKategorię znaleziono po category_idlub category_name_full?Produkt jest tworzonyrazem ze zdjęciami i cechamiW category_list jest kategoriagłównaznaleziona w bazie?category_create_by_source=1?Produkt trafia do kategoriitechnicznej źródła
    • Початок або кінець
    • Дія або результат
    • Розвилка: далі шлях залежить від відповіді

    Czyja cena zostanie

    Cenę produktu w Elbuz zapisują trzy mechanizmy: API, narzuty katalogu bazowego i aktualizacja katalogu z cenników. Zostaje wartość tego, kto zapisał ostatni — według takich zasad:

    Kto zapisujeCo robi z cenąCo go blokuje
    api/scope/updatezapisuje cenę bez zmian, nie uruchamia potem narzutównic: „Stała cena” i „Nie aktualizuj” nie działają
    api/scope/addzapisuje Twoją cenę, a potem w tym samym zapytaniu przelicza narzuty katalogu bazowego dla nowo utworzonych produktów: jeśli są aktywne reguły narzutu i przekazałeś price_cost większy od zera, cena jest przeliczana od ceny zakupu„Stała cena” lub „Nie aktualizuj” w samym pakiecie
    aktualizacja katalogu z cenników i narzutynadpisują cenę produktów dopasowanych do cennika„Stała cena” (i „Nie aktualizuj” — dla narzutów)

    Czyli cena przekazana przez API przetrwa tylko do następnej aktualizacji katalogu lub przeliczenia narzutów, jeśli produkt nie ma „Stała cena”. Aby cena z API pozostała nadrzędna, przekaż razem z nią flag_fix_price=1. Flaga zdejmuje się sama po dacie w polu „Data zdjęcia flagi „Stała cena””, jeśli ją ustawiono — jest to sprawdzane przy każdej aktualizacji katalogu.

    Kiedy dodane dane trafią na stronę i do eksportu

    Same operacje API niczego nie eksportują: ani add, ani update nie uruchamiają tunelu ani eksportu pliku. Produkt trafi dalej przy najbliższym przebiegu skonfigurowanego u Ciebie eksportu — ręcznym lub według harmonogramu.

    W ramach samego zapytania dodawania wykonano już wszystko, czego potrzebuje katalog: narzuty, dane techniczne do sortowania i zbiorczą (płaską) tabelę produktów. Jeśli na koncie jest kilka aktywnych sklepów, nowe produkty trafiają do sklepu z parametru store_id, a bez niego — do sklepu o numerze 1.

    Subtelne miejsce — tryb tunelu „Eksportować tylko nowe dane”. W nim tunel bierze tylko produkty z odznaczoną flagą „Flaga: wyeksportowano”.

    • Jeśli produkt utworzono przez add, flaga jest odznaczona i produkt pójdzie w najbliższym przebiegu.
    • Jeśli produkty zmieniono pakietowym update (z item_list), flaga też się odznacza i zmiana pójdzie w najbliższym przebiegu.
    • Jeśli zmieniono jeden produkt bez item_list, flaga się odznacza, gdy zapytanie zawiera choć jedno pole samego produktu (cena, stan itp.). Zapytanie tylko z polami tekstowymi — nazwą, opisami, meta tagami — flagi nie odznacza i w tym trybie taka zmiana nie trafi na stronę. Aby trafiła, przekaż w tym samym zapytaniu flag_exported=0.

    Usunięcie przez api/scope/delete usuwa produkt także ze strony, jeśli w ustawieniach tunelu dozwolone jest usuwanie produktów na stronie: od razu, gdy włączono też „Usuwać dane od razu na stronie”, w przeciwnym razie — przy najbliższym przebiegu tunelu. Bez zgody na usuwanie produktów na stronie produkt tam zostaje.

    Jak dowiedzieć się o usuniętych

    Synchronizacja przyrostowa po date_modified nie dowie się o usunięciu. Usunięty produkt jest kasowany z bazy całkowicie — razem z opisami, zdjęciami, cechami i przypisaniami do kategorii, a wśród słowników get nie ma dziennika usunięć. Razem z produktem głównym usuwane są też jego produkty-opcje.

    Aby wychwycić usunięte, okresowo pobieraj pełną listę identyfikatorów (limit_field=product_id, max_rows=500, przechodzenie po page_next) i porównuj ją ze swoją: czego nie ma w Elbuz, to już nie istnieje.

    W drugą stronę działa ta sama zasada: Elbuz niczego nie usuwa za Ciebie. Produktu, którego zabrakło w Twoim systemie, add i update nie dotykają — zostaje w Elbuz z ostatnio zapisanymi danymi. Usunąć go można tylko jawnym api/scope/delete z jego product_id.

    Jak wycofać błędny pakiet

    Jeśli pakiet add utworzył zbędne lub uszkodzone produkty, znajdź je po oznaczeniu źródła. Produkty utworzone pakietem mają w polu „Źródło: kod” Twój source_code (lub jumper, jeśli go nie przekazałeś).

    • Przez API: api/scope/get z filtrem filterdatafield0=source_code, filtercondition0=EQUAL, filtervalue0=my_erp zwróci listę identyfikatorów. Aby wybrać właśnie ten przebieg, dodaj drugi warunek po date_added.
    • W programie: w tabeli produktów katalogu bazowego przefiltruj kolumnę „Źródło: kod”, zaznacz znalezione i usuń — program zapyta „Usunąć wybrane produkty?” z ich liczbą.

    api/scope/delete usuwa jeden produkt na zapytanie, więc wycofanie tysiąca produktów przez API to tysiąc zapytań w granicach limitu częstotliwości. Tabela produktów usuwa wszystkie zaznaczone jednym działaniem.

    Aktualizacja pakietowa nadpisuje „Źródło: kod” wartością api. Produktów, które po błędnym dodaniu dodatkowo zaktualizowano pakietem, nie znajdziesz już po swoim source_code — szukaj ich po date_added lub po swoim uuid.

    Z błędnym update jest trudniej: zapytanie aktualizacji nigdzie nie zapisuje poprzednich wartości i nie da się go wycofać środkami API. Przywrócić dane trzeba będzie ponownym update z poprawnymi danymi z Twojego systemu.

    Dokumenty: status, stan i duplikaty

    Dokument utworzony przez api/scope/add ze scope=document:

    • wymaga type_id — bez niego odpowiedź brzmi „Nie podano typu dokumentu”, z nieistniejącym — „Nie znaleziono typu dokumentu”;
    • otrzymuje status „Nowy”, jeśli nie przekazano status_id;
    • otrzymuje numer automatycznie, według numeracji swojego typu;
    • nie jest zatwierdzany, jeśli nie przekażesz is_sign=1. Bez tego parametru taki dokument nie zmienia stanu ani rezerwacji: rezerwacja liczy się tylko dla zatwierdzonych zamówień, a stan zmienia zatwierdzenie. Z is_sign=1 dokument jest zatwierdzany od razu w tym samym zapytaniu — tak samo jak przyciskiem zatwierdzenia w programie, z ruchem stanów, a w odpowiedzi pojawia się pole is_sign.

    Pozycje dokumentu przekazuje się w item_list. Produkt każdej pozycji Elbuz ustala tak:

    • jest product_id — pozycja jest wiązana z tym produktem. Jeśli produktu o takim product_id nie ma w bazie, pozycja nie jest zapisywana, a w odpowiedzi otrzymuje status Error i tekst „Nie znaleziono produktu”; reszta dokumentu jest tworzona.
    • nie ma product_id, ale jest name — Elbuz sam szuka produktu: najpierw po kodzie kreskowym ean, potem po kodzie sku, potem po dokładnej nazwie. Nazwa jest porównywana bez uwzględniania wielkości liter, zbędnych spacji i cudzysłowów i jest uznawana tylko wtedy, gdy produkt o takiej nazwie jest w bazie jeden.
    • produktu nie znaleziono żadnym sposobem — Elbuz tworzy nowy z nazwą, kodem SKU, kodem kreskowym i ceną pozycji w kategorii technicznej „Produkty - api - api”. Kategoria jest tworzona jako wyłączona i bez eksportu.
    • nie ma ani product_id, ani name — pozycja nie jest zapisywana, status Error, „Nie znaleziono produktu”.

    Zamówienie klienta (type_id=3) z jedną pozycją po product_id i jedną — tylko z nazwą, kodem SKU i kodem kreskowym (funkcja elbuz_call — z pierwszego zapytania w dokumentacji):

    $res = elbuz_call($host, 'api/scope/add', array(
        'api_token' => $token,
        'scope'     => 'document',
        'type_id'   => 3,
        'item_list' => array(
            array('product_id' => 2, 'quantity' => 1, 'price' => 449),
            array('name' => 'Kabel HDMI 2.1, 2 m', 'sku' => 'HDMI-21-2M', 'ean' => '5900000000015', 'quantity' => 3, 'price' => 39),
        ),
    ));

    Aby produkty się nie mnożyły, przekazuj w pozycji product_id, a jeśli go nie masz — przynajmniej ean lub sku, takie same jak w karcie produktu w Elbuz. Wyszukiwanie po nazwie działa tylko przy dokładnej i jedynej zgodności: inna nazwa w zamówieniu albo dwa produkty o tej samej nazwie — i pojawia się nowa karta.

    Nowe karty trafiają do kategorii „Produkty - api - api”: zaglądaj tam, aby zauważyć pozycje, których Elbuz nie rozpoznał.

    Przed duplikatami przy powtórzeniu chroni parametr check_unique_field_name — nazwa pola dokumentu, unikalnego dla Twojego systemu (np. pola z numerem Twojego zamówienia).

    • Jeśli dokument z taką wartością już istnieje, nowy nie jest tworzony, a odpowiedź zwraca „Dokument już istnieje” z document_id istniejącego.
    • Do sprawdzania po parze pól służy jeszcze check_unique_field_name_2.
    • Nazwa musi być dokładną nazwą pola dokumentu. Jeśli pola o nazwie z check_unique_field_name nie ma, sprawdzenie nie jest wykonywane i dokument jest tworzony; nieistniejąca nazwa w check_unique_field_name_2 usuwa tylko drugi warunek.
    • Jeśli w samym zapytaniu nie przekazano wartości pola, uważa się ją za pustą.

    Scenariusze

    System księgowy przysyła ceny, a część produktów handlowiec prowadzi ręcznie

    Zadanie: ceny i stany przychodzą z systemu księgowego, ale przy wybranych produktach handlowiec ustawia własną cenę i wymiana danych nie może jej skasować.

    Co włączyć: przy produktach handlowca — „Stała cena”, a tam, gdzie nie wolno niczego ruszać, — „Nie aktualizuj”. Integracja wysyła api/scope/add z item_list, update_exist_product=1 i tym samym uuid, z którym utworzyła produkt.

    Efekt: istniejące produkty są znajdowane po uuid i aktualizowane. Ceny produktów ze „Stała cena” pozostają ustawione przez handlowca, w produktach z „Nie aktualizuj” pola i cechy się nie zmieniają, a puste pole w pakiecie nie kasuje wypełnionego (poza ilością, statusem i innymi polami, w których zero oznacza działanie, — lista wyżej).

    Czego nie będzie: ochrony nie będzie, jeśli tę samą zmianę wyślesz przez api/scope/update — tam „Stała cena” i „Nie aktualizuj” nie chronią pól produktu i cena zostanie nadpisana.

    Zamówienia ze strony bez duplikatów przy powtórzeniu

    Zadanie: strona przekazuje zamówienia do Elbuz i przy awarii sieci powtarza zapytanie — drugie takie samo zamówienie nie może się pojawić.

    Co włączyć: api/scope/add ze scope=document i type_id; numer zamówienia ze strony — w polu dokumentu, a nazwa tego pola — w check_unique_field_name.

    Efekt: dokument otrzymuje status „Nowy” i numer według numeracji swojego typu. Powtórzenie z tym samym numerem odpowiada „Dokument już istnieje” z document_id pierwszego, drugi dokument nie jest tworzony.

    Czego nie będzie: stan i rezerwacja się nie zmienią, jeśli nie przekażesz is_sign=1 — bez tego dokument pozostaje niezatwierdzony i zatwierdza się go w programie.

    Pierwszy import katalogu, który można usunąć

    Zadanie: wgrać katalog z systemu księgowego tak, aby po przerwaniu dało się powtórzyć, a nieudany przebieg — znaleźć i usunąć.

    Co włączyć: api/scope/add z item_list, source_code=my_erp, każdy produkt z własnym uuid i ścieżką w category_name_full.

    Efekt: utworzone produkty mają w polu „Źródło: kod” wartość my_erp. Produkt trafia do najgłębszej kategorii ścieżki znalezionej po nazwie, a jeśli żadnej części ścieżki nie ma w bazie — tworzony jest łańcuch kategorii. Powtórzenie pakietu po przerwaniu znajduje już utworzone po uuid i nie dubluje. Nieudany przebieg znajdziesz filtrem po „Źródło: kod” — jak to zrobić.

    Czego nie będzie: powtórzenie nie doda zdjęć produktom, które zdążyły powstać przed przerwaniem, a po api/scope/update oznaczenie źródła zmieni się na api.

    Co zrobić, gdy wynik jest nie taki

    Co widziszDlaczego tak jestCo zrobić
    total_item_add jest mniejszy niż liczba wysłanych wierszywiersze bez nazwy i nowe produkty bez kategorii pakiet pomija bez błędudaj każdemu wierszowi nazwę i kategorię (które wiersze są pomijane)
    Cena z API po dniu się zmieniłanadpisała ją aktualizacja katalogu z cenników lub narzutyprzekaż razem z ceną flag_fix_price=1 (czyja cena zostanie)
    Ręczna cena handlowca została skasowanaapi/scope/update nie uwzględnia „Stała cena”wysyłaj add z update_exist_product=1 albo nie przekazuj ceny (szczegóły)
    Produktów integracji nie da się znaleźć po ich source_codeaktualizacja pakietowa nadpisała „Źródło: kod” wartością apiszukaj po date_added lub uuid
    Po powtórzeniu pakietu produkty nie mają zdjęćzdjęcia zapisują się tylko nowo utworzonym produktomdosłij zdjęcia przez api/scope/update z image_list

    Najczęstsze pytania

    Czy można cofnąć błędny update?

    Nie: zapytanie nie zapisuje poprzednich wartości. Przywróć dane ponownym update z poprawnymi wartościami z Twojego systemu (wycofanie).

    Produkt zniknął w moim systemie — dlaczego został w Elbuz?

    Elbuz niczego nie usuwa za Ciebie: add i update takiego produktu nie dotykają. Usuń go jawnym api/scope/delete z jego product_id (szczegóły).

    Dlaczego zamówienie ze strony nie zmniejszyło stanu?

    Dokument przez API jest zatwierdzany tylko z is_sign=1. Bez tego pozostaje niezatwierdzony, a stan i rezerwacja się nie zmieniają (dokumenty).

    Czy można wyszukiwać istniejące produkty bez własnego uuid?

    Tak: bez uuid produkt jest wyszukiwany po zgodności mpn, nazwy i ext_url łącznie. Ale po zmianie nazwy zgodność zniknie i powtórzenie utworzy nowy produkt (powtórzenie pakietu).

    Produkt dodano przez API — dlaczego nie ma go na stronie?

    API samo niczego nie eksportuje: produkt pójdzie przy najbliższym przebiegu tunelu lub eksportu. W trybie „Eksportować tylko nowe dane” zmiana samych pól tekstowych bez flag_exported=0 nie pójdzie (szczegóły).

    Gdzie to jest i kto ma dostęp

    Osobnego okna nie ma: zasady działają przy każdym zapisie przez API v1, a skutki widać w programie.

    Klucz
    klucz v1 bez „Tylko do odczytu” (pola klucza)
    Gdzie widać wynik
    tabela produktów katalogu bazowego, kolumna „Źródło: kod”
    Dziennik
    dziennik pracy, operacje typu „api”

    Powiązane tematy

    Czy ten artykuł był pomocny?

    Brakuje funkcji? Napisz do nas.

    Dodamy ją za darmo, jeśli przyda się też innym.

    Jeśli potrzebujesz jej tylko ty — umówimy się osobno.

    Spis treści

    Zaproponuj usprawnienie

    Wypróbuj Elbuz za darmo