Integracja z Apilo

Wstęp: Czym jest Apilo?

Apilo to zaawansowany system do zarządzania sprzedażą wielokanałową (omnichannel). Działa jako centralny panel dowodzenia dla e-commerce, pozwalając na spięcie Twojego sklepu internetowego z popularnymi platformami marketplace (m.in. Allegro, Amazon, eBay, Empik), setkami hurtowni, firmami kurierskimi oraz programami księgowymi (ERP).

Dzięki uruchomieniu dwukierunkowej integracji zyskujesz pełną automatyzację wymiany danych. Sklep i Apilo potrafią na bieżąco wymieniać się informacjami o kartotekach produktów, cenach, stanach magazynowych oraz zamówieniach.

Spis treści

• 1. Co robi integracja
• 2. Warunki działania i połączenie API
• 3. Przewodnik po konfiguracji zamówień
• 4. Przewodnik po konfiguracji produktów
• 5. Harmonogram zadań
• 6. Zasady powiązywania produktów
• 7. Eksport i Import asortymentu
• 8. Przetwarzanie i synchronizacja zamówień
• 9. Jak analizować Logi Integracji?
• 10. Diagnostyka krok po kroku
• 11. Kiedy zgłosić się do Supportu?

1. Co robi integracja

Dwukierunkowa integracja sklepu Selly z Apilo (systemem zarządzania sprzedażą wielokanałową) obsługuje następujące obszary:

Każdy z powyższych obszarów można włączyć niezależnie. Kierunek synchronizacji dla produktów, stanów i cen wybiera się za pomocą Trybów (opisanych w rozdziale 4).

2. Konfiguracja połączenia z Apilo (zakładka „Połączenie”):

Ustawienia w sklepie znajdziesz w: Panel admina → Integracje → Integracja Apilo.

Ustawienia w Apilo znajdziesz w: Panel admina → Administracja → Klucze API Apilo.

• W panelu Apilo wejdż w: Administracja → Klucze API Apilo i kliknij „Nowa aplikacja REST API”

• Wpisz własną nazwę aplikacji oraz zapisz.

• Po utworzeniu aplikacji, wejdź w panel sklepu: Integracje -> Integracje dodatkowe -> Apilo i skopiuj niezbędne dane. Następnie zapisz.

• Po wprowadzeniu poprawnych danych status połączenia zmieni się na „połączono”

WAŻNE INFORMACJE:

• Kod autoryzacyjny wygenerowany w Apilo jest ważny 3 godziny — należy go użyć niezwłocznie po wygenerowaniu.
• Po udanej autoryzacji system korzysta z tokenów odświeżających się automatycznie w tle.
• Zmiana Client ID lub Client Secret (albo długa przerwa w funkcjonowaniu crona) może unieważnić tokeny i wymusić konieczność ponownej autoryzacji. Sama zmiana adresu panelu nie przerywa autoryzacji.
• Dopóki status w pierwszej zakładce nie brzmi „Połączono”, pozostałe zakładki są zablokowane i synchronizacja nie ruszy.
• Jeśli chcesz tymczasowo usunąć integracje usuń „Adres panelu Apilo” oraz zapisz zmiany.

3. Przewodnik po konfiguracji zamówień

Zakładka: Zamówienia i faktury

Pozostałe kluczowe zakładki:

• Statusy zamówień: Tutaj mapujesz statusy. Status sklepu bez przypisanego odpowiednika w Apilo zablokuje eksport danego zamówienia. Ta sama mapa działa w obie strony (przy imporcie z Apilo).

• Wysyłki: Musisz wskazać domyślną formę dostawy dla zamówień pobieranych z Apilo, inaczej import wyrzuci błąd. Znajdziesz tu też dwie mapy przewoźników (jedna dla samego numeru przesyłki, druga dla określenia konta kurierskiego na zamówieniu).

• Płatności: Należy zdefiniować domyślną płatność w obu kierunkach oraz zmapować formy płatności sklepu. Zwróć uwagę, że na listach w nawiasach widnieją wewnętrzne ID Apilo.

4. Przewodnik po konfiguracji produktów

Trzy główne obszary danych opierają się na modelu wskazania „systemu nadrzędnego”.

Zakładki: Stany / Ceny / Produkty i cechy

• Apilo jest nadrzędne = dane nadpisują wartości w sklepie (Apilo → Sklep).
• Sklep jest nadrzędny = dane ze sklepu nadpisują te w Apilo (Sklep → Apilo).

Zasady widoczności i zakładania produktów:

Widoczność (status) produktu synchronizuje się zawsze wraz ze stanami magazynowymi (w obu kierunkach). Chroni to przed sytuacją, w której ukryty w sklepie produkt nadal by się sprzedawał przez kanały podpięte pod Apilo. Z kolei nowe kartoteki produktowe zakładane są w obu systemach wyłącznie wtedy, gdy aktywna jest synchronizacja Danych produktowych. Tryb ograniczony tylko do Cen i Stanów uaktualnia wyłącznie produkty już powiązane.

Dobra Praktyka:

Najczęstszą przyczyną zgłoszeń braku synchronizacji jest ustawienie nadrzędności w niewłaściwym kierunku. Jeśli zmienisz cenę w panelu sklepu, a nadrzędność ceny przypisana jest Apilo, modyfikacja nie zostanie wyeksportowana.

5. Harmonogram zadań i synchronizacja natychmiastowa

Zadania (takie jak Eksport katalogu, Import zamówień) układane są w kolejce i obsługiwane cyklicznie przez systemowego Crona. Jeden przebieg crona wykonuje jedno zadanie. Aktualny stan kolejki widzisz zawsze w sekcji „w Kolejce” natomiast wykonane zadania i ich logi w sekcji „Ostatnio wykonane”

Zdarzenia w czasie rzeczywistym (Sklep → Apilo):

• Gdy nadrzędny dla stanów/cen jest Sklep, zmiana w panelu sklepu natychmiastowo przesyła aktualizację do Apilo (poza kolejką cron).
• API Apilo nie wysyła do sklepu powiadomień natychmiastowych. Zmiany wprowadzone bezpośrednio w Apilo pojawią się w sklepie dopiero po wykonaniu cyklicznego zadania importu z kolejki.

6. Zasady powiązywania produktów

Aby synchronizacja działała na konkretnym asortymencie, systemy muszą powiązać produkty między sobą. Sklep przechowuje to powiązanie w dedykowanej tabeli technicznej. Widocznym dowodem powiązania jest wypełnione pole Kod dostawcy na karcie produktu w formacie APL##[ID_APILO].

Jak algorytm sklepu dopasowuje produkty z Apilo:

1. Po systemowym Kodzie Dostawcy APL##
2. Po zapisanej wcześniej historii mapowań technicznych.
3. Po zgodności SKU (kodu producenta).
4. Po zgodności kodów EAN.
5. W przypadku braku dopasowania → system zakłada nowy produkt (jeśli włączono import Danych Produktowych).

Zarządzanie powiązaniami asortymentu:

• Ręczne powiązanie z istniejącym produktem w Apilo: Wpisz w „Kod dostawcy” odpowiednią wartość APL##[ID_Apilo] i uruchom import.
• Powiązanie po kodach kreskowych: Upewnij się, że w obu panelach produkt ma identyczny EAN lub SKU, po czym wywołaj zadanie importu. System połączy je automatycznie.
• Usunięcie produktu w Apilo: Skutkuje to przerwaniem więzi. Przy kolejnym eksporcie, sklep założy ten sam produkt jako zupełnie nowy z nowym identyfikatorem w Apilo.
• Usunięcie produktu w sklepie: Integracja nie usunie go automatycznie z Apilo. W Apilo pozostanie aktywny. Należy skasować go tam ręcznie, aby zablokować sprzedaż.

7. Eksport i Import asortymentu w praktyce

• Eksport (Sklep → Apilo): Sklep wysyła standardowo tylko produkty zmodyfikowane od ostatniego przebiegu zadania. Raz na dobę uruchamiany jest tzw. pełny przebieg weryfikujący zgodność całego katalogu. Zdjęcia wypychane są asynchronicznie, wyłącznie gdy system wykryje zmianę w ich galerii (wymagany jest dostęp publiczny do adresów URL zdjęć w sklepie).
• Import (Apilo → Sklep): Pobierany jest pełen katalog (API Apilo nie pozwala na filtrowanie po dacie edycji). Jeśli na karcie produktu w sklepie włączona jest jakakolwiek blokada aktualizacji (np. blokada zmiany cen), integracja ją uszanuje. Zdjęcia z Apilo pobierane są wyłącznie raz (podczas zakładania produktu).
• Warianty asortymentu (np. rozmiary) przesyłane i odbierane są z/do Apilo w postaci osobnych kartotek (wynika to z ograniczeń konstrukcyjnych grup API Apilo).

8. Przetwarzanie i synchronizacja zamówień

