Работа с вебхуками в Goulash.tech

9 мин

Продолжительность урока

Что такое вебхук?

Вебхук — это специальный программный код, с помощью которого можно следить за изменениями на одном сайте и передавать информацию об этом на другой сайт. Благодаря вебхуку новая информация приходит быстро до получателя.

В чем разница между API и вебхуками?

Данные об изменениях в системе также можно получать с помощью API, но для этого необходимо многократное обращение к серверу. В отличие от этого, вебхук настраивается всего один раз. Когда происходит нужное действие, он автоматически отправляет данные через протокол HTTP.

Вебхук отлично подходит для оперативного получения важных обновлений, таких как изменение цены, номера телефона или статуса заявки. Если же нужно полноценно работать с базами данных — просматривать, создавать, изменять или удалять информацию — в этом случае лучше выбирать API.

Какой принцип работы вебхуков?

Когда происходит заданное событие, вебхук автоматически отправляет информацию об изменениях. Для этого достаточно указать типы уведомлений и адрес получателя. Вам не нужно углубляться в детали работы механизма или писать программный код с нуля — настройка вебхуков осуществляется через удобный интерфейс.

Как работают вебхуки в Гуляше?

Перед тем, как начать работать с вебхуками, нужно дать всем необходимым ролям доступ к настройке вебхуков, пройду путь Главная > Справочники > Роли.

Далее находим роль, которой нам необходимо дать права на настройку вебхуков и нажимаем на карандаш, чтобы начать редактировать.

Права на настройку вебхуков будет находится в разделе Настройки > Настройка вебхуков.

Теперь настраиваем непосредственно вебхуки.

Для того, чтобы настроить вебхуки в Гуляше, нам необходимо перейти в раздел Настройки, найти раздел Вебхуки и выбрать Настройка вебхуков.

Перед нами откроется таблица с уже внесенными вебхуками. Мы можем их Создать, Редактировать, нажав на карандаш, или Удалить, нажав на крестик.

Для того, чтобы создать новый вебхук нажимаем на зеленую кнопку Создать.

Далее нам необходимо заполнить необходимые параметры:

Тип события. На данный момент в выпадающем списке доступен только один вариант Изменение заказа. В этом разделе выбираем причину, по которой будет отправляться уведомление.

Источники заказа. В этом поле нам необходимо выбрать один или несколько источников, из которых мы хотели бы получать информацию об изменениях статуса заказа. Если хотим выделить больше, чем один источник, следует прожать Cntr.

Оператор. В этом поле нам необходимо указать ФИО оператора, изменения статуса заказов которого мы хотим отслеживать.

URL. В этом поле нам необходимо вставить ссылку на конечный ресурс, на котором мы хотим принимать уведомления об изменении статуса заказа.

Настроив все необходимые параметры, нажимаем на Сохранить.

Тело запроса вебхуков

