Magento - informacje podstawowe

Wbudowana integracja Magento, pozwala na podpięcie wielu sklepów jednocześnie do systemu YetiForce, będącego sercem organizacji.

Główne założenia integracji

W systemie YetiForce można użyć wbudowanej integracji z Magento. Integracja działa na zasadzie synchronizacji danych w cron-ie przy użyciu API (Magento Admin REST endpoints), która synchronizuje dane pomiędzy YetiForce a Magento. Elastyczna konstrukcja, pozwala na wielosklepowość tzn. możesz zintegrować z systemem YetiForce wiele sklepów opartych na silniku Magento. Niezależnie od ilości sklepów, system YetiForce zawsze jest systemem nadrzędnym, który centralizuje dane z różnych systemów podrzędnych [np. Magento].

Komunikacja pomiędzy systemami jest jednostronna [system YetiForce odpytuje API Magento, pobierając i aktualizują dane w dwóch kierunkach]. Teoretycznie nie ma konieczności instalowania żadnych rozszerzeń do Magento, jednakże w praktyce zalecamy dostosowania mapowania oraz ujednolicenia typów pól i słowników pomiędzy systemami [więcej informacji w dalszej części dokumentu].

Integracja w dużym stopniu zabezpiecza się przed zmianami w Magento [co zostało opisane w sekcjach poniżej], należy jednak pamiętać, że integrowane są duże systemy, często przetwarzające tysiące informacji dziennie. Każda zmiana wartości w słownikach, usunięcie produktu, usunięcie klienta może wpływać na oba systemy, a więc pracownicy mający uprawnienia administracyjne powinni być przeszkoleni.

Synchronizacja

System synchronizuje wiele elementów, do najważniejszych z nich można zaliczyć: waluty, kategorie, produkty, klienci, zamówienia. Jeżeli podczas synchronizacji pojawi się na zamówieniu produkt, kategoria lub klient którego nie ma w YetiForce, wówczas mechanizm automatycznie doczyta brakujące dane.

Synchronizacja wymaga użytkownika z uprawnieniami administratora do wszystkich części które podlegają synchronizacji.

Magento > YetiForce

Waluty

Domyślnie oba systemy posiadają tą samą listę obsługiwanych walut, dodanie waluty w Magento wymaga weyfikacji, czy nowa waluta jest również poprawnie obsługiwana w drugim systemie. Jeżeli w sklepie Magento jest włączona waluta, która nie jest włączona w YetiForce, wówczas integracja dodaje nową walutę do listy obsługiwanych walut [może to zrobić tylkow wówczas, gdy nowa waluta jest na liście walut wspieranych przez system, co można sprawdzić w panelu konfiguracyjnym systemu].

Jeżeli po stronie Magento zostanie usunięta waluta, wówczas w systemie YetiForce nic się nie zmieni.

Kategorie

Wszystkie kategorie synchronizowane są tylko w jednym kierunku [z Magento do YetiForce], w ten sposób zarządzanie kategoriami może odbywać się po stronie sklepu. W przypadku pojawienia się nowej kategorii, mechanizm synchronizacji dodaję tą kategorię do systemu YetiForce [aktualnie są synchronizowane tylko konieczne pola, zgodnie z mapowaniem pól opisanym w sekcjach poniżej]. 

Dla bezpieczeństwa integracji, zmiana kategorii w jednym systemie nie wpływa na zmianę kategorii w drugim systemie [np. gdy zmienimy nazwę kategori] w ten sposób systemy nie będą na siebie wpływać np. zmiana nazwy kategorii mogłaby wpływać na filtry, wykresy w systemie YetiForce oraz kategorie w innych sklepach, co nie powinno mieć miejsca, w szczególności gdy sklepy są zarządzne przez różne zespoły osób. Podczas synchronizacji, system ignoruje status kategorii a usunięcie kategorii w Magento nie powoduje usunięcia jej w YetiForce. 