• Eksport: Zamówienia pobrane ze sklepu otrzymują po stronie Apilo unikalny originalCode ułatwiający rozpoznawanie produktów oraz dedykowaną pozycję rabatową i koszt dostawy. Zabezpieczenie systemowe chroni przed wyeksportowaniem tego samego zamówienia dwukrotnie.
• Import: System odrzuca zamówienia puste, anulowane przez kupującego oraz te, dla których jakakolwiek z zamówionych pozycji nie jest rozpoznana w katalogu sklepu (aby zapobiec powstawaniu rozbieżności magazynowych).
• Synchronizacja wtórna: Moduł cyklicznie przez 14 dni monitoruje zamówienie, pobierając z Apilo nowe statusy, wpłaty korygujące, numery paczek przewozowych i ewentualne dokumenty księgowe. Zmiany na starszych zamówieniach nie będą przetwarzane ze względu na brak wsparcia Apilo dla znaczników modyfikacji wstecznej.

9. Jak analizować Logi Integracji?

Każde wykonanie zadania zapisuje wpis w historii (Sekcja „Zadania i logi” → „Ostatnio wykonane” → „Pokaż log”). Zawsze szukaj pierwszych i ostatnich linijek logu, aby zrozumieć, co ustawiłeś i co wykonał system.

Zakres eksportu — dane produktów: TAK, ceny: NIE, stany: TAK, cechy sklepu: NIE…

Z powyższego nagłówka jasno wynika, że na skutek konfiguracji, ten przebieg zignorował ceny (był to tryb „Apilo nadrzędne” lub „Brak”). Na dole logu znajdziesz podsumowanie. Zwróć uwagę, że wartość „licznik Apilo” odnosi się do ilości zapytań wewnętrznej bazy Apilo, a nie ilości przetworzonych fizycznie produktów w sklepie.

10. Diagnostyka (Sprawdź przed napisaniem)

W przypadku wątpliwości czy synchronizacja działa poprawnie, przeprowadź samodzielną weryfikację 4 elementów:

1. Połączenie: Upewnij się, że pierwsza zakładka nadal wskazuje status „Połączono”.
2. Tryby kierunkowe: Czy ustawiłeś nadrzędność systemu w stronę, w którą oczekujesz nadpisania parametru (Apilo nadpisuje Sklep, czy Sklep nadpisuje Apilo?).
3. Zadania w kolejce: Zwróć uwagę czy na liście zadań nie wiszą paski z komunikatem o błędach API oraz przeanalizuj pierwszy wers pliku z logami.
4. Historia produktu / zamówienia: Zawsze weryfikuj zakładkę „Historia” (w edycji konkretnego produktu lub zamówienia) – znajdziesz tam precyzyjne daty i znaczniki operacji (np. `Apilo: zaktualizowano produkt (cena 10.00 -> 12.50)`).

Najczęstsze zdarzenia pozorne (niebędące błędem)

• Apilo odrzuca wysłanie produktu, zgłaszając duplikat. (Zazwyczaj oznacza to, że w Apilo istnieje już inny produkt z tym samym kodem EAN).
• Zmieniłeś zdjęcie pod tym samym numerem, ale Apilo go nie podmieniło. (Znane ograniczenie Apilo: stara referencja jest zamrożona. W celu nadpisania zdjęcia w Apilo wymagane jest dodanie go jako „nowego” pod nowym numerem pliku).
• Kolejna wpłata do zamówienia nie została zaimportowana z Apilo (API Apilo wspiera wyłącznie pobieranie pierwszej dokonanej wpłaty).
• Nazwa towaru w panelu Apilo jest obcięta (API automatycznie ucina nazwy dłuższe niż 60 znaków na potrzeby swojego grupowania).

11. Kiedy zgłosić się do Supportu?

Jeśli konfiguracja trybów jest w 100% poprawna, błędy API z Apilo nie wskazują na uszkodzone kody kreskowe (EAN), log weryfikacyjny przebiegł przez dany zasób i pominął go bez przyczyny – zgłoś sprawę do zespołu wdrożeniowego.

Aby zgłoszenie mogło zostać sprawnie obsłużone, zawsze załącz:

• Numery ID sprawiającego problem produktu lub zamówienia (zarówno ze sklepu, jak i z panelu Apilo).
• Zrzuty ekranu konfiguracji trybów.
• Pełny plik z logiem konkretnego cyklu crona (od pierwszej do ostatniej linijki).
• Zrzut ekranu zakładki „Historia” wadliwego zamówienia / produktu.