Как да настроите уебхукове в easySales: изпращайте поръчки, етикети и промени в наличностите към своите системи
Изпращайте събития от easySales, като нови поръчки, етикети за доставка, фактури и промени в наличностите, към своите системи в момента, в който се случат, и поддържайте абонаментите работещи.
За какво служат уебхуковете
Уебхукът уведомява друга система в момента, в който нещо се случи в easySales. Когато пристигне поръчка, се създаде етикет за доставка или се промени наличност, easySales изпраща данните на адрес, който Вие изберете. Така Вашата ERP система, счетоводна програма или онлайн магазин могат да реагират веднага, вместо да проверяват easySales на всеки няколко минути.
Отворете страницата easy-sales.com/webhooks, докато сте влезли в акаунта си. Всеки ред на нея е абонамент: едно събитие, изпращано към един адрес.
Три неща, които е добре да знаете от самото начало:
- Адресът, който получава данните, трябва да бъде изграден от Вас или от Вашия разработчик. easySales изпраща данните, а системата на този адрес решава какво да прави с тях.
- Абонамент, който постоянно се проваля, се изключва сам. След 100 неуспешни опита easySales спира да изпраща и Ви уведомява по имейл. Абонаментът не се включва отново сам.
- Докато абонаментът е изключен, събитията не се пазят. Когато го включите отново, изпращането започва от този момент.
Абониране за събитие
- Натиснете Subscribe to webhook.
- В Url въведете адреса, който ще получава данните. Използвайте https адрес.
- Оставете HTTP method на POST.
- В Webhook изберете събитието.
- В Secret въведете ключ от поне 24 знака. Вашата система го използва, за да провери, че данните наистина идват от easySales.
- Натиснете 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 е спрян или активиран отново. |
Проверете какво е изпратено
При всеки абонамент се вижда Success или Failed за последното изпратено събитие и кога е изпратено. Натиснете More details..., за да видите това събитие:
- Payload са данните, които easySales е изпратил.
- Response е отговорът на Вашия адрес, заедно с кода на състоянието.
- Attempt 2 of 3 | Next attempt: … означава, че изпращането не е успяло и събитието ще бъде изпратено отново. Final attempt has been made означава, че за това събитие няма да има повече опити.
Тук се вижда само последното събитие на всеки абонамент.
Промяна, спиране или премахване на абонамент
- Edit променя адреса, HTTP метода или тайния ключ. За да изпращате друго събитие, абонирайте се за него и премахнете стария абонамент.
- Disable спира временно абонамента, а Enable го пуска отново. Докато е спрян, нищо не се изпраща, а събитията от този период не се изпращат и по-късно.
- Unsubscribe премахва абонамента веднага.
Какво трябва да прави Вашата система
| Подробности | |
|---|---|
| Формат | JSON, с данните за събитието под payload и идентификатора на абонамента и името на събитието под webhook. |
| Подпис | Заглавката Signature съдържа HMAC-SHA256 на тялото на заявката, изчислен с Вашия таен ключ. Изчислявайте го върху тялото точно както е получено. |
| Отговор | Всеки статус 2xx до 3 секунди. Първо отговорете, а след това обработете данните. |
| Сертификат | https адресите трябва да имат валиден сертификат. |
| Повторни опити | Три опита за всяко събитие: вторият около 10 секунди след първия, третият около 100 секунди по-късно. |
| Ред на пристигане | Заради повторните опити събитията може да пристигнат в различен ред. Разчитайте на данните в payload, а не на времето на пристигане. |
Когато абонаментът се изключи сам
Брои се всеки неуспешен опит: отговор с грешка, липса на отговор до 3 секунди или проблем със сертификата. След 100 неуспешни опита абонаментът се изключва и получавате имейла „Уебхукът беше деактивиран“. Бутонът Преглед на уебхуковете в него отваря тази страница.
- Отстранете проблема на адреса, който получава данните.
- Натиснете Enable при абонамента.
- Изтеглете през API на easySales пропуснатите промени, например поръчките, променени през този период.
Достъп на екипа до уебхуковете
Член на екипа се нуждае от правото Преглед на 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 се изпраща при всяка промяна. Отговаряйте бързо и обработвайте данните във фонов режим. |