Интеграция с Hype Custom: справочник за API

Ключ на адаптера: hype-custom (HC) Документация в Postman: https://documenter.getpostman.com/view/52109283/2sBXc8oNnL

Съдържание

Общ преглед
Архитектура
Удостоверяване
Базови URL адреси и ограничения
Обработка на грешки
Система от задачи
Справочник за обектите
Webhook адреси
Управление на интеграции
Управление на опашки
Статуси на интеграцията и процеса на синхронизация
Първоначална синхронизация
Текуща синхронизация
Кратък справочник

1. Общ преглед

Hype Custom е адаптер за двупосочна интеграция в Hype Exchange Service (HES). Тази облачна услуга синхронизира данни между Hype POS, инсталиран на място в ресторанта, и външни платформи.

Адаптерът hype-custom позволява на външна платформа да:

Получава категории, добавки, салони, маси и артикули от менюто на Hype POS
Изпраща заявки за поръчки от онлайн платформа към Hype POS
Синхронизира канали за доставка, видове плащане и статуси на поръчки между платформите
Управлява жизнения цикъл на поръчките: създаване, промяна на статус и проследяване на доставката

Какво е Hype?

Hype Software е ERP система за барове, ресторанти и кафенета. Вашата платформа се свързва с нея чрез HES, за да получава данни от каталога, да изпраща поръчки и да получава промени в статусите им.

Основни понятия

Понятие	Описание
HES	Hype Exchange Service, облачната услуга на `es.hype-software.com`, през която минава комуникацията по интеграциите
Адаптер	Модул в HES за конкретна платформа. `hype-custom` е адаптерът за произволни външни платформи
Интеграция	Настроена връзка между акаунт в Hype POS и акаунт във външна платформа
Задача	Единица работа, създадена от HES за изпълнение от платформата: създаване, промяна или извличане на обект
Pipeline	Подредена последователност от стъпки за първоначална синхронизация
Съпоставяне на стойности	Вътрешни връзки в HES между идентификаторите на обекти в двете платформи, например артикул №5 в Hype е продукт №123 във вашата платформа
Акаунт	Едната страна на интеграцията: акаунт в Hype Server или във външната платформа

2. Архитектура

Мястото на Hype Custom в HES

text

Вашата платформа -> HES: извличане на задачи за синхронизация (GET)
Вашата платформа -> HES: отчитане на резултати от задачи (PUT)
Вашата платформа -> HES: изпращане на поръчки и промени (POST/PUT webhook)
HES -> Вашата платформа: чакащи задачи, отговори на заявки, статус на интеграцията

Начини на комуникация

Адаптерът hype-custom използва два начина на комуникация:

1. Периодично извличане на задачи (HES -> вашата платформа)

Когато Hype POS изпрати данни към HES, например нов артикул, HES създава задачи за вашата платформа. Тя периодично ги извлича, обработва ги и връща резултатите.

HES предоставя промените в каталога като задачи за вашата платформа
Вашата платформа --> GET /tasks/hype-custom/items --> HES връща чакащите задачи
Вашата платформа обработва задачите: създава/променя записи
Вашата платформа --> PUT /tasks/hype-custom/items --> Отчита резултатите в HES

2. Изпращане чрез webhook (вашата платформа -> HES)

Когато вашата платформа трябва да изпрати данни към Hype, например нова онлайн поръчка, тя ги изпраща директно към webhook адресите на HES.

Вашата платформа --> POST /webhook/hype-custom/orderRequests --> HES
  HES приема заявката с 204 и я доставя асинхронно
  Проверете дали поръчката се появява в Hype; 204 не потвърждава доставянето

3. Удостоверяване

Всички API заявки изискват Bearer токен в хедъра Authorization.

Authorization: Bearer <your_api_token>

Получаване на API токен

API токен се издава при създаване на интеграция между вашата платформа и клиент на Hype POS. Свържете се с поддръжката на Hype за настройване на интеграцията. Ще получите api_token, свързан с акаунта на вашата платформа в HES.

Грешка при удостоверяване

Ако токенът липсва или е невалиден, API връща:

HTTP/1.1 401 Unauthorized

Задължителни хедъри

Всички заявки трябва да включват:

Content-Type: application/json
Accept: application/json
Authorization: Bearer <your_api_token>

4. Базови URL адреси и ограничения

Среди

Среда	Базов URL адрес
Разработка	`https://es.dev.hype-software.com`
Продукция	`https://es.hype-software.com`

Комуникацията е само по HTTPS. HTTP заявките се пренасочват с код 301 към съответния HTTPS адрес.

Ограничения на броя заявки

Ограниченията са за всеки API токен и зависят от групата адреси:

Адреси	Ограничение
`/tasks/hype-custom/` и `/webhook/hype-custom/`	1000 заявки в минута
`/api/hype-custom/*` (интеграции и задания в опашката)	60 заявки в минута

При надвишаване на ограничението API връща 429 Too Many Requests.

Хедър на отговора	Описание
`X-RateLimit-Limit`	Максимален брой заявки в минута
`X-RateLimit-Remaining`	Оставащи заявки в текущия времеви прозорец

Тези хедъри се връщат при заявки в рамките на ограничението. Отговорът 429 не съдържа Retry-After или X-RateLimit-Reset, затова изчакайте преди нов опит (прозорецът е една минута), например с експоненциално нарастващо забавяне.

5. Обработка на грешки

Грешките при удостоверяване, маршрутизиране, ограничение на заявките и неочакваните сървърни грешки връщат HTTP кода и следното JSON тяло:

json

{
  "error": 1,
  "message": "Error description text"
}

Код	Значение
`401`	Липсващ или невалиден Bearer токен
`404`	Непознат обект в `/tasks/hype-custom/{entity}`, непознат `entity_task_id` или непозната интеграция
`429`	Надвишен брой заявки
`500`	Вътрешна грешка на сървъра. Връща се и при заявка за задания в опашката на интеграция извън вашия акаунт, както и при резултат от задача без `entity_task_id`

HES не валидира телата на заявките синхронно, затова тези адреси никога не връщат 422:

Webhook адресите (/webhook/hype-custom/{entity}) приемат всяко JSON тяло с 204 No Content и го обработват асинхронно. Невалидните данни водят до грешка по-късно; проверете заданията в опашката на интеграцията.
Webhook за неподдържан обект не връща 404: POST връща 500, а останалите методи връщат 200 с {"error": "Resource can't be found"}. Проверявайте името на обекта в адреса винаги когато webhook върне код, различен от 204.
Резултат от задача без status се отчита като неуспешен.

6. Система от задачи

Задачите са основният механизъм за синхронизиране на данни от Hype POS към вашата платформа. HES създава задачи, които платформата трябва да извлече, обработи и отчете.

Как работи

HES създава задачи при промяна на обекти в Hype POS или при първоначална синхронизация
Вашата платформа извлича чакащите задачи чрез GET /tasks/hype-custom/{entity}
Вашата платформа обработва всяка задача: създава, променя или извлича записи в собствената си система
Вашата платформа връща резултатите чрез PUT /tasks/hype-custom/{entity}

Структура на задачата

Всяка задача, върната от GET заявка, има следната структура:

json

{
  "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
  "request": { ... },
  "status": 0,
  "meta": {
    "source_account": {
      "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
      "name": "Local",
      "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
      "platform_name": "Hype Server",
      "platform_key": "hype-server"
    }
  },
  "type": "POST"
}

