> For the complete documentation index, see [llms.txt](https://ytimes-2.gitbook.io/ytimes-kafe/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ytimes-2.gitbook.io/ytimes-kafe/integracii/vneshnii-api/webhook-api.md).

# WebHook API

Приложение может отправлять события на ваш сервер, такие как изменение статуса заказа или информацию о том, что в системе изменилось меню.

### Настройка

Для включения необходимо создать интеграцию на странице "**Настройки - Интеграции**" с типом "**Интеграция по API**". В настройках интеграции указать ключ авторизации (он будет отправлен вам в header **Authorization**, чтобы вы понимали что запрос пришел от нас) и указать URL-адреса, на которые нужно отправлять те или иные события. Если для события указан адрес, на него будет отправляться событие, если адрес не указан, то соответственно ничего отправляться не будет.

Например, если вы указали адрес **<https://example.ytimes.ru/notification/menu/update>** для событий изменений меню, на него будут поступать запросы всякий раз, когда кто-то в личном кабинете YTimes будет менять настройки меню.

В теле запроса будет передаваться JSON, соответствующий событию. В поле **eventId** будет передаваться UUID события - это ключ идемпотентности, чтобы повторные запросы не приводили к дублированию на вашей стороне.&#x20;

При успешной обработке события ваш сервер должен ответить **кодом 200** и в теле ответа отправить "**OK**". Мы будем отправлять событие каждые 5 минут до тех пор пока ваш сервер не примет событие. Если в течение 48 часов успешного ответа не получено, отправка события отменяется.

## Статус заказа, созданного по API

<mark style="color:green;">`POST`</mark> `{your url}/remote-order/status`

Передает информацию и принятии или отмене заказа (созданного через API) кассиром.\
\
event\
guid - идентификатор заказа.\
status - может принимать значения CANCELLED или ACCEPTED.

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer {your key} |

#### Request Body

| Name                                   | Type   | Description                                                                                                                                                                                                 |
| -------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| body<mark style="color:red;">\*</mark> | string | <p>{ <br>    "eventId": "ключ идемпотентности",<br>    "guid" : "885188cd-d0ee-4444-919e-4f063359dff7", <br>    "status" : "CANCELLED", <br>    "statusMessage" : "Отсутствуют позиции в наличие" <br>}</p> |

{% tabs %}
{% tab title="200 ответ вашего сервера" %}

```
OK
```

{% endtab %}
{% endtabs %}

## Событие изменения меню

<mark style="color:green;">`POST`</mark> `{your base url}/menu/changed`

Информация о том, что в системе изменились настройки меню. После этого необходимо запросить с сервера актуальную версию меню.\
\
В событии отправляется тип меню, который был изменен. Возможные варианты: MENU\_GROUP, MENU\_ITEM, SUPPLEMENT\_GROUP, SUPPLEMENT, COMBO

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer {your key} |

#### Request Body

| Name                                   | Type   | Description                                                                                    |
| -------------------------------------- | ------ | ---------------------------------------------------------------------------------------------- |
| body<mark style="color:red;">\*</mark> | string | <p>{<br>   "eventId": ключ идемпотентности<br>   "type": тип меню, которое изменилось<br>}</p> |

{% tabs %}
{% tab title="200 ответ вашего сервера" %}

```
OK
```

{% endtab %}
{% endtabs %}

## Изменение анкеты карты гостя

<mark style="color:green;">`POST`</mark> `{your base url}/client/update`

Если анкету базы клиентов изменили (включая изменение бонусного баланса), то срабатывает данное событие.

#### Headers

| Name          | Type   | Description       |
| ------------- | ------ | ----------------- |
| Authorization | string | Bearer {your key} |

#### Request Body

| Name                                   | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| body<mark style="color:red;">\*</mark> | string | <p>{ <br>  eventId: ключ идемпотентности</p><p>  dateTimeUTC: дата/время события по UTC <br>  phoneCode: телефонный код страны, например 7 для РФ <br>  phone: телефон</p><p>  number: номер карты гостя (целое число) <br>  name: имя гостя <br>  surname: фамилия гостя <br>  email: электронная почта <br>  birthday: день рождения sex: пол <br>  comment: комментарий к карте <br>  isAgreeToNotification: наличие согласия на получение рассылки (true/false)</p><p>  excludeAddPoints: если true, данному гостю нельзя начислять бонусы (true/false) <br>  pointsValue: текущий баланс гостя на момент события (double) <br>  pointsChange: изменение баланса гостя в результате события (double) <br>  pointsChangeComment: комментарий к изменению баланса гостя</p><p>  statVisitCount: общее кол-во посещений (int) <br>  statPayValue: общая оплаченная сумма (double) <br>  statLastMonthVisitCount: количество посещений в прошлый месяц (int) <br>  statLastMonthPayValue: сумма оплаты в прошлый месяц (double) <br>  statCurrentMonthVisitCount: количество посещений в текущий месяц (int) <br>  statCurrentMonthPayValue: сумма оплаты в текуший месяц (double) <br>}</p> |

{% tabs %}
{% tab title="200 ответ вашего сервера" %}

```
OK
```

{% endtab %}
{% endtabs %}

### Пример контроллера для приема событий

```java
@Controller
@RequestMapping("/public/exapi/webhook/")
public class ExWebHookTestController {


    @RequestMapping("/menu/changed")
    @ResponseBody
    public String menuChanged(@RequestHeader(required = false) String Authorization,
                              @RequestBody(required = false) Map body) {
        //check auth header
        //do something
        return "OK";
    }

    @RequestMapping("/order/status")
    @ResponseBody
    public String orderStatus(@RequestHeader(required = false) String Authorization,
                              @RequestBody(required = false) Map body) {
        //check auth header
        //do something
        return "OK";
    }

}
```