Автоматизации

Как да настроите уебхукове в easySales: изпращайте поръчки, етикети и промени в наличностите към своите системи

Как да настроите уебхукове в easySales: изпращайте поръчки, етикети и промени в наличностите към своите системи

Изпращайте събития от easySales, като нови поръчки, етикети за доставка, фактури и промени в наличностите, към своите системи в момента, в който се случат, и поддържайте абонаментите работещи.

За какво служат уебхуковете

Уебхукът уведомява друга система в момента, в който нещо се случи в easySales. Когато пристигне поръчка, се създаде етикет за доставка или се промени наличност, easySales изпраща данните на адрес, който Вие изберете. Така Вашата ERP система, счетоводна програма или онлайн магазин могат да реагират веднага, вместо да проверяват easySales на всеки няколко минути.

Отворете страницата easy-sales.com/webhooks, докато сте влезли в акаунта си. Всеки ред на нея е абонамент: едно събитие, изпращано към един адрес.

Три неща, които е добре да знаете от самото начало:

  • Адресът, който получава данните, трябва да бъде изграден от Вас или от Вашия разработчик. easySales изпраща данните, а системата на този адрес решава какво да прави с тях.
  • Абонамент, който постоянно се проваля, се изключва сам. След 100 неуспешни опита easySales спира да изпраща и Ви уведомява по имейл. Абонаментът не се включва отново сам.
  • Докато абонаментът е изключен, събитията не се пазят. Когато го включите отново, изпращането започва от този момент.

Абониране за събитие

Страницата Webhooks: бутонът Subscribe to webhook и четири абонамента, групирани по събитие: Order created и Order updated със Success, Invoice created с Failed и Product stock updated с Failed и бутона Enable. При всеки се виждат URL адресът, тайният ключ, методът и More details.
По един абонамент за всяко събитие и адрес.
  1. Натиснете Subscribe to webhook.
  2. В Url въведете адреса, който ще получава данните. Използвайте https адрес.
  3. Оставете HTTP method на POST.
  4. В Webhook изберете събитието.
  5. В Secret въведете ключ от поне 24 знака. Вашата система го използва, за да провери, че данните наистина идват от easySales.
  6. Натиснете Save.

Абонаментът се появява под името на своето събитие. За да изпращате същото събитие и към втора система, абонирайте се отново с другия адрес. Един адрес може да се добави само веднъж за всяко събитие.

Събитие Кога се изпраща
Order created Пристига нова поръчка от който и да е канал или поръчка е добавена ръчно.
Order updated Нещо в поръчката се променя, например статусът, продуктите или адресът. Това събитие се изпраща често.
Awb created За поръчка се създава етикет за доставка чрез куриер в easySales.
Delivery status updated Куриерът съобщава нов статус на доставката за пратка.
Invoice created, Storno invoice created За поръчка се издава фактура или сторно фактура.
Return created, Return updated Създава се връщане или се променят статусът, продуктите, бележките, пратките или фактурите му.
Product created, Product updated Продукт е добавен или променен, включително цената му.
Product stock updated Наличността на продукт се променя.
Category created / updated, Characteristic created / updated Категория или характеристика е добавена или променена.
Products refresh requested, Stock refresh requested За онлайн магазин е поискано опресняване на продуктите или наличностите.
Ticket created, Ticket updated В Клиенти → Сигнали започва разговор с купувач или съществуващ разговор се променя.
Account suspended, Account activated Акаунтът в easySales е спрян или активиран отново.
Събития, за които можете да се абонирате

Проверете какво е изпратено

Абонамент Invoice created с отворено More details: данните за фактурата, изпратени като payload, и отговорът Service Unavailable с означенията Attempt 2 of 3, часа на следващия опит и кода на състоянието 503.
Последното изпратено събитие и отговорът на Вашия адрес.

При всеки абонамент се вижда Success или Failed за последното изпратено събитие и кога е изпратено. Натиснете More details..., за да видите това събитие:

  • Payload са данните, които easySales е изпратил.
  • Response е отговорът на Вашия адрес, заедно с кода на състоянието.
  • Attempt 2 of 3 | Next attempt: … означава, че изпращането не е успяло и събитието ще бъде изпратено отново. Final attempt has been made означава, че за това събитие няма да има повече опити.