Поле	Тип	Описание
`id`	UUID низ	Идентификатор на задачата, необходим при отчитане на резултата
`request`	object/array	Данните на обекта за обработка. При `GET` задачи съдържа настройките на интеграцията за вашия акаунт или `[]`, ако няма такива; не е нужно да ги обработвате.
`status`	integer	При извличане винаги е `0`, тоест нова и необработена задача
`meta`	object	`source_account` описва акаунта в Hype Server, от който идва промяната: `id`, `name`, `platform_id`, `platform_name`, `platform_key`
`type`	string	Операцията за изпълнение: `GET` изпраща всички записи от този тип от вашата система, `POST` създава запис, `PUT` променя запис

Значение на типовете задачи

Тип	Значение	Вашето действие
`GET`	HES иска всички записи от този тип от вашата платформа	Върнете всички записи в отговора
`POST`	В Hype е създаден нов обект	Създайте записа и го върнете с идентификатора от вашата платформа
`PUT`	В Hype е променен съществуващ обект	Променете записа и върнете обновената версия

В момента HES не изпраща DELETE задачи. Когато съпоставен запис бъде изтрит в Hype, получавате PUT задача за него с нулирани полета (празни низове или нули, например "name": ""). Проверявайте за този случай, преди да приложите PUT, и изтрийте записа, ако отразявате изтриванията.

Отчитане на резултатите от задачите

След обработката върнете резултатите с PUT заявка. Тялото е масив от резултати:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "response": { ... },
    "status": 201
  }
]

Поле	Тип	Описание
`entity_task_id`	UUID низ	Полето `id` от първоначалната задача
`response`	object/array	Резултатът от обработката. Успешните задачи, различни от `GET`, трябва да включват `id` на обекта във вашата платформа. Успешните `GET` задачи връщат масив с всички записи от съответния тип.
`status`	integer	HTTP код за резултата: `200` означава обновен запис, `201` създаден, а `4xx`/`5xx` грешка

Успешна PUT заявка връща 204 No Content.

При успешни задачи, различни от GET, върнете id от вашата платформа, когато сте създали или намерили реален обект. HES използва този id, за да съпостави обектите за последващата синхронизация.

При успешни GET задачи върнете JSON масив в response. Всеки елемент трябва да следва схемата на съответния обект и да съдържа постоянния му id във вашата платформа. При първоначалната синхронизация HES събира така статусите на поръчки, каналите за доставка и видовете плащане за ръчно съпоставяне в административния интерфейс на Hype Server след активиране. Връщайте празен масив само ако нямате записи от този тип.

Изключение за салони и маси: ако платформата ви не моделира разположението в обекта и не изисква съпоставяне на салони и маси, можете да отчетете успешните задачи за тях с празен обект в отговора:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "response": {},
    "status": 200
  }
]

Това позволява синхронизацията да продължи, но не създава връзка между идентификаторите на салона или масата. Ако използвате този вариант, не включвайте tableId при създаване на заявки за поръчки към Hype Server, защото HES няма да може да преобразува тази референция.

7. Справочник за обектите

7.1 Артикули

Артикулите са продаваните позиции от менюто на Hype POS: ястия, напитки и други.

Схема

Поле	Тип	Задължително	Описание
`id`	string/integer	Да, при PUT/отговор	Уникалният идентификатор на артикула във вашата платформа
`name`	string	Да	Име на артикула
`categoryId`	string/integer	Да	Идентификатор на съпоставената категория във вашата платформа
`price`	number	Да	Цена на артикула
`preparationTime`	integer	Не	Време за приготвяне в минути. Задачите изпращат `0`, когато в Hype няма стойност.
`barCode`	string	Не	Баркод
`modifiers`	array	Не	Списък с идентификатори на модификатори; все още не се използва
`supplements`	array	Не	Винаги е празен (`[]`) в `PUT` задачите и липсва в `POST` задачите. Използвайте самостоятелния обект `supplements`.
`quantity`	integer	Не	Винаги е `1`. Не означава наличност.
`active`	boolean	Да	Дали артикулът е активен/видим

Забележка: задачите за артикули не съдържат данни за добавки. Добавките, връзките им и референциите към тях в поръчките идват от самостоятелния обект supplements.

API адреси

Метод	URL	Описание
`GET`	`/tasks/hype-custom/items`	Извличане на чакащи задачи за артикули
`PUT`	`/tasks/hype-custom/items`	Отчитане на задачи за артикули

Пример: извличане на задачи за артикули

Заявка:

GET /tasks/hype-custom/items
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

Отговор: 200 OK

json

[
  {
    "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "request": {
      "name": "Маргарита 20",
      "categoryId": 31,
      "price": 4.33,
      "preparationTime": 20,
      "barCode": "812345679",
      "modifiers": [],
      "quantity": 1,
      "active": true
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "POST"
  },
  {
    "id": "9a101f76-f1c8-47c2-a19f-439150bb58ab",
    "request": {
      "id": "87001",
      "name": "Coca Cola",
      "categoryId": 31,
      "price": 2.5,
      "preparationTime": 0,
      "barCode": "712345689",
      "modifiers": [],
      "supplements": [],
      "quantity": 1,
      "active": true
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "PUT"
  }
]

Пример: отчитане на задачи за артикули

Заявка:

PUT /tasks/hype-custom/items
Authorization: Bearer <token>
Content-Type: application/json
Accept: application/json

Тяло:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "response": {
      "id": "87008",
      "name": "Маргарита 20",
      "categoryId": 31,
      "price": 4.33,
      "preparationTime": 20,
      "barCode": "812345679",
      "modifiers": [],
      "supplements": [],
      "quantity": 1,
      "active": true
    },
    "status": 201
  },
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-439150bb58ab",
    "response": {
      "id": "87001",
      "name": "Coca Cola",
      "categoryId": 31,
      "price": 2.5,
      "preparationTime": 0,
      "barCode": "712345689",
      "modifiers": [],
      "supplements": [],
      "quantity": 1,
      "active": true
    },
    "status": 200
  }
]

Отговор: 204 No Content

7.2 Категории

Категориите групират артикулите от менюто. Hype използва йерархия на две нива: основни категории и категории в менюто.

Схема

Поле	Тип	Задължително	Описание
`id`	string/integer	Да, при PUT/отговор	Уникален идентификатор във вашата платформа
`name`	string	Да	Име на категорията
`order`	integer	Да	Ред на подреждане

API адреси

Метод	URL	Описание
`GET`	`/tasks/hype-custom/categories`	Извличане на чакащи задачи за категории
`PUT`	`/tasks/hype-custom/categories`	Отчитане на задачи за категории

Пример: извличане на задачи за категории

Заявка:

GET /tasks/hype-custom/categories
Authorization: Bearer <token>

Отговор: 200 OK

json

[
  {
    "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "request": {
      "name": "Сандвичи",
      "order": 1
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "POST"
  },
  {
    "id": "9a101f76-f1c8-47c2-a19f-439150bb58ab",
    "request": {
      "name": "Пици",
      "order": 2
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "POST"
  },
  {
    "id": "9a101f76-f1c8-47c2-a19f-489150bb62b1",
    "request": {
      "id": 234,
      "name": "Бира",
      "order": 3
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "PUT"
  }
]

Пример: отчитане на задачи за категории

Заявка:

PUT /tasks/hype-custom/categories
Authorization: Bearer <token>

Тяло:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "response": {
      "id": "3011",
      "name": "Сандвичи",
      "order": 1
    },
    "status": 201
  },
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-439150bb58ab",
    "response": {
      "id": "135",
      "name": "Пици",
      "order": 2
    },
    "status": 201
  }
]

