Automatyzacje

Jak skonfigurować webhooki w easySales: wysyłaj zamówienia, etykiety i zmiany stanów do swoich systemów

Jak skonfigurować webhooki w easySales: wysyłaj zamówienia, etykiety i zmiany stanów do swoich systemów

Wysyłaj zdarzenia z easySales, takie jak nowe zamówienia, etykiety, faktury i zmiany stanów magazynowych, do swoich systemów w chwili, gdy się dzieją, i dbaj o to, by subskrypcje działały.

Do czego służą webhooki

Webhook powiadamia inny system w chwili, gdy coś dzieje się w easySales. Gdy wpada zamówienie, powstaje etykieta albo zmienia się stan magazynowy, easySales wysyła szczegóły na wybrany przez Ciebie adres. Dzięki temu Twój ERP, program księgowy lub sklep internetowy może zareagować od razu, zamiast co kilka minut odpytywać easySales.

Otwórz stronę easy-sales.com/webhooks, gdy jesteś zalogowany. Każda pozycja na niej to subskrypcja: jedno zdarzenie wysyłane na jeden adres.

Trzy rzeczy, które warto wiedzieć na start:

  • Adres, który odbiera dane, musisz przygotować Ty lub Twój programista. easySales wysyła dane, a system pod tym adresem decyduje, co z nimi zrobić.
  • Subskrypcja, która ciągle zawodzi, sama się wyłącza. Po 100 nieudanych próbach easySales przestaje wysyłać dane i powiadamia Cię e-mailem. Subskrypcja nie włącza się ponownie sama.
  • Gdy subskrypcja jest wyłączona, zdarzenia nie są przechowywane. Po jej ponownym włączeniu wysyłka rusza od tej chwili.

Jak dodać subskrypcję zdarzenia

Strona Webhook (Pulpit > Webhook): przycisk Subscribe to webhook i cztery subskrypcje pogrupowane według zdarzeń: Order created i Order updated na adres erp.sklepdemo.pl/hooks/easysales/orders ze statusem Success, Invoice created na adres ksiegowosc.sklepdemo.pl/webhook ze statusem Failed oraz Product stock updated na adres www.sklepdemo.pl/easysales/stan ze statusem Failed i przyciskiem Enable. Przy każdej widać URL, klucz, metodę i More details.
Jedna subskrypcja na zdarzenie i adres.
  1. Kliknij Subscribe to webhook.
  2. W polu Url wpisz adres, który ma odbierać dane. Użyj adresu https.
  3. W polu HTTP method zostaw POST.
  4. W polu Webhook wybierz zdarzenie.
  5. W polu Secret wpisz klucz o długości co najmniej 24 znaków. Twój system sprawdza nim, czy dane naprawdę pochodzą z easySales.
  6. Kliknij Save.

Subskrypcja pojawi się pod nazwą swojego zdarzenia. Aby wysyłać to samo zdarzenie także do drugiego systemu, dodaj kolejną subskrypcję z innym adresem. Dany adres można dodać tylko raz dla każdego zdarzenia.

Zdarzenie Kiedy jest wysyłane
Order created Wpada nowe zamówienie z dowolnego kanału albo zamówienie zostaje dodane ręcznie.
Order updated Na zamówieniu zmienia się cokolwiek, np. status, produkty lub adres. To zdarzenie jest wysyłane często.
Awb created W easySales zostaje utworzona etykieta kurierska do zamówienia.
Delivery status updated Kurier zgłasza nowy status doręczenia przesyłki.
Invoice created, Storno invoice created Do zamówienia zostaje wystawiona faktura lub faktura korygująca.
Return created, Return updated Zostaje utworzony zwrot albo zmieniają się jego status, produkty, notatki, przesyłki lub faktury.
Product created, Product updated Produkt zostaje dodany lub zmieniony, także jego cena.
Product stock updated Zmienia się stan magazynowy produktu.
Category created / updated, Characteristic created / updated Kategoria lub cecha zostaje dodana albo zmieniona.
Products refresh requested, Stock refresh requested Dla sklepu internetowego zostaje zlecone odświeżenie produktów lub stanów magazynowych.
Ticket created, Ticket updated W Klienci → Zgłoszenia zaczyna się rozmowa z kupującym albo istniejąca rozmowa się zmienia.
Account suspended, Account activated Konto easySales zostaje zawieszone lub ponownie aktywowane.
Zdarzenia, które możesz subskrybować

Sprawdź, co zostało wysłane

Subskrypcja Invoice created na adres ksiegowosc.sklepdemo.pl/webhook z otwartym More details: dane faktury w PLN wysłane jako payload i odpowiedź Service Unavailable z oznaczeniami Attempt 2 of 3, czasem następnej próby i kodem statusu 503.
Ostatnio wysłane zdarzenie i odpowiedź Twojego adresu.

Przy każdej subskrypcji widać Success albo Failed dla ostatnio wysłanego zdarzenia oraz czas wysyłki. Kliknij More details..., aby zobaczyć to zdarzenie:

  • Payload to dane wysłane przez easySales.
  • Response to odpowiedź Twojego adresu wraz z kodem statusu.
  • Attempt 2 of 3 | Next attempt: … oznacza, że wysyłka się nie powiodła i zdarzenie zostanie wysłane ponownie. Final attempt has been made oznacza, że dla tego zdarzenia nie będzie już kolejnych prób.

