Настройване на webhooks

С API ключ друга програма изтегля Вашите данни, когато ѝ трябват. При webhook е обратното: ние изпращаме съобщение към Ваш адрес веднага щом се случи нещо.

Това спестява чакане. Поръчка, която влиза в осем и петнадесет, е в счетоводството Ви в осем и петнадесет — а не на следващата обиколка, час по-късно.

За какво го използват клиентите:

• всяка продажба веднага в счетоводството или в собствена база данни;
• малък екран на входа, който показва кой току-що е влязъл;
• съобщение в групов чат веднага щом обиколка се разпродаде;
• собствен имейл или sms до купувача, освен нашия.

Тази статия е ръководството за екрана, стъпка по стъпка. Ако първо искате да разберете какво е уебхук и дали Ви трябва, прочетете Уебхукове.

Добре е да знаете: webhooks са част от същия план като API. При по-малък план API достъп не се появява в менюто Ви; ако все пак попаднете на екрана, виждате обяснение и бутон Към абонамента.

Къде да отидете

Отворете в менюто вляво Настройки → API достъп и щракнете горе върху раздела Webhooks. Само ролята Собственик вижда този екран.

Виждате три блока: Ние се обаждаме на Вас (обяснение), Нова дестинация (формулярът) и Дестинации (това, което вече съществува).

Какво Ви трябва

Едно нещо, и то трябва да съществува преди да започнете: адрес на Вашия собствен сървър, който може да приема съобщения. Това е малко работа по програмиране от Ваша страна — Вашият уеб разработчик или счетоводният Ви софтуер ще разбере какво имате предвид с „endpoint за webhooks".

Три изисквания:

1. Трябва да е https. Обикновен http адрес отхвърляме: по тази линия пътуват данни на купувачи.
2. Трябва да е достъпен отвън. Адрес във Вашата офис мрежа (нещо с 192.168. или 10.) не можем да достигнем и също го отхвърляме.
3. Трябва да отговаря бързо. Изчакваме десет секунди. Ако обработката отнема повече, нека сървърът Ви каже „ok" веднага и работи след това.

Добавяне на дестинация