Отговор: 204 No Content

7.3 Добавки

Всеки запис за добавка свързва добавка с един артикул и съдържа цената ѝ за този артикул. Добавките достигат до вашата платформа чрез собствени задачи; задачите за артикули не ги съдържат. Поръчките ги посочват по id в orderDetails.items[].supplements[].

Задачи за добавки се появяват при първоначалната синхронизация и всеки път, когато добавка бъде създадена или променена в Hype.

Схема

Поле	Тип	Задължително	Описание
`id`	string/integer	Да, при PUT/отговор	Уникален идентификатор на добавката в рамките на менюто във вашата платформа
`articleId`	string/integer	Да	Идентификатор на свързания артикул във вашата платформа
`price`	number	Да	Продажна цена на добавката за този артикул
`name`	string	Не	Име на добавката. Задачите винаги го съдържат; съвпада със `supplement.name`.
`supplement`	object	Да	Вложени данни за добавката

Вложен обект: `supplement`

Поле	Тип	Описание
`name`	string	Име на добавката

API адреси

Метод	URL	Описание
`GET`	`/tasks/hype-custom/supplements`	Извличане на чакащи задачи за добавки
`PUT`	`/tasks/hype-custom/supplements`	Отчитане на задачи за добавки

Пример: извличане на задачи за добавки

Отговор: 200 OK

json

[
  {
    "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "request": {
      "articleId": "item-101",
      "price": 2.5,
      "name": "Extra cheese",
      "supplement": {
        "name": "Extra cheese"
      }
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "POST"
  }
]

Пример: отчитане на задачи за добавки

Тяло:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "response": {
      "id": "supplement-301",
      "articleId": "item-101",
      "price": 2.5,
      "supplement": {
        "name": "Extra cheese"
      }
    },
    "status": 201
  }
]

Отговор: 204 No Content

7.4 Салони

Салоните са помещения или зони в плана на обекта в Hype POS, например Main Hall, Garden или Bar Area.

Задачи за салони се появяват при първоначалната синхронизация и всеки път, когато салон бъде създаден или променен в Hype.

Схема

Поле	Тип	Задължително	Описание
`id`	string/integer	Обикновено, при PUT/отговор	Уникален идентификатор на салона във вашата платформа
`name`	string	Да	Име на салона
`width`	integer	Да	Ширина на плана
`height`	integer	Да	Височина на плана
`order`	integer	Да	Ред на подреждане

API адреси

Метод	URL	Описание
`GET`	`/tasks/hype-custom/saloons`	Извличане на чакащи задачи за салони
`PUT`	`/tasks/hype-custom/saloons`	Отчитане на задачи за салони

Пример: извличане на задачи за салони

Отговор: 200 OK

json

[
  {
    "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "request": {
      "name": "Main Hall",
      "width": 2400,
      "height": 1400,
      "order": 1
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "POST"
  }
]

Пример: отчитане на задачи за салони

Тяло:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "response": {
      "id": "saloon-11",
      "name": "Main Hall",
      "width": 2400,
      "height": 1400,
      "order": 1
    },
    "status": 201
  }
]

Отговор: 204 No Content

Ако вашата платформа не съхранява салони, можете да отчетете успешна задача за салон с status: 200 и response: {}. Това позволява синхронизацията да продължи без създаване на връзка за салона.

7.5 Маси

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

Задачи за маси се появяват при първоначалната синхронизация и всеки път, когато маса бъде създадена или променена в Hype.

Схема

Поле	Тип	Задължително	Описание
`id`	string/integer	Обикновено, при PUT/отговор	Уникален идентификатор на масата във вашата платформа
`name`	string	Да	Име на масата
`saloonId`	string/integer	Да	Идентификатор на салона във вашата платформа, вече преведен от HES, или `0`, ако сте потвърдили салона с `{}`
`x`	integer	Да	Координата X в плана на салона
`y`	integer	Да	Координата Y в плана на салона
`width`	integer	Да	Ширина на масата в плана
`height`	integer	Да	Височина на масата в плана

Забележки:

Синхронизират се само невиртуални маси.
Данните включват позиция и размери, но не включват визуални стилове или settings.
Ако вашата платформа не съхранява маси, можете да отчетете успешните задачи с status: 200 и response: {}. Синхронизацията продължава без съпоставяне на масите; в този случай не изпращайте tableId в webhook заявките за поръчки.

API адреси

Метод	URL	Описание
`GET`	`/tasks/hype-custom/tables`	Извличане на чакащи задачи за маси
`PUT`	`/tasks/hype-custom/tables`	Отчитане на задачи за маси

Пример: извличане на задачи за маси

Отговор: 200 OK

json

[
  {
    "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "request": {
      "name": "T12",
      "saloonId": "saloon-11",
      "x": 320,
      "y": 180,
      "width": 96,
      "height": 96
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "POST"
  }
]

Пример: отчитане на задачи за маси

Тяло:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "response": {
      "id": "table-88",
      "name": "T12",
      "saloonId": "saloon-11",
      "x": 320,
      "y": 180,
      "width": 96,
      "height": 96
    },
    "status": 201
  }
]

Отговор: 204 No Content

7.6 Заявки за поръчки

Заявките за поръчки са входящите поръчки от вашата платформа към Hype POS. Това е най-сложният обект и съдържа вложени данни за плащане, доставка, клиент и поръчани артикули.

Схема

Поле	Тип	Задължително	Описание
`id`	string/integer	Да	Уникален идентификатор на поръчката във вашата платформа
`tableId`	string/integer	Не	Идентификатор на масата във вашата платформа. Ако е подаден, трябва вече да е съпоставен чрез самостоятелната синхронизация на `tables`.
`discount`	number	Не	Обща сума на отстъпката
`tip`	number	Не	Брутна сума на бакшиша. Изпраща се към Hype Server като надбавка на ниво поръчка. Липсващ `tip` се приема за `0`.
`paymentTypes`	array	Да	Използвани начини на плащане, описани по-долу
`orderComment`	string	Не	Общ коментар към поръчката
`deliveryChannel`	object	Да	Данни за начина на доставка, описани по-долу. Полето `id` трябва да е съпоставено при настройката. Без `deliveryChannel` HES пак връща `204`, но не може да достави поръчката до Hype.
`status`	object	Да	Текущ статус на поръчката, описан по-долу
`clientDetails`	object	Не	Данни за клиента, описани по-долу
`orderDetails`	object	Да	Поръчани артикули, описани по-долу
`total`	number	Да	Обща сума след отстъпки, включително доставка и бакшиш
`subTotal`	number	Да	Междинна сума преди отстъпки и доставка

Вложен обект: `paymentTypes[]`

Поле	Тип	Описание
`id`	string/integer	Идентификатор на вида плащане, съпоставен при настройката на интеграцията
`name`	string	Име на вида плащане
`amount`	number	Сума, платена с този метод
`status`	string	Статус на плащането. Използвайте `"completed"` за вече получена сума и `"pending"` за избран, но неплатен метод. Hype Server третира всяка друга стойност като неплатена.

Hype Server прилага paymentTypes[].status, когато поръчката бъде прикачена към сметка на маса (приета). Дотогава, докато поръчката е нова, webhook за промяна заменя paymentTypes, така че промените в плащанията преди приемането се отразяват. Промени на статуса на плащане след прикачването се игнорират.

Вложен обект: `deliveryChannel`