id;int;id заказа create_time;date;дата и время приема заказа (формат гггг-мм-дд чч:мм:сс) prepare_time;date;дата и время приготовления (формат гггг-мм-дд чч:мм:сс) delivery_time;date;дата и время доставки (формат гггг-мм-дд чч:мм:сс) current_time;date;текущая дата и время UTC +5 (формат гггг-мм-дд чч:мм:сс) total_amount;int;общая сумма заказа discount_amount;int;сумма скидки paid_by_bonuses;int;сумма оплаты бонусами (сушкоф) bonuses_gained;int;сумма начисленных бонусов total_amount_clean;int;сумма к оплате compensation;int;выданная компенсация (сумма) status;object;статус заказа city_id;int city_name;String delivery_type;string;delivery || self || self_car || hall || gift_certificate delivery_address;String;Адрес доставки delivery_address_add_info;String;Доп. информация к адресу (подъезд, этаж, квартира) comment;String?;Комментарий к доставке delivery_department_id;int;ID подразделения заказа delivery_department_address;String;Адрес подразделения заказа delivery_department_name;String;Название подразделения заказа delivery_department_contacts;ntkt[Object];Контакты подразделения (телефон и ссылка не телеграм канал ) {phone: ‘+7 999 999 99 99’, telegram: ‘Telegram – a new era of messa ging} complete;bool cancelled;bool orderring_current;bool;Заказ оформлен на текущее время order_type;int;7 - заказ сотрудника, 8 - доставка, 9 - самовывоз, 10 - зал, 14 - чаевые, 15 - доставка внешней службой доставки, 16 - подарочный сертификат, 17 - экспресс роллы, 18 - доставка курьером сервиса агрегатора total_products_count;int;Кол-во товаров в заказе products;[Object];Массив товаров в заказе (массив объектов Товар в корзине). Передается только при запросе детальной информации по заказу can_score;bool;Есть ли возможность оценить заказ has_score;bool;Заказ уже оценен score_categories;[Object];Массив объектов“Дополнительная категория оценки”Deprecated, с версии 1.13 score;Object;Объект оценка заказа Передается только при запросе детальной информации по заказу delivery_info;Object;Объект “Информация о доставке” promocodes;[String];Массив промокодов, примененных к заказу external_delivery_car_model;String?;Марка автомобиля, если доставка через сторонний сервис (ЖМ) external_delivery_car_number;String?;Гос. номер автомобиля, если доставка через сторонний сервис (ЖМ) gift_certificate;object?;Объект “подарочный сертификат” can-cancel;bool?;Можно ли отменить заказ mystery_shopper_offer;Object?;Предложение стать тайным покупателем{“token”: “токен тайного покупателя”} bet_offer;Object?;Предложение участия в тотализаторе (Сушкоф) tips_info;Object?;Информация для чаевых (ЖМ) update_hash;string?;Хеш для получения обновлений по веб сокетам is_qr_paid;bool?;Флаг, оплачен ли QR-код qr_url;string?;URL для оплаты заказа по QR-код (если is-qr-paid = false) loyalty_info;Object?;Если разрешена программа лояльности (ЖМ и приложение 1.34+):Объект “Значения программы лояльности в заказе” guest;guest:{id:int, phone:str, name:str, email:str};Информация о госте (только для Web-хуков) additional_products;[Object];Массив объектов “Группа дополнительной продукции”

Популярные вопросы.

1. Правильно ли я понимаю, что id заказа это некий уникальный идентификатор внутри системы, который не может совпадать для разных заказов?

Да, id заказа является уникальным идентификатором и не может повторяться.

2. code Номер заказа это то, что надо показывать клиенту?

Да, он так же является уникальным в смене.

3. Что status Статус заказа из себя представляет и как посмотреть возможные значения?

Вебхуки статуса заказа автоматически уведомляют об изменениях в статусе заказа, отправляя данные клиентам и внутренним системам для обновления информации.

Возможные значения вебхуков:
STATUS_NEW - Принят

STATUS_SEND - В пути

STATUS_DONE - Готов

STATUS_PRECHEK - Пречек

STATUS_COMPLETE - Выполнен/Доставлен

STATUS_CANCEL - Отмена

STATUS_RETURN - Возврат

STATUS_DELAYED - Отложен

STATUS_SITE_OPERATOR - Сайт (оператор)

STATUS_SITE_EDIT - Сайт (редактирование)

STATUS_ORDER_DROP - Брошен

STATUS_DELIVERED - Готов

4. Если нам нужен список заказанных блюд, то достаточно перебирать products (Массив товаров в заказе) и оттуда брать поле "name"?

Да, при запросе детальной информации по заказу все будет передано.

5. Информация о госте (только для Web-хуков) в нашем случае будет отправляться? Потому как нам для оповещения номер телефона заказчика просто необходим.

Да, данная информация будет присутствовать в вебхуке.

6. Ещё вопрос о частоте отправки подобных сообщений. Некоторые системы отправляют подобные сообщения в случае изменения статуса заказа. В частности, мы обрабатываем события "принят в работу", "отправлен заказчику" и "завершён". Некоторые же отправляют только последний статус, как результат завершения работы по заказу. Хотелось бы узнать, что отправляется у вас?

Вебхуки отправляются только при изменении статуса заказа, при создании нового заказа вебхуки не отправляются. Также при неудачной отправке вебхуков делается не более трех попыток повторной отправки на URL.

Важно! Не все данные из файла передаются, но также существуют данные, которые передаются, но не отражены в документы.

Турбо

С вебхуками на этом всё!

Понравился материал?

Понравилось?

Goulash