Synchronizacja kategorii odbywa się na podstawie unikalnego ID kategorii w systemie Magento, a w systemie YetiForce oprócz ID kategorii jest również uwzględniany ID sklepu [połączenie tych dwóch ID jest wartością unikalną w systemie YetiForce]. System Magento nie może dopuszczać do dwóch kategorii o tym samym identyfikatorze.

Produkty

Synchronizacja produktów działa od strony technicznej bardzo podobnie jak synchronizacja kategorii. Polem unikalnym po którym są synchronizowane produkty pomiędzy systemami to SKU. Istotną różnicą w porównaniu do synchronizacji kategorii, jest to, że kategorie w YetiForce są unikalne na podstawie ID kategorii + ID sklepu, a w przypadku produktów, wartością unkalną jest tylko pole SKU a więc dwa sklepy sprzedające produkt o tym samym SKU będą w YetiForce miały ten sam produkt [ale mogą mieć różne kategorie].

Kontakty

Synchronizacja kontaktów działa od strony technicznej bardzo podobnie jak synchronizacja kategorii. Polem unikalnym po którym są synchronizowane kontakty pomiędzy systemami to pole email. Synchronizacja kontaktu odbywa się przy synchronizacji klientów  oraz przy tworzeniu zamówienia/faktury [system sprawdza dane kontaktu i jeżeli nie istnieje on w systemie YetiForce, to go tworzy, a jeżeli istnieje to go powiązuje z zamówieniem].

Kontrahenci
Synchronizacja kontrahentów działa od strony technicznej bardzo podobnie jak synchronizacja kategorii. Polem unikalnym po którym są synchronizowani kontrahenci pomiędzy systemami to pole NIP lub adres email. Synchronizacja kontrahenta odbywa się przy synchronizacji klientów  oraz przy tworzeniu zamówienia/faktury [system sprawdza dane kontrahenta na kontakcie i jeżeli nie istnieje on w systemie YetiForce, to go tworzy, a jeżeli istnieje to go powiązuje z zamówieniem].

Niestety sam system Magento, ma bardzo skomplikowaną mechanikę tworzenia kontrahenta [dane o kontrahencie mogą być uzupełniane w różnych miejscach i w różnych momentach tworzenia zamówienia], dlatego została wdrożona następująca logika jeżeli chodzi o wyszukiwanie i powiązywanie kontrahentów pomiędzy systemami:

  1. [Magento] Sprawdzamy czy wprowadzono NIP w bloku “Domyślny adres rozliczeniowy”;
  2. [Magento] Sprawdzamy czy wprowadzono NIP w bloku “Domyślny adres dostawy”;
  3. Jeżeli nie znajdziemy NIP-u to szukamy adresu email we wszystkich polach typu "E-mail" moduł Kontrahenta;

Jeżeli nie znajdziemy kontrahenta, jest on tworzony, jeżeli znajdziemy w YetiForce kontrahenta, jest on powiązywany z zamówieniem.

Zamówienia

Synchronizacja zamówienia jest realizowana podobnie do synchronizacja produktów, z następującymi różnicami:

  1. Synchronizacja następuje w momencie, kiedy YetiForce pobierze z API informacje o nowym zamówieniu w sklepie.
  2. System określa unikalność zamówienia po stronie Magento na podstawie pola "Numer zamówienia" a po stronie YetiForce na podstawie połączenia pól "ID zamówienia Magento" + "ID Sklepu Magento". Oba pola sa polami systemowymi i nie można ich edytować.  
  3. Jeżeli nie istnieje kontakt/kontrahent/produkt/kategoria to są tworzone na podstawie danych z Magento.
  4. Jeżeli zamówienie będzie zawierało usługi dodatkowe [wymienione poniżej], wówczas do zamówienia w YetiForce zostaną również dodane dodatkowe usługi a cena zostanie pobrana z zamówienia Magento:
    • Usługa przewozowa
    • Usługa płatności Paypal
    • Płatność gotówkowa przy odbiorze
  5. Utworzenie/edycja zamówienia z statusem "Zakończone" spowoduje automatyczne tworzenie dokumentu WZ (domyślnie mechanizm jest wyłączony należy go włączyć w panelu administratora moduł "Wyzwalacze"). Po utworzeniu WZ należy pamiętać, że oba dokumenty [Zamówienie i WZ] są niezależne, zmiana jednego z nich nie wpływa na drugi jedyny wyjątek jest gdy status zamówienia otrzyma inną wartość  niż  "Zakończone" to wszystkie WZ dla tego zamówienia zstają anulowane.