Поле	Тип	Описание
`id`	string/integer	Идентификатор на канала за доставка, съпоставен при настройката на интеграцията
`name`	string	Име на канала
`deliveryPrice`	number	Такса за доставка

Вложен обект: `status`

Поле	Тип	Описание
`id`	string/integer	Идентификатор на статуса, съпоставен при настройката на интеграцията
`name`	string	Име на статуса, например „Нова“ или „Приета“

Вложен обект: `clientDetails`

Поле	Тип	Описание
`firstName`	string	Собствено име на клиента
`lastName`	string	Фамилия на клиента
`phone`	string	Телефонен номер
`city`	string	Град
`postCode`	string	Пощенски код
`address`	string	Адрес
`formatted`	string	Пълен форматиран адрес

Вложен обект: `orderDetails`

Поле	Тип	Описание
`items`	array	Масив от поръчани артикули, описан по-долу

Забележка: използвайте orderDetails.items както при създаване, така и при промяна на поръчка.

Вложен обект: `orderDetails.items[]`

Поле	Тип	Описание
`id`	string/integer	Идентификатор на артикула, съпоставен при първоначалната синхронизация на артикулите
`name`	string	Име на артикула
`modifierIds`	array	Масив с идентификатори на модификатори; все още не се поддържа
`supplements`	array	Незадължителни добавки със задължителен `id`, незадължителна единична `price` и незадължително `quantity`, по подразбиране `1`. Идентификаторите се съпоставят чрез синхронизацията на `supplements` в рамките на менюто.
`comment`	string	Коментар към артикула
`quantity`	integer	Поръчано количество
`orderPrice`	number	Единична цена към момента на поръчката

Вложен обект: `orderDetails.items[].supplements[]`

Поле	Тип	Описание
`id`	string/integer	Идентификатор на добавката във вашата платформа
`price`	number	Незадължителна единична цена на добавката за този поръчан артикул
`quantity`	integer	Незадължително количество на добавката за този артикул. Ако липсва, се приема `1`.

Забележка: supplements[].price е единична цена, а не обща сума на реда. За общата сума на добавката към артикула изчислете price * quantity.

API адреси

Адреси за задачи, чрез които получавате промени по поръчки от Hype:

Метод	URL	Описание
`GET`	`/tasks/hype-custom/orderRequests`	Извличане на чакащи задачи за поръчки
`PUT`	`/tasks/hype-custom/orderRequests`	Отчитане на задачи за поръчки

Webhook адреси за изпращане на поръчки към Hype:

Метод	URL	Описание
`POST`	`/webhook/hype-custom/orderRequests`	Създаване на нова заявка за поръчка
`PUT`	`/webhook/hype-custom/orderRequests`	Промяна на съществуваща заявка за поръчка

Пример: създаване чрез webhook за заявки за поръчки

Заявка:

POST /webhook/hype-custom/orderRequests
Authorization: Bearer <token>
Content-Type: application/json

Тяло:

json

{
  "id": 1,
  "tableId": 42,
  "discount": 3.45,
  "tip": 2.5,
  "paymentTypes": [
    {
      "id": 1,
      "name": "Stripe",
      "amount": 12.75,
      "status": "completed"
    }
  ],
  "orderComment": "Коментар към поръчката",
  "deliveryChannel": {
    "id": 1,
    "name": "За плажа",
    "deliveryPrice": 2.5
  },
  "status": {
    "id": 1,
    "name": "Нова"
  },
  "clientDetails": {
    "firstName": "Иван",
    "lastName": "Иванов",
    "phone": "+12345",
    "city": "Бургас",
    "postCode": "8000",
    "address": "кв. Възраждане, 111",
    "formatted": "Бургас, 8000, кв. Възраждане, 111"
  },
  "orderDetails": {
    "items": [
      {
        "id": 255653,
        "name": "Маргарита 20",
        "modifierIds": [],
        "supplements": [
          {
            "id": 3,
            "price": 2.0,
            "quantity": 1
          }
        ],
        "comment": "Да няма нищо зелено, като рукола зелени маслини или чушки",
        "quantity": 2,
        "orderPrice": 4.33
      }
    ]
  },
  "total": 12.75,
  "subTotal": 8.67
}

Отговор: 204 No Content

Пример: промяна чрез webhook за заявки за поръчки

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

Заявка:

PUT /webhook/hype-custom/orderRequests
Authorization: Bearer <token>
Content-Type: application/json

Тяло:

json

{
  "id": 1,
  "tableId": 42,
  "discount": 3.45,
  "tip": 2.5,
  "paymentTypes": [
    {
      "id": 1,
      "name": "Stripe",
      "amount": 12.75,
      "status": "completed"
    }
  ],
  "orderComment": "Коментар към поръчката",
  "deliveryChannel": {
    "id": 1,
    "name": "За плажа",
    "deliveryPrice": 2.5
  },
  "status": {
    "id": 2,
    "name": "Приета"
  },
  "clientDetails": {
    "firstName": "Иван",
    "lastName": "Иванов",
    "phone": "+12345",
    "city": "Бургас",
    "postCode": "8000",
    "address": "кв. Възраждане, 118",
    "formatted": "Бургас, 8000, кв. Възраждане, 118"
  },
  "orderDetails": {
    "items": [
      {
        "id": 255653,
        "name": "Маргарита 20",
        "modifierIds": [],
        "supplements": [
          {
            "id": 3,
            "price": 2.0,
            "quantity": 1
          }
        ],
        "comment": "Да няма нищо зелено, като рукола, зелени маслини или чушки",
        "quantity": 2,
        "orderPrice": 4.33
      }
    ]
  },
  "total": 12.75,
  "subTotal": 8.67
}

Отговор: 204 No Content

Забележки:

PUT /webhook/hype-custom/orderRequests приема същите полета като webhook заявката за създаване: tableId, paymentTypes, deliveryChannel, clientDetails, orderDetails.items, tip, сумите и status.
В текущия процес на Hype Server тези пълни промени се прилагат, докато заявката за поръчка е нова и още не е свързана със сметка на маса.
След свързване или приемане на поръчката в Hype обработката на PUT се основава на статуса. За последващи промени разчитайте на полето status.

Пример: извличане на задачи за поръчки от Hype

Когато Hype POS промени статуса на поръчка, например на „Приета“, HES създава задача от тип PUT за вашата платформа.

Заявка:

GET /tasks/hype-custom/orderRequests
Authorization: Bearer <token>

Отговор: 200 OK

json

[
  {
    "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "request": {
      "id": 1,
      "status": {
        "id": 2,
        "name": "Приета"
      }
    },
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "PUT"
  }
]

Забележки:

Hype обновява съпоставения status на поръчката. Други полета може да са запазени от по-рано съхранени данни; те не са актуално състояние на цялата поръчка. Примерът показва само нужните на обработчика id и status.
Използвайте външното поле status в резултата, за да отчетете обработката, например 200 при успех.

Пример: отчитане на задачи за заявки за поръчки

Заявка:

PUT /tasks/hype-custom/orderRequests
Authorization: Bearer <token>

Тяло:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "response": {
      "id": 1,
      "status": {
        "id": 2,
        "name": "Приета"
      }
    },
    "status": 200
  }
]

Отговор: 204 No Content

7.7 Канали за доставка

Каналите за доставка описват как се изпълняват поръчките, например консумация на място, вземане или доставка до плажа. Те се синхронизират само при първоначална настройка, за да може HES да съпостави идентификаторите на начините за доставка между платформите.