Тук се вижда само последното събитие на всеки абонамент.

Промяна, спиране или премахване на абонамент

Формулярът за уебхук с Url, HTTP method POST, Webhook Invoice created, Secret и Save.
Адрес, метод, събитие и таен ключ.
  • Edit променя адреса, HTTP метода или тайния ключ. За да изпращате друго събитие, абонирайте се за него и премахнете стария абонамент.
  • Disable спира временно абонамента, а Enable го пуска отново. Докато е спрян, нищо не се изпраща, а събитията от този период не се изпращат и по-късно.
  • Unsubscribe премахва абонамента веднага.

Какво трябва да прави Вашата система

Подробности
Формат JSON, с данните за събитието под payload и идентификатора на абонамента и името на събитието под webhook.
Подпис Заглавката Signature съдържа HMAC-SHA256 на тялото на заявката, изчислен с Вашия таен ключ. Изчислявайте го върху тялото точно както е получено.
Отговор Всеки статус 2xx до 3 секунди. Първо отговорете, а след това обработете данните.
Сертификат https адресите трябва да имат валиден сертификат.
Повторни опити Три опита за всяко събитие: вторият около 10 секунди след първия, третият около 100 секунди по-късно.
Ред на пристигане Заради повторните опити събитията може да пристигнат в различен ред. Разчитайте на данните в payload, а не на времето на пристигане.
Какво изпраща и какво очаква easySales

Когато абонаментът се изключи сам

Брои се всеки неуспешен опит: отговор с грешка, липса на отговор до 3 секунди или проблем със сертификата. След 100 неуспешни опита абонаментът се изключва и получавате имейла „Уебхукът беше деактивиран“. Бутонът Преглед на уебхуковете в него отваря тази страница.

  1. Отстранете проблема на адреса, който получава данните.
  2. Натиснете Enable при абонамента.
  3. Изтеглете през API на easySales пропуснатите промени, например поръчките, променени през този период.
📖
Прочети също
Как да се свържете с API на easySales: OAuth клиенти и лични токени за достъп
Създайте OAuth клиенти и лични токени за достъп до API на easySales, изберете правилния grant тип и обхвати и не позволявайте връзките да се изключват взаимно.
→
📖
Прочети също
Как да свържете персонализиран магазин с easySales през API
Свържете всеки персонализиран или неподдържан магазин с easySales през API: двете нужни удостоверения, изпращане на продукти и наличности, подаване на поръчки и получаване на промените обратно.
→

Достъп на екипа до уебхуковете

Член на екипа се нуждае от правото Преглед на webhook-овете, за да отвори страницата. С него може да добавя, променя, спира и премахва абонаменти.

Когато нещо не работи както трябва

Симптом Какво да направите
Вече нищо не пристига, а при абонамента се вижда Enable Абонаментът е изключен след повтарящи се неуспехи. Поправете адреса, натиснете Enable и изтеглете пропуснатите промени през API.
Последното събитие показва Failed Отворете More details... и проверете кода на състоянието и отговора на Вашия адрес.
„The secret must be at least 24 characters.“ Въведете таен ключ от 24 или повече знака.
„The url has already been taken.“ Този адрес вече получава това събитие. Вместо да добавяте нов абонамент, редактирайте съществуващия.
Сторно фактурите не пристигат Абонирайте се за Storno invoice created; Invoice created обхваща само обикновените фактури.
Получаващата система е залята с актуализации на поръчки Order updated се изпраща при всяка промяна. Отговаряйте бързо и обработвайте данните във фонов режим.
Чести проблеми

Често задавани въпроси

Отворете easy-sales.com/webhooks, докато сте влезли в акаунта си. Имейлът „Уебхукът беше деактивиран“ също води към тази страница.

След 100 неуспешни опита easySales изключва абонамента и Ви изпраща имейл. Поправете адреса, който получава данните, и натиснете Enable.

Не. Изтеглете промените от този период през API на easySales.

Изчислете HMAC-SHA256 на тялото на заявката с Вашия таен ключ и го сравнете със заглавката Signature.

До 3 секунди, със статус 2xx. В противен случай опитът се брои за неуспешен и се повтаря.

Да, с правото Преглед на webhook-овете.

Беше ли полезно това ръководство?