Uwagi:
  • Jeżeli zamówienie nie będzie miało wymaganych informacji np. waluty obsługiwanej przez YetiForce, wówczas zamówienie to zostanie pominięte.
  • Jeżeli zamówienie będzie zawierało produkt, które nie istnieje w YetiForce i nie istnieje w Magento [produkt został usunięty po utworzeniu zamówienia], wówczas zamówienie to zostanie pominięte.

Faktury sprzedażowe

Synchronizacja faktur sprzedażowych jest realizowana tak samo jak synchronizacja zamówień, tylko nie są generowane dokumenty WZ.

YetiForce > Magento

Stany magazynowe (bazujące na dokumentach WZ)

Jedną z najważniejszych elementów integracji, jest synchronizacja stanów magazynowych z YetiForce do Magento. Każdy sklep może mieć własny "magazyn" po stronie YetiForce i informacja o stanie magazynowym może pochodzić albo z magazynu przypisanego do sklepu, albo bezpośrednio z produktu [czyli stanu magazynowego ze wszystkich magazynów łącznie]. Wymagane jest włączenie generowania dokumentu WZ przy tworzeniu/edycji zamówienia.

Samo Magento również wpływa na stany magazynowe systemu YetiForce, tylko poprzez zamówienia [zmiana stanu magazynowe w Magento nie wpływa w żaden sposób na stan magazynowy w YetiForce] na podstawie którego w systemie YetiForce jest tworzony dokument WZ [Wydanie na Zewnątrz], a dokument WZ jest dokumentem magazynowym zmniejszającym stan magazynowy produktów. System pwiązuje produkty i ich stan magazynowy na podstawie pola EAN/SKU, które powinno być polem unikalnym w obu systemach [więcej informacji w sekcji mapowania pól].

W praktyce oznacza to, że Magento sam nie powinien zmieniać lokalnie [w Magento] stanu magazynowego, ale nawet jeżeli to robi [a w domyślnej wersji systemu bez modyfikacji kodu, właśnie tak działa Magento], wówczas system YetiForce nadpiszę stan magazynowy Magento na ten, który znajduje się w YetiForce. Informacje o stanie magazynowym są synchronizowane w krótkim odstępie czasu [zależy to od konfiguracji akcji CRON, domyślnie akcja wykonuje się raz na minutę gdy cały mechanizm CRON-a działa co minutę].

Aktualizacja statusów na zamówieniu

System YetiForce synchronizuje statusy zamówienia i statusy płatności pomiędzy systemami w obu kierunkach. 

Mapowanie pól