Тези стойности не се съпоставят автоматично. След като интеграцията стане активна, каналите за доставка, видовете плащане и статусите на поръчки трябва да се съпоставят ръчно в административния интерфейс на Hype Server.

Схема

Поле	Тип	Задължително	Описание
`id`	string/integer	Да	Идентификатор на канала за доставка във вашата платформа
`name`	string	Да	Име на канала
`deliveryPrice`	number	Не	Такса за доставка по подразбиране

API адреси

Адреси за задачи:

Метод	URL	Описание
`GET`	`/tasks/hype-custom/orderDeliveryChannels`	Извличане на чакащи задачи за канали за доставка
`PUT`	`/tasks/hype-custom/orderDeliveryChannels`	Отчитане на задачи за канали за доставка

Webhook адреси:

Метод	URL	Описание
`POST`	`/webhook/hype-custom/orderDeliveryChannels`	Създаване на канал за доставка
`PUT`	`/webhook/hype-custom/orderDeliveryChannels`	Промяна на канал за доставка

Пример: извличане на задачи за канали за доставка

Отговор: 200 OK

json

[
  {
    "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "request": [],
    "status": 0,
    "meta": {
      "source_account": {
        "id": "a0fa1fe5-feda-4753-9f23-691343e3828c",
        "name": "Local",
        "platform_id": "4d410b0e-ee37-497e-8362-478a383d68ee",
        "platform_name": "Hype Server",
        "platform_key": "hype-server"
      }
    },
    "type": "GET"
  }
]

Задача от тип GET означава, че HES иска всички канали за доставка от вашата платформа.

Пример: отчитане на задачи за канали за доставка

Тяло:

json

[
  {
    "entity_task_id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "response": [
      {
        "id": 1,
        "name": "Takeaway"
      },
      {
        "id": 2,
        "name": "Delivery"
      }
    ],
    "status": 200
  }
]

Отговор: 204 No Content

Пример: създаване чрез webhook за канали за доставка

Заявка:

POST /webhook/hype-custom/orderDeliveryChannels
Authorization: Bearer <token>
Content-Type: application/json

Тяло:

json

{
  "id": 1,
  "name": "За плажа",
  "deliveryPrice": 2.5
}

Отговор: 204 No Content

Пример: промяна чрез webhook за канали за доставка

Тяло:

json

{
  "id": 1,
  "name": "За плажа",
  "deliveryPrice": 2.2
}

Отговор: 204 No Content

7.8 Видове плащане

Видовете плащане описват как плащат клиентите, например Stripe, в брой или PayPal. Синхронизират се само при първоначална настройка за съпоставяне на идентификаторите.

Схема

Поле	Тип	Задължително	Описание
`id`	string/integer	Да	Идентификатор на вида плащане във вашата платформа
`name`	string	Да	Име на вида плащане

API адреси

Адреси за задачи:

Метод	URL	Описание
`GET`	`/tasks/hype-custom/orderPaymentTypes`	Извличане на чакащи задачи за видове плащане
`PUT`	`/tasks/hype-custom/orderPaymentTypes`	Отчитане на задачи за видове плащане

Webhook адреси:

Метод	URL	Описание
`POST`	`/webhook/hype-custom/orderPaymentTypes`	Създаване на вид плащане
`PUT`	`/webhook/hype-custom/orderPaymentTypes`	Промяна на вид плащане

Пример: създаване чрез webhook за видове плащане

Тяло:

json

{
  "id": 1,
  "name": "Stripe"
}

Отговор: 204 No Content

Пример: промяна чрез webhook за видове плащане

Тяло:

json

{
  "id": 1,
  "name": "Stripe 2"
}

Отговор: 204 No Content

7.9 Статуси на заявки за поръчки

Статусите определят жизнения цикъл на поръчката, например „Нова“, „Приета“, „Приготвя се“ и „Доставена“. Синхронизират се само при първоначална настройка за съпоставяне на идентификаторите.

Схема

Поле	Тип	Задължително	Описание
`id`	string/integer	Да	Идентификатор на статуса във вашата платформа
`name`	string	Да	Име на статуса

API адреси

Адреси за задачи:

Метод	URL	Описание
`GET`	`/tasks/hype-custom/orderRequestStatus`	Извличане на чакащи задачи за статуси
`PUT`	`/tasks/hype-custom/orderRequestStatus`	Отчитане на задачи за статуси

Webhook адреси:

Метод	URL	Описание
`POST`	`/webhook/hype-custom/orderRequestStatus`	Създаване на статус
`PUT`	`/webhook/hype-custom/orderRequestStatus`	Промяна на статус

Пример: създаване чрез webhook за статуси на заявки за поръчки

Тяло:

json

{
  "id": 1,
  "name": "Нова"
}

Отговор: 204 No Content

Пример: промяна чрез webhook за статуси на заявки за поръчки

Тяло:

json

{
  "id": 1,
  "name": "Изчакваща"
}

Отговор: 204 No Content

8. Webhook адреси

Всички webhook адреси използват еднакъв шаблон с името на обекта като параметър в пътя:

POST /webhook/hype-custom/:entity    -- Create an entity
PUT  /webhook/hype-custom/:entity    -- Update an entity

Стойност на `:entity`	Тип обект
`orderRequests`	Заявки за поръчки
`orderDeliveryChannels`	Канали за доставка
`orderPaymentTypes`	Видове плащане
`orderRequestStatus`	Статуси на заявки за поръчки

Забележки:

Всички webhook адреси връщат 204 No Content при успех
Артикули, категории, добавки, салони и маси се прехвърлят от Hype към вашата платформа чрез системата от задачи. Не ги изпращайте чрез hype-custom webhooks: webhook адресът приема данни за items, categories и supplements с 204, но HES не ги препраща към Hype
Заявките за поръчки се обменят двупосочно: вашата платформа ги изпраща чрез webhooks, а Hype връща промени чрез задачи
Канали за доставка, видове плащане и статуси се изпращат чрез webhooks основно при първоначална синхронизация

9. Управление на интеграции

Тези адреси позволяват да проверите състоянието на интеграциите си с клиенти на Hype POS.

Получаване на всички интеграции

GET /api/hype-custom/integrations
Authorization: Bearer <token>

Отговор:

json

[
  {
    "id": "9b57a2e7-48e3-4173-9bcd-11a831a6f111",
    "status": "syncing"
  }
]

Получаване на подробности за интеграция

Отговорът по подразбиране съдържа id и status. Заявете include=accountOne,pipeline за разширения пример по-долу или include=pipeline за напредъка на синхронизацията. Ако няма процес, полето pipeline се пропуска.

GET /api/hype-custom/integrations/:integrationId?include=accountOne,pipeline
Authorization: Bearer <token>

Отговор:

json

{
  "id": "9b57a2e7-48e3-4173-9bcd-11a831a6f111",
  "status": "syncing",
  "accountOne": {
    "id": "9a583928-13d9-4a0f-bb7f-c02b847a927c",
    "name": "demo.hype-software.com",
    "status": "active",
    "api_token": "9a583928-0e98-418a-940c-6650faf12163",
    "foreign_account_id": "157",
    "client_id": 157,
    "settings": [],
    "platform": {
      "id": "4d410b0e-ee37-497e-8362-478a383d68ee",
      "name": "Hype Server",
      "key": "hype-server",
      "prefix": "HS"
    }
  },
  "pipeline": {
    "id": "9b57a2e7-dd9b-428f-be5a-3173b77aebad",
    "status": "processing",
    "progress": {
      "step": 6,
      "from": 11,
      "task_id": "9b57a3a2-6cf6-4c06-9037-cea260069b6f"
    },
    "message": null
  }
}