Widać tu tylko ostatnie zdarzenie każdej subskrypcji.

Jak zmienić, wstrzymać lub usunąć subskrypcję

Formularz webhooka z polami Url, HTTP method POST, Webhook Invoice created, Secret i przyciskiem Save.
Adres, metoda, zdarzenie i klucz.
  • Edit zmienia adres, metodę HTTP lub klucz. Aby wysyłać inne zdarzenie, zasubskrybuj to zdarzenie i usuń starą subskrypcję.
  • Disable wstrzymuje subskrypcję, a Enable ponownie ją uruchamia. W czasie wstrzymania nic nie jest wysyłane, a zdarzenia z tego okresu nie zostaną wysłane później.
  • Unsubscribe od razu usuwa subskrypcję.

Co musi robić Twój system

Szczegóły
Format JSON, z danymi zdarzenia w payload oraz id subskrypcji i nazwą zdarzenia w webhook.
Podpis Nagłówek Signature zawiera HMAC-SHA256 treści żądania, obliczony Twoim kluczem. Obliczaj go na treści dokładnie w takiej postaci, w jakiej dotarła.
Odpowiedź Dowolny status 2xx w ciągu 3 sekund. Najpierw odpowiedz, a dane przetwórz później.
Certyfikat Adresy https muszą mieć ważny certyfikat.
Ponowne próby Trzy próby na zdarzenie: druga ok. 10 sekund po pierwszej, trzecia ok. 100 sekund później.
Kolejność dostarczania Przez ponowne próby zdarzenia mogą docierać w innej kolejności. Opieraj się na danych z payloadu, a nie na czasie ich dotarcia.
Co easySales wysyła i czego oczekuje

Gdy subskrypcja sama się wyłączy

Liczy się każda nieudana próba: odpowiedź z błędem, brak odpowiedzi w ciągu 3 sekund lub problem z certyfikatem. Po 100 nieudanych próbach subskrypcja zostaje wyłączona, a Ty dostajesz e-mail „Webhook został deaktywowany”. Przycisk Zobacz webhooki w tej wiadomości otwiera tę stronę.

  1. Usuń problem po stronie adresu, który odbiera dane.
  2. Kliknij Enable przy subskrypcji.
  3. Pobierz przez API easySales zmiany, które Cię ominęły, np. zamówienia zmienione w tym czasie.
📖
Czytaj dalej
Jak połączyć się z API easySales: klienci OAuth i tokeny dostępu osobistego
Utwórz klientów OAuth i tokeny dostępu osobistego do API easySales, wybierz właściwy typ grantu i zakresy i nie dopuść, by połączenia wylogowywały się nawzajem.
→
📖
Czytaj dalej
Jak połączyć własny sklep z easySales przez API
Podłącz przez API dowolny własny lub nieobsługiwany sklep do easySales: dwa potrzebne poświadczenia, wysyłanie produktów i stanów, przekazywanie zamówień i odbieranie zmian z powrotem.
→

Dostęp zespołu do webhooków

Członek zespołu potrzebuje uprawnienia Webhooki, aby otworzyć stronę. Z tym uprawnieniem może dodawać, zmieniać, wstrzymywać i usuwać subskrypcje.

Gdy coś nie działa tak, jak powinno

Objaw Co zrobić
Nic już nie dociera, a przy subskrypcji widać Enable Subskrypcja została wyłączona po powtarzających się błędach. Popraw adres, kliknij Enable, a potem pobierz pominięte zmiany przez API.
Ostatnie zdarzenie ma status Failed Otwórz More details... i sprawdź kod statusu oraz odpowiedź swojego adresu.
„The secret must be at least 24 characters.” Wpisz klucz o długości co najmniej 24 znaków.
„The url has already been taken.” Ten adres już otrzymuje to zdarzenie. Zamiast dodawać nową subskrypcję, edytuj istniejącą.
Nie docierają faktury korygujące Zasubskrybuj Storno invoice created; Invoice created obejmuje tylko zwykłe faktury.
System odbierający jest zalewany aktualizacjami zamówień Order updated jest wysyłane przy każdej zmianie. Odpowiadaj szybko, a dane przetwarzaj w tle.
Najczęstsze problemy

Często zadawane pytania

Otwórz easy-sales.com/webhooks, gdy jesteś zalogowany. Link do tej strony znajdziesz też w e-mailu „Webhook został deaktywowany”.

Po 100 nieudanych próbach easySales wyłącza subskrypcję i wysyła Ci e-mail. Popraw adres, który odbiera dane, i kliknij Enable.

Nie. Pobierz zmiany z tego okresu przez API easySales.

Oblicz HMAC-SHA256 treści żądania swoim kluczem i porównaj wynik z nagłówkiem Signature.

W ciągu 3 sekund, ze statusem 2xx. W przeciwnym razie próba jest uznawana za nieudaną i zostaje powtórzona.

Tak, jeśli ma uprawnienie Webhooki.

Czy ten przewodnik był pomocny?