Стъпка 1. Въведете адреса. В първото поле (https://...) — пълният адрес, към който може да изпращаме, например https://schetovodstvo.moyafirma.bg/webhooks/bileti.

Стъпка 2. Кажете за какво е. Второто поле (За какво е това?) не е задължително, но е удобно. „Нашето счетоводство", „екран на касата". Ако имате три, ще знаете коя за какво служи.

Стъпка 3. Отбележете за какво може да Ви уведомяваме. Под За какво да Ви уведомяваме? е списъкът. Това е най-важният избор. Отбележете само това, което наистина обработвате: всяко съобщение, което не използвате, е работа за сървъра Ви и шум в дневника Ви. Поне едно поле трябва да е отметнато; дестинация без съобщения никога не би получила нищо.

Съобщение	Кога тръгва
Създадена поръчка	Появила се е поръчка (количка не се брои).
Платена поръчка	Парите са постъпили.
Отменена поръчка	Поръчката е отменена или изтекла.
Възстановена поръчка	Има пълно или частично възстановяване.
Издаден билет	Издаден е билет.
Сканиран билет	Имало е сканиране на входа — включително отказано.
Анулиран билет	Билет е анулиран или възстановен.
Разпродаден часови слот	Часови интервал е пълен.
Часови слот отново свободен	Отново има място в пълен часови интервал.
Издаден ваучер	Продаден е ваучер.
Използван ваучер	От ваучер е удържана сума.
Издадена карта	Създадена е годишна карта.
Затворена касова сесия	Касово чекмедже е преброено и затворено.
Издадена фактура	Създадена е фактура или кредитно известие за купувач.

Стъпка 4 (по избор). Тестова дестинация. Ако адресът сочи към тестова среда, отметнете Тестова дестинация (получава само тестови събития). Повече за това по-долу, в „Тестова дестинация“.

Стъпка 5. Щракнете върху Добавяне на дестинация.

Можете да имате до двадесет дестинации. Ако вече имате двадесет, първо изтрийте една.

Тайната виждате само веднъж

Веднага след това се появява тайна: дълга последователност, започваща с whsec_.

Копирайте я сега и я предайте на този, който изгражда връзката. Ако презаредите страницата или смените раздела, тя е изчезнала.

С тази тайна подписваме всяко съобщение, което изпращаме към Вашия адрес. Така сървърът Ви може да провери, че съобщението наистина идва от нас, а не от някой, който е прихванал адреса Ви. Това не е лукс: без тази проверка Вашият endpoint е отворена врата, през която всеки може да подхвърли поръчки.

Изгубили сте тайната? Щракнете върху Нова тайна. Веднага получавате нова, а старата спира да работи от този момент — не забравяйте да я замените и от другата страна.

За този, който изгражда връзката, порталът за разработчици обяснява точно как се преизчислява този подпис, с примери на PHP, JavaScript и Python. Чрез API той може да поиска и подписано примерно съобщение, за да тества собствения си код, без първо да се прави продажба.

Тестване без продажба

Щракнете до дестинация върху Пробно съобщение. Тогава изпращаме едно съобщение от вида test.ping — без реални данни, само сигнал.

Отдолу веднага се отваря дневникът на съобщенията, за да видите какво отговори сървърът Ви. Ако пише Пристигнало, значи работи. Ако пише код за грешка, знаете къде да търсите. Пробното съобщение се изпраща и към дестинация, която е изключена.

Дневникът на съобщенията

Щракнете до дестинация върху Съобщения. Виждате последните петдесет съобщения, а за всяко от тях:

• от какъв вид е било и кога е тръгнало;
• какво е върнал сървърът Ви (числото е http статусът; 200 означава „ok");
• колко пъти сме опитвали;
• в какво състояние е: Пристигнало, На път (още опитваме) или Недоставено.

Ако съобщение не е пристигнало, можете да го подадете отново с Опитайте отново. Удобно, след като сте отстранили повреда от Ваша страна.

Съобщенията се пазят тридесет дни. След това се почистват: дневникът служи за намиране на проблем, не като архив.

Какво става, ако сървърът Ви не работи

Не се отказваме веднага. Ако съобщение не пристигне, опитваме още шест пъти, с все по-дълги интервали: след минута, пет минути, половин час, два часа, дванадесет часа и един ден. Общо доста повече от ден и половина.

Ако и тогава не се получи:

• дестинацията получава обозначението Не преминава;
• получавате един имейл. Той отива на Имейл за контакт на организацията Ви или на Имейл адрес за фактуриране, ако първият е празен (и двата са в Настройки → Организация, раздел Контакт);
• дестинацията остава включена. Следващите събития се предлагат отново и веднага щом нещо пристигне, обозначението изчезва.

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

Тестова дестинация

Отбележете Тестова дестинация при създаването, когато адресът сочи към тестова среда. Такава дестинация получава само тестови събития — това, което се случва с тестовите поръчки на тестов ключ — и никога реални продажби. В списъка тя носи обозначението Тест. Обратно, обикновена дестинация никога не получава нищо от тестова поръчка.

Това разделение е строго, и то нарочно: тестов сървър, който по погрешка обработи реална поръчка, изпраща потвърждение на реален купувач.

Изключване или изтриване

Изключване спира доставките, но запазва дестинацията, с нейната тайна и дневник; тя получава обозначението Изключено. Удобно по време на поддръжка от Ваша страна. Щракнете отново върху Включване и всичко тръгва пак.

Изтриване премахва дестинацията и дневника ѝ. Това не може да се отмени; нова дестинация получава нова тайна.

Има и трети случай: ако сървърът Ви някога отговори с код 410, изключваме дестинацията сами. Този код означава буквално „този адрес вече не съществува", а да продължаваме да чукаме би било невъзпитано. Същото става, когато адресът междувременно започне да сочи към вътрешна мрежа. Щракнете върху Включване, щом всичко е наред отново.

Три съвета за този, който изгражда връзката

1. Първо отговаряйте, после обработвайте. Кажете „ok" веднага и свършете истинската работа на заден план. Иначе се удряте в нашите десет секунди.
2. Обработвайте идемпотентно. Всяко съобщение носи свой номер (Idempotency-Key). Ако един и същ номер пристигне два пъти, не правете нищо. Ние опитваме отново при съмнение, а двойна резервация е по-лошо от двоен ред в дневника.
3. Не разчитайте на реда. Две съобщения могат да се изпреварят, когато първото се повтаря. Гледайте времето в съобщението и съдържанието му, не реда на пристигане.

Още за четене

• Уебхукове — какво е уебхук и кога Ви трябва, без технически термини.
• Създаване на API ключ — другият раздел на този екран.
• Порталът за разработчици — за този, който изгражда връзката.