Należy pamiętać, że większość pól jest uzupełniana tylko przy tworzeniu, co oznacza w praktyce, że zmiana nazwy kategorii w jednym systemie nie wpływa na drugi system, a więc w drugim systemie należy ręcznie zmienić również nazwę [o ile jest to biznesowo zasadne]. Sama zmiana np. nazwy kategorii czy produktu, nie wpływa na synchronizacje, ponieważ ona zawsze odbywa się na podstawie pól unikalnych.

  1. Kategorie
    • Nazwa kategorii [Magento] > Nazwa kategorii [YetiForce]
    • Włącz kategorię [Magento] > Aktywna [YetiForce]
    • Kategoria nadrzędna [Magento]  > Kategoria nadrzędna [YetiForce]
  2. Produkty
    • Nazwa produktu [Magento] > Nazwa produktu [YetiForce]
    • Włącz produkt [Magento] > W sprzedaży [YetiForce]
    • SKU [Magento]  > SKU [YetiForce]
    • Opis [Magento]  > Opis [YetiForce]
  3. Kontakty
    • Płeć [Magento] > Płeć [YetiForce]
    • Imię [Magento] > Imię [YetiForce]
    • Nazwisko [Magento] > Nazwisko [YetiForce]
    • E-mail [Magento] > Mail podstawowy [YetiForce]
    • Numer telefonu [Magento] > Telefon podstawowy [YetiForce]
    • Faks [Magento] > Telefon dodatkowy [YetiForce]
    • Data urodzenia [Magento] > Data urodzenia [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Ulica i numer 1] [Magento] > [Adres podstawowy] pole [Ulica] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Ulica i numer 2] [Magento] > [Adres podstawowy] pole [Numer budynku] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Kod pocztowy] [Magento] > [Adres podstawowy] pole [Kod pocztowy] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Miasto] [Magento] > [Adres podstawowy] pole [Miejscowość] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Województwo] [Magento] > [Adres podstawowy] pole [Województwo] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Kraj] [Magento] > [Adres podstawowy] pole [Kraj] [YetiForce]
    • [Domyślny adres dostawy] pole [Ulica i numer 1] [Magento] > [Adres do doręczeń] pole [Ulica] [YetiForce]
    • [Domyślny adres dostawy] pole [Ulica i numer 2] [Magento] > [Adres do doręczeń] pole [Numer budynku] [YetiForce]
    • [Domyślny adres dostawy] pole [Kod pocztowy] [Magento] > [Adres do doręczeń] pole [Kod pocztowy] [YetiForce]
    • [Domyślny adres dostawy] pole [Miasto] [Magento] > [Adres do doręczeń] pole [Miejscowość] [YetiForce]
    • [Domyślny adres dostawy] pole [Województwo] [Magento] > [Adres do doręczeń] pole [Województwo] [YetiForce]
    • [Domyślny adres dostawy] pole [Kraj] [Magento] > [Adres do doręczeń] pole [Kraj] [YetiForce]
  4. Kontrahenci
    • Firma [Magento] > Nazwa kontrahenta [YetiForce] - jeżeli na zamówieniu jest osoba prywatna, wówczas system w YetiForce utworzy Kontrahenta oznaczego jako osoba prywatna, gdzie nazwa kontrahenta to jego Imię i Nazwisko. 
    • Numer NIP (VAT UE) [Magento] > NIP [YetiForce]
    • E-mail [Magento] > Mail podstawowy [YetiForce]
    • Numer telefonu [z odpowiedniego bloku] [Magento] > Telefon podstawowy [YetiForce]
    • Faks [z odpowiedniego bloku] [Magento] > Telefon dodatkowy [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Ulica i numer 1] [Magento] > [Adres podstawowy] pole [Ulica] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Ulica i numer 2] [Magento] > [Adres podstawowy] pole [Numer budynku] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Kod pocztowy] [Magento] > [Adres podstawowy] pole [Kod pocztowy] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Miasto] [Magento] > [Adres podstawowy] pole [Miejscowość] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Województwo] [Magento] > [Adres podstawowy] pole [Województwo] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Kraj] [Magento] > [Adres podstawowy] pole [Kraj] [YetiForce]
    • [Domyślny adres dostawy] pole [Ulica i numer 1] [Magento] > [Adres do doręczeń] pole [Ulica] [YetiForce]
    • [Domyślny adres dostawy] pole [Ulica i numer 2] [Magento] > [Adres do doręczeń] pole [Numer budynku] [YetiForce]
    • [Domyślny adres dostawy] pole [Kod pocztowy] [Magento] > [Adres do doręczeń] pole [Kod pocztowy] [YetiForce]
    • [Domyślny adres dostawy] pole [Miasto] [Magento] > [Adres do doręczeń] pole [Miejscowość] [YetiForce]
    • [Domyślny adres dostawy] pole [Województwo] [Magento] > [Adres do doręczeń] pole [Województwo] [YetiForce]
    • [Domyślny adres dostawy] pole [Kraj] [Magento] > [Adres do doręczeń] pole [Kraj] [YetiForce]
  5. Zamówienia
    • Numer zamówienia [Magento] > Temat [YetiForce]
    • Powiązanie kontrahenta [zgodnie z logią opisaną powyżej] [YetiForce]
    • Powiązanie kontaktu [zgodnie z logią opisaną powyżej] [YetiForce]
    • Powiązanie magazynu [YetiForce] - pole wypełniane automatycznie w YetiForce.
    • Link do porzedniego zamówienia [Magento] - Nadrzędne zamówienie [YetiForce]
    • Customer note [Magento] - Uwagi [YetiForce]
    • Źródło [YetiForce] - domyślnie ustawiana wartość Magento. 
    • Informacje o płatności [Magento] - Forma płatności [YetiForce] - słownik mapowany
    • Status płatności [Magento] - Status płatności [YetiForce] - słownik mapowany
    • Data zamówienia [Magento] > Data rozpoczęcia [YetiForce]
    • Stan zamówienia [Magento] - Status Magento, Status  [YetiForce]
    • Imię [Magento] > Imię [YetiForce] - do bloków adresowych na potrzeby wydruków
    • Nazwisko [Magento] > Nazwisko [YetiForce] - do bloków adresowych na potrzeby wydruków
    • Nazwa firmy [Magento] > Nazwa firmy [YetiForce] - do bloków adresowych na potrzeby wydruków
    • NIP [Magento] > NIP [YetiForce] - do bloków adresowych na potrzeby wydruków
    • Mail [Magento] > Email [YetiForce] - do bloków adresowych na potrzeby wydruków
    • [Domyślny adres rozliczeniowy] pole [Ulica i numer 1] [Magento] > [Adres główny] pole [Ulica] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Ulica i numer 2] [Magento] > [Adres główny] pole [Numer budynku] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Kod pocztowy] [Magento] > [Adres główny] pole [Kod pocztowy] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Miasto] [Magento] > [Adres główny] pole [Miejscowość] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Województwo] [Magento] > [Adres główny] pole [Województwo] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Kraj] [Magento] > [Adres główny] pole [Kraj] [YetiForce
    • [Domyślny adres dostawy] pole [Ulica i numer 1] [Magento] > [Adres dodostawy] pole [Ulica] [YetiForce]
    • [Domyślny adres dostawy] pole [Ulica i numer 2] [Magento] > [Adresdodostawy] pole [Numer budynku] [YetiForce]
    • [Domyślny adres dostawy] pole [Kod pocztowy] [Magento] > [Adres dodostawy] pole [Kod pocztowy] [YetiForce]
    • [Domyślny adres dostawy] pole [Miasto] [Magento] > [Adres dodostawy] pole [Miejscowość] [YetiForce]
    • [Domyślny adres dostawy] pole [Województwo] [Magento] > [Adres dodostawy] pole [Województwo] [YetiForce]
    • [Domyślny adres dostawy] pole [Kraj] [Magento] > [Adres dodostawy] pole [Kraj] [YetiForce]
  6. Zamówienie - blok z produktami/usługami
    • Produkt [Magento] > Nazwa pozycji [YetiForce] - mapowanie na podstawie SKU
    • Ilość [Magento] > Ilość [YetiForce]
    • Cena [Magento] > Cena jedn. [YetiForce]
    • Rabat [Magento] > Rabat [%] + Rabat [wartość] [YetiForce]
    • Podatek [Magento] > Podatek [YetiForce]
    • Waluta [ustawiana na podstawie waluty zamówienia] [YetiForce]
    • Typ rabatu [ustawiany automatycznie na indywidualny]  [YetiForce]
    • Typ podatku [ustawiany automatycznie na indywidualny]  [YetiForce]
  7. Faktury sprzedażowe
    • Numer zamówienia [Magento] > Temat [YetiForce]
    • Powiązanie kontrahenta [zgodnie z logią opisaną powyżej] [YetiForce]
    • Informacje o płatności [Magento] - Forma płatności [YetiForce] - słownik mapowany
    • Metoda płatności [Magento] - Forma płatności [YetiForce] - słownik mapowany
    • Data utworzenia [Magento] > Data wystawienia [YetiForce]
    • Data utworzenia [Magento] > Data sprzedaży [YetiForce]
    • Stan faktury [Magento] - Status [YetiForce]
    • Imię [Magento] > Imię [YetiForce] - do bloków adresowych na potrzeby wydruków
    • Nazwisko [Magento] > Nazwisko [YetiForce] - do bloków adresowych na potrzeby wydruków
    • Nazwa firmy [Magento] > Nazwa firmy [YetiForce] - do bloków adresowych na potrzeby wydruków
    • NIP [Magento] > NIP [YetiForce] - do bloków adresowych na potrzeby wydruków
    • Mail [Magento] > Email[YetiForce] - do bloków adresowych na potrzeby wydruków
    • [Domyślny adres rozliczeniowy] pole [Ulica i numer 1] [Magento] > [Adres główny] pole [Ulica] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Ulica i numer 2] [Magento] > [Adres główny] pole [Numer budynku] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Kod pocztowy] [Magento] > [Adres główny] pole [Kod pocztowy] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Miasto] [Magento] > [Adres główny] pole [Miejscowość] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Województwo] [Magento] > [Adres główny] pole [Województwo] [YetiForce]
    • [Domyślny adres rozliczeniowy] pole [Kraj] [Magento] > [Adres główny] pole [Kraj] [YetiForce
    • [Domyślny adres dostawy] pole [Ulica i numer 1] [Magento] > [Adres dodostawy] pole [Ulica] [YetiForce]
    • [Domyślny adres dostawy] pole [Ulica i numer 2] [Magento] > [Adresdodostawy] pole [Numer budynku] [YetiForce]
    • [Domyślny adres dostawy] pole [Kod pocztowy] [Magento] > [Adres dodostawy] pole [Kod pocztowy] [YetiForce]
    • [Domyślny adres dostawy] pole [Miasto] [Magento] > [Adres dodostawy] pole [Miejscowość] [YetiForce]
    • [Domyślny adres dostawy] pole [Województwo] [Magento] > [Adres dodostawy] pole [Województwo] [YetiForce]
    • [Domyślny adres dostawy] pole [Kraj] [Magento] > [Adres dodostawy] pole [Kraj] [YetiForce]
  8. Faktury sprzedażowe - blok z produktami/usługami
    • Produkt [Magento] > Nazwa pozycji [YetiForce] - mapowanie na podstawie SKU
    • Ilość [Magento] > Ilość [YetiForce]
    • Cena [Magento] > Cena jedn. [YetiForce]
    • Rabat [Magento] > Rabat [%] + Rabat [wartość] [YetiForce]
    • Podatek [Magento] > Podatek [YetiForce]
    • Waluta [ustawiana na podstawie waluty zamówienia] [YetiForce]
    • Typ rabatu [ustawiany automatycznie na indywidualny]  [YetiForce]
    • Typ podatku [ustawiany automatycznie na indywidualny]  [YetiForce]

Rozwiązywanie problemów integracji

Integracja ma oddzielne logi które są przechowywane w bazie danych, oraz wykorzystuje standardowe mechanizmy logowania. W logach znajdziemy wszystkie najważniejsze informacje w tym błędy integracji [np. pominięte rekordy i przyczynę ich pominięcia]. Przed pierwszym produkcyjnym uruchomieniem, powinno się rozwiązać wszystkie błędy które są nieakceptowalne biznesowo.

  • środa, 15 kwiecień 2020