Полета в подробностите за интеграцията

Поле	Описание
`id`	UUID на интеграцията
`status`	Текущ статус; вижте статуси на интеграцията и синхронизацията
`accountOne`	Свързаният с интеграцията акаунт в Hype Server
`accountOne.platform`	Метаданни за платформата; за тази страна винаги е Hype Server
`pipeline`	Последният процес, заявен с `include=pipeline`; полето се пропуска, ако няма такъв
`pipeline.progress.step`	Номер на текущата стъпка, започващ от 1. След като процесът е `synced`, остава на индекса на последната стъпка, тоест `from - 1`.
`pipeline.progress.from`	Общ брой стъпки; 11 при стандартна hype-custom интеграция
`pipeline.progress.task_id`	UUID на EntityTask, която се обработва в текущата стъпка
`pipeline.status`	Статус на процеса: `"pending"`, `"processing"`, `"synced"`, `"failed"`, `"stopped"`
`pipeline.message`	Съобщение при грешка; в останалите случаи е `null`

10. Управление на опашки

Заданията в опашката са вътрешни единици работа в HES, които създават задачи за синхронизация. Ако свързаните обекти още не са синхронизирани, заданията могат да завършат с грешка или да бъдат отложени.

Получаване на заданията в опашката

GET /api/hype-custom/integrations/:integrationId/queue-jobs
Authorization: Bearer <token>

Отговор:

json

[
  {
    "id": "1f6cc4e9-222f-4ee1-95fd-517e9b28dde8",
    "entity": "CategoryEntity",
    "request_method": "POST",
    "payload": {
      "id": 53,
      "name": "TEST 4",
      "color": "#674AEF",
      "order": 9007199254740991,
      "createdAt": "2024-04-15T12:15:37.013Z",
      "updatedAt": "2024-04-15T12:15:57.000Z",
      "mainCategoryId": null
    },
    "source": {
      "id": "9a583928-13d9-4a0f-bb7f-c02b847a927c",
      "name": "demo.hype-software.com"
    },
    "status": "failed",
    "error_msg": "The entity with name TEST 4, which the platform is attempting to update, has not yet been fully synchronized between the two platforms."
  },
  {
    "id": "5de7fd5e-9fb0-4e19-9c01-8763a90094a3",
    "entity": "OrderRequestStatusEntity",
    "request_method": "POST",
    "payload": {
      "id": 1,
      "translationKey": "NEW",
      "src_status": {}
    },
    "source": {
      "id": "9a583928-13d9-4a0f-bb7f-c02b847a927c",
      "name": "hype-fe.stage.scalewest.com"
    },
    "status": "pending",
    "error_msg": null
  }
]

Полета на заданието в опашката

Поле	Тип	Описание
`id`	UUID	Идентификатор на заданието
`entity`	string	Име на класа на обекта, например `"CategoryEntity"` или `"OrderRequestStatusEntity"`
`request_method`	string	HTTP метод от първоначалния webhook: `POST`, `PUT`, `DELETE`
`payload`	object	Оригиналните данни за обекта от платформата източник
`source`	object	Акаунтът източник, изпратил данните
`status`	string	`"failed"` или `"pending"`
`error_msg`	string/null	Контекст на грешката, когато статусът е `"failed"`

Честа причина за грешка

Заданията завършват с грешка, когато сочат към несинхронизирани обекти. Например заявка за поръчка може да съдържа артикул, за който още няма връзка между идентификаторите. HES спира временно опашката и опитва отново след синхронизирането на липсващия обект.

Изтриване на задания от опашката

DELETE /api/hype-custom/integrations/:integrationId/queue-jobs/:jobId
Authorization: Bearer <token>

Параметър	Задължителен	Описание
`:integrationId`	Да	UUID на интеграцията
`:jobId`	Не	UUID на конкретно задание. Ако липсва, се изтриват всички задания в опашката.

11. Статуси на интеграцията и процеса на синхронизация

Статуси на интеграцията

Статус	Описание
`inactive`	Интеграцията съществува, но синхронизацията не е започнала
`syncing`	Първоначалната синхронизация се изпълнява
`active`	Първоначалната синхронизация е завършила; преди обмен на поръчки все още е нужно ръчно съпоставяне на статуси, канали и плащания в административния интерфейс на Hype Server
`aborted`	Процесът е завършил с грешка или е прекъснат ръчно
`error`	Интеграцията е в състояние на грешка

text

Създаване на интеграция -> inactive -> syncing -> active
                                         |
                                         +-> aborted при грешка или прекъсване

След active завършете описаното по-долу ръчно съпоставяне, преди да разрешите поръчки. failed е статус на процеса; при неуспешен процес статусът на интеграцията става aborted.

Статуси на процеса на синхронизация

Статус	Описание
`pending`	Процесът е създаден, но още не е започнал
`processing`	Стъпките се изпълняват
`synced`	Всички стъпки са завършили успешно
`failed`	Стъпка е завършила с грешка и процесът е спрян
`stopped`	Процесът е спрян ръчно

12. Първоначална синхронизация

При създаване на интеграция HES изпълнява pipeline, строго подредена последователност от стъпки за синхронизиране на обектите между Hype POS и вашата платформа. Стъпките идват от конфигурациите на двата адаптера и се ограничават до типовете обекти, включени в шаблона на интеграцията.

Стъпки на процеса: общо 11

Стандартната hype-custom интеграция има 11 стъпки, изпълнявани в следния ред:

Фаза 1: събиране на данните от Hype, стъпки 1-8

HES извлича обекти от Hype. Стъпки 1-5 създават задачи за вашата платформа, а стъпки 6-8 съхраняват стойностите от Hype за ръчно съпоставяне. Стандартните настройки за статуси, канали и плащания не предвиждат автоматично създаване на записи в другата платформа.

Стъпка	Обект	Какво се случва
1	Категории	HES извлича категориите от Hype POS и създава `POST` задачи. Вие ги извличате, създавате в системата си и връщате собствените си идентификатори.
2	Салони	HES извлича салоните от Hype POS и създава `POST` задачи за вашата платформа.
3	Маси	HES извлича невиртуалните маси от Hype POS и създава `POST` задачи. Масите сочат към салоните от стъпка 2.
4	Артикули	HES извлича артикулите от менюто и създава `POST` задачи. Те сочат към категориите от стъпка 1. Задачите за артикули не съдържат данни за добавки.
5	Добавки	HES извлича добавките в рамките на менюто и създава `POST` задачи. Получените връзки се използват при посочване на добавки в поръчки.
6	Статуси на заявки за поръчки	HES съхранява статусите от Hype като варианти за ръчно съпоставяне след активиране.
7	Канали за доставка	HES съхранява каналите от Hype като варианти за ръчно съпоставяне след активиране.
8	Видове плащане	HES съхранява видовете плащане от Hype като варианти за ръчно съпоставяне след активиране.

Фаза 2: събиране на стойностите от вашата платформа, стъпки 9-11

HES заявява стойностите от вашата платформа чрез GET задачи и ги съхранява като другата страна на ръчното съпоставяне. Това не свързва стойностите автоматично и не ги създава в Hype POS.

Стъпка	Обект	Какво се случва
9	Статуси на заявки за поръчки	Отговорете на `GET` задачата за `orderRequestStatus` с масив от вашите статуси и постоянните им идентификатори. HES ги съхранява за ръчно съпоставяне.
10	Канали за доставка	Отговорете на `GET` задачата за `orderDeliveryChannels` с масив от вашите канали и постоянните им идентификатори. HES ги съхранява за ръчно съпоставяне.
11	Видове плащане	Отговорете на `GET` задачата за `orderPaymentTypes` с масив от вашите видове плащане и постоянните им идентификатори. HES ги съхранява за ръчно съпоставяне.

Защо редът е важен

Категории преди артикули, стъпки 1 и 4: артикулите сочат към категории чрез categoryId. Връзката за категорията трябва да съществува, за да може HES да преобразува тези референции.
Артикули преди добавки, стъпки 4 и 5: добавките сочат към артикули чрез articleId, затова артикулите трябва да бъдат синхронизирани първи.
Салони преди маси, стъпки 2 и 3: масите сочат към салони чрез saloonId. Връзката за салона е нужна за преобразуване на местоположението на масата.
Двете страни преди ръчно съпоставяне: стъпки 6-8 събират статусите, каналите и плащанията от Hype, а стъпки 9-11 събират вашите. И двата набора трябва да са налични, преди човек да ги свърже в административния интерфейс.

Преминаване към следваща стъпка

Процесът изпълнява една стъпка наведнъж. От гледна точка на вашата платформа:

Извличайте задачи от всеки включен /tasks/hype-custom/{entity} адрес.
Обработвайте всяка задача според type и изпращайте резултата чрез PUT /tasks/hype-custom/{entity}.
Връщайте постоянни идентификатори за записите, които създавате или съпоставяте. HES записва резултатите и създава връзките между идентификаторите.
HES преминава напред едва след завършване на цялата работа по текущата стъпка. Следете напредъка чрез GET /api/hype-custom/integrations/{id}?include=pipeline.
След завършване на всички стъпки процесът става synced, а интеграцията active. Завършете описаното по-долу ръчно съпоставяне преди изпращане на поръчки.

Процесът чака без ограничение във времето. Ако платформата ви спре да извлича задачи или да връща резултати, синхронизацията може да остане в processing. Ако нямате чакащи задачи, но напредъкът е спрял, свържете се с поддръжката на Hype с идентификатора на интеграцията и съобщението на процеса.

Вашите задължения при първоначална синхронизация

Извличайте често задачи за всички типове обекти. Процесът преминава последователно през тях: първо /tasks/hype-custom/categories, после /tasks/hype-custom/saloons, /tasks/hype-custom/tables, /tasks/hype-custom/items, /tasks/hype-custom/supplements и т.н.
Обработвайте всяка задача своевременно. Следващата стъпка започва едва след обработка на изходния отговор и успешно отчитане с PUT на всички задачи от текущата стъпка.
Включвайте id от вашата платформа, когато обектът съществува. HES използва тези идентификатори за двупосочно преобразуване при обработка на поръчки. Единственото поддържано потвърждение без обект за Hype Custom е за салони и маси, когато платформата не моделира план на обекта. Ако върнете response: {}, не посочвайте маси в последващите поръчки.
При GET задачи, стъпки 9-11, върнете всички записи от съответния тип в тялото на отговора. Те са нужни като варианти за ръчното съпоставяне след активиране.
Следете напредъка чрез GET /api/hype-custom/integrations/:id?include=pipeline: проверявайте pipeline.progress.step и pipeline.progress.from.

Ръчно съпоставяне след активиране

След като процесът стане synced, а интеграцията active, отворете интеграцията в административния интерфейс на Hype Server. Съпоставете и запазете съответстващите стойности за:

статуси на заявки за поръчки
канали за доставка
видове плащане

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

Не разрешавайте реални поръчки, преди връзките да са запазени и тестова поръчка да е достигнала Hype с върната промяна на статуса към вашата платформа. Преглеждайте съпоставянията при добавяне на нови стойности.

Грешки и възстановяване на синхронизацията

Няма отмяна на предишните промени. При грешка вече синхронизираните обекти остават. Процесът просто спира.

При грешка:

Неуспешната EntityTask се маркира като ERROR със съобщението за грешка
Процесът става failed, а полето message съдържа грешката
Интеграцията става aborted

Пауза при липсващи зависимости: при текуща синхронизация след първоначалния процес, ако задание срещне несъпоставена референция, например поръчка с още несинхронизиран артикул, опашката на интеграцията спира за 60 секунди и опитва отново. Така се обработват случаи, при които свързани обекти пристигат в разменен ред.

Възстановяване от поддръжката на Hype:

Повторно стартиране на целия процес на синхронизация

13. Текуща синхронизация

Започнете нормален обмен на поръчки след завършване на първоначалната синхронизация, статус active, запазено ръчно съпоставяне в административния интерфейс на Hype Server и успешна проверка на целия път на поръчката.

Hype -> вашата платформа: промени по обекти

text

1. Промяна в каталога става достъпна чрез HES като задача от тип PUT.
2. Вашата платформа извлича: GET /tasks/hype-custom/items.
3. Прилага промяната и запазва съществуващия идентификатор на записа.
4. Отчита резултата: PUT /tasks/hype-custom/items (status: 200).

Вашата платформа -> Hype: нова поръчка

text

1. Клиент прави поръчка във вашата платформа.
2. Изпратете POST /webhook/hype-custom/orderRequests със съпоставени ID.
3. HES връща 204 и доставя поръчката асинхронно.
4. Проверете дали поръчката се появява в Hype.
5. Извличайте GET /tasks/hype-custom/orderRequests за промени на статуса.
6. Прилагайте всяка промяна във вашата платформа.
7. Отчитайте резултата чрез PUT /tasks/hype-custom/orderRequests.

14. Кратък справочник

Всички API адреси

#	Метод	URL	Описание
1	`GET`	`/tasks/hype-custom/items`	Извличане на чакащи задачи за артикули
2	`PUT`	`/tasks/hype-custom/items`	Отчитане на задачи за артикули
3	`GET`	`/tasks/hype-custom/categories`	Извличане на чакащи задачи за категории
4	`PUT`	`/tasks/hype-custom/categories`	Отчитане на задачи за категории
5	`GET`	`/tasks/hype-custom/supplements`	Извличане на чакащи задачи за добавки
6	`PUT`	`/tasks/hype-custom/supplements`	Отчитане на задачи за добавки
7	`GET`	`/tasks/hype-custom/saloons`	Извличане на чакащи задачи за салони
8	`PUT`	`/tasks/hype-custom/saloons`	Отчитане на задачи за салони
9	`GET`	`/tasks/hype-custom/tables`	Извличане на чакащи задачи за маси
10	`PUT`	`/tasks/hype-custom/tables`	Отчитане на задачи за маси
11	`GET`	`/tasks/hype-custom/orderRequests`	Извличане на чакащи задачи за поръчки
12	`PUT`	`/tasks/hype-custom/orderRequests`	Отчитане на задачи за поръчки
13	`GET`	`/tasks/hype-custom/orderDeliveryChannels`	Извличане на чакащи задачи за канали за доставка
14	`PUT`	`/tasks/hype-custom/orderDeliveryChannels`	Отчитане на задачи за канали за доставка
15	`GET`	`/tasks/hype-custom/orderPaymentTypes`	Извличане на чакащи задачи за видове плащане
16	`PUT`	`/tasks/hype-custom/orderPaymentTypes`	Отчитане на задачи за видове плащане
17	`GET`	`/tasks/hype-custom/orderRequestStatus`	Извличане на чакащи задачи за статуси на поръчки
18	`PUT`	`/tasks/hype-custom/orderRequestStatus`	Отчитане на задачи за статуси на поръчки
19	`POST`	`/webhook/hype-custom/orderRequests`	Създаване на заявка за поръчка
20	`PUT`	`/webhook/hype-custom/orderRequests`	Промяна на заявка за поръчка
21	`POST`	`/webhook/hype-custom/orderDeliveryChannels`	Създаване на канал за доставка
22	`PUT`	`/webhook/hype-custom/orderDeliveryChannels`	Промяна на канал за доставка
23	`POST`	`/webhook/hype-custom/orderPaymentTypes`	Създаване на вид плащане
24	`PUT`	`/webhook/hype-custom/orderPaymentTypes`	Промяна на вид плащане
25	`POST`	`/webhook/hype-custom/orderRequestStatus`	Създаване на статус на поръчка
26	`PUT`	`/webhook/hype-custom/orderRequestStatus`	Промяна на статус на поръчка
27	`GET`	`/api/hype-custom/integrations`	Списък с всички интеграции
28	`GET`	`/api/hype-custom/integrations/:id`	Подробности за интеграция
29	`GET`	`/api/hype-custom/integrations/:id/queue-jobs`	Списък със задания в опашката
30	`DELETE`	`/api/hype-custom/integrations/:id/queue-jobs/:jobId`	Изтриване на задания от опашката

