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
- Aktualizacja a ręczne poprawki — które pola nadpisze
updatei jak uzupełniać dane, nie kasując wypełnionych. - Przerwanie i powtórzenie pakietu — powtórzenie nie dubluje produktów; które wiersze pakiet pomija bez komunikatu.
- Czyja cena zostanie — , narzuty czy aktualizacja katalogu z cenników.
- Kiedy produkt trafi na stronę — API samo niczego nie eksportuje.
- Usunięte i wycofanie błędnego pakietu — jak znaleźć i usunąć zbędne.
- Dokumenty — status, zatwierdzenie i ochrona przed duplikatem zamówienia.
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 maimage_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ść:
| Sytuacja | Co 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łnionych | zamiast 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,shippingi wszystkie polaflag_*; - 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_specialten 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
uuidjest pusty — po zgodności trzech pól łącznie:mpn, nazwy iext_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 wcategory_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ściecategory_list. Nie udało się żadnym sposobem — produkt nie jest zapisywany. Parametrcategory_create_by_source=1umieszcza takie produkty w osobnej kategorii technicznej z kodem źródła w nazwie; jest ona tworzona jako wyłączona i bez eksportu.
- Початок або кінець
- Дія або результат
- Розвилка: далі шлях залежить від відповіді
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 zapisuje | Co robi z ceną | Co go blokuje |
|---|---|---|
api/scope/update | zapisuje cenę bez zmian, nie uruchamia potem narzutów | nic: „Stała cena” i „Nie aktualizuj” nie działają |
api/scope/add | zapisuje 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 narzuty | nadpisują 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(zitem_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 zapytaniuflag_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/getz filtremfilterdatafield0=source_code,filtercondition0=EQUAL,filtervalue0=my_erpzwróci listę identyfikatorów. Aby wybrać właśnie ten przebieg, dodaj drugi warunek podate_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. Zis_sign=1dokument jest zatwierdzany od razu w tym samym zapytaniu — tak samo jak przyciskiem zatwierdzenia w programie, z ruchem stanów, a w odpowiedzi pojawia się poleis_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 takimproduct_idnie ma w bazie, pozycja nie jest zapisywana, a w odpowiedzi otrzymuje statusErrori tekst „Nie znaleziono produktu”; reszta dokumentu jest tworzona. - nie ma
product_id, ale jestname— Elbuz sam szuka produktu: najpierw po kodzie kreskowymean, potem po kodziesku, 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, aniname— pozycja nie jest zapisywana, statusError, „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_idistnieją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_namenie ma, sprawdzenie nie jest wykonywane i dokument jest tworzony; nieistniejąca nazwa wcheck_unique_field_name_2usuwa 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 widzisz | Dlaczego tak jest | Co zrobić |
|---|---|---|
total_item_add jest mniejszy niż liczba wysłanych wierszy | wiersze bez nazwy i nowe produkty bez kategorii pakiet pomija bez błędu | daj każdemu wierszowi nazwę i kategorię (które wiersze są pomijane) |
| Cena z API po dniu się zmieniła | nadpisała ją aktualizacja katalogu z cenników lub narzuty | przekaż razem z ceną flag_fix_price=1 (czyja cena zostanie) |
| Ręczna cena handlowca została skasowana | api/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_code | aktualizacja pakietowa nadpisała „Źródło: kod” wartością api | szukaj po date_added lub uuid |
| Po powtórzeniu pakietu produkty nie mają zdjęć | zdjęcia zapisują się tylko nowo utworzonym produktom | dosł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
- Jeśli potrzebujesz ogólnego obrazu i przejścia na API v2 — stare API v1: klucz i przejście.
- Jeśli trzeba znaleźć parametr zapytania lub zrozumieć błąd — dokumentacja starego API v1.
- Jeśli cenę z API nadpisują narzuty — narzuty katalogu bazowego.
- Jeśli piszesz nową integrację i nie chcesz duplikatów przy powtórzeniu — Idempotency-Key w API v2.