Обобщение на типовете обекти

Обект	Посока	Сегмент в адреса за задачи	Сегмент в webhook адреса
Артикули	Hype -> външната платформа	`items`	--
Категории	Hype -> външната платформа	`categories`	--
Добавки	Hype -> външната платформа	`supplements`	--
Салони	Hype -> външната платформа	`saloons`	--
Маси	Hype -> външната платформа	`tables`	--
Заявки за поръчки	Двупосочно	`orderRequests`	`orderRequests`
Канали за доставка	Двупосочно при първоначална синхронизация	`orderDeliveryChannels`	`orderDeliveryChannels`
Видове плащане	Двупосочно при първоначална синхронизация	`orderPaymentTypes`	`orderPaymentTypes`
Статуси на поръчки	Двупосочно при първоначална синхронизация	`orderRequestStatus`	`orderRequestStatus`

Документът се поддържа в хранилището на Hype Exchange Service и е справочник за клиенти, които разработват интеграция с адаптера hype-custom.

Интеграция с Hype Custom: справочник за API ​

Съдържание ​

1. Общ преглед ​

Какво е Hype? ​

Основни понятия ​

2. Архитектура ​

Мястото на Hype Custom в HES ​

Начини на комуникация ​

3. Удостоверяване ​

Получаване на API токен ​

Грешка при удостоверяване ​

Задължителни хедъри ​

4. Базови URL адреси и ограничения ​

Среди ​

Ограничения на броя заявки ​

5. Обработка на грешки ​

6. Система от задачи ​

Как работи ​

Структура на задачата ​

Значение на типовете задачи ​

Отчитане на резултатите от задачите ​

7. Справочник за обектите ​

7.1 Артикули ​

Схема ​

API адреси ​

Пример: извличане на задачи за артикули ​

Пример: отчитане на задачи за артикули ​

7.2 Категории ​

Схема ​

API адреси ​

Пример: извличане на задачи за категории ​

Пример: отчитане на задачи за категории ​

7.3 Добавки ​

Схема ​

Вложен обект: supplement ​

API адреси ​

Пример: извличане на задачи за добавки ​

Пример: отчитане на задачи за добавки ​

7.4 Салони ​

Схема ​

API адреси ​

Пример: извличане на задачи за салони ​

Пример: отчитане на задачи за салони ​

7.5 Маси ​

Схема ​

API адреси ​

Пример: извличане на задачи за маси ​

Пример: отчитане на задачи за маси ​

7.6 Заявки за поръчки ​

Схема ​

Вложен обект: paymentTypes[] ​

Вложен обект: deliveryChannel ​

Вложен обект: status ​

Вложен обект: clientDetails ​

Вложен обект: orderDetails ​

Вложен обект: orderDetails.items[] ​

Вложен обект: orderDetails.items[].supplements[] ​

API адреси ​

Пример: създаване чрез webhook за заявки за поръчки ​

Пример: промяна чрез webhook за заявки за поръчки ​

Пример: извличане на задачи за поръчки от Hype ​

Пример: отчитане на задачи за заявки за поръчки ​

7.7 Канали за доставка ​

Схема ​

API адреси ​

Пример: извличане на задачи за канали за доставка ​

Пример: отчитане на задачи за канали за доставка ​

Пример: създаване чрез webhook за канали за доставка ​

Пример: промяна чрез webhook за канали за доставка ​

7.8 Видове плащане ​

Схема ​

API адреси ​

Пример: създаване чрез webhook за видове плащане ​

Пример: промяна чрез webhook за видове плащане ​

7.9 Статуси на заявки за поръчки ​

Схема ​

API адреси ​

Пример: създаване чрез webhook за статуси на заявки за поръчки ​

Пример: промяна чрез webhook за статуси на заявки за поръчки ​

8. Webhook адреси ​

Интеграция с Hype Custom: справочник за API

Съдържание

1. Общ преглед

Какво е Hype?

Основни понятия

2. Архитектура

Мястото на Hype Custom в HES

Начини на комуникация

3. Удостоверяване

Получаване на API токен

Грешка при удостоверяване

Задължителни хедъри

4. Базови URL адреси и ограничения

Среди

Ограничения на броя заявки

5. Обработка на грешки

6. Система от задачи

Как работи

Структура на задачата

Значение на типовете задачи

Отчитане на резултатите от задачите

7. Справочник за обектите

7.1 Артикули

Схема

API адреси

Пример: извличане на задачи за артикули

Пример: отчитане на задачи за артикули

7.2 Категории

Схема

API адреси

Пример: извличане на задачи за категории

Пример: отчитане на задачи за категории

7.3 Добавки

Схема

Вложен обект: `supplement`

API адреси

Пример: извличане на задачи за добавки

Пример: отчитане на задачи за добавки

7.4 Салони

Схема

API адреси

Пример: извличане на задачи за салони

Пример: отчитане на задачи за салони

7.5 Маси

Схема

API адреси

Пример: извличане на задачи за маси

Пример: отчитане на задачи за маси

7.6 Заявки за поръчки

Схема

Вложен обект: `paymentTypes[]`

Вложен обект: `deliveryChannel`

Вложен обект: `status`

Вложен обект: `clientDetails`

Вложен обект: `orderDetails`

Вложен обект: `orderDetails.items[]`

Вложен обект: `orderDetails.items[].supplements[]`

API адреси

Пример: създаване чрез webhook за заявки за поръчки

Пример: промяна чрез webhook за заявки за поръчки

Пример: извличане на задачи за поръчки от Hype

Пример: отчитане на задачи за заявки за поръчки

7.7 Канали за доставка

Схема

API адреси

Пример: извличане на задачи за канали за доставка

Пример: отчитане на задачи за канали за доставка

Пример: създаване чрез webhook за канали за доставка

Пример: промяна чрез webhook за канали за доставка

7.8 Видове плащане

Схема

API адреси

Пример: създаване чрез webhook за видове плащане

Пример: промяна чрез webhook за видове плащане

7.9 Статуси на заявки за поръчки

Схема

API адреси

Пример: създаване чрез webhook за статуси на заявки за поръчки

Пример: промяна чрез webhook за статуси на заявки за поръчки

8. Webhook адреси