Интеграция от настройката до пускането в работа

Интеграцията свързва акаунт в Hype Server с акаунт във вашата платформа чрез Hype Exchange Service (HES). HES координира работата и преобразува идентификаторите между двете системи.

Тип интеграция	Какво позволява	Какво е необходимо преди употреба
hype-custom	Hype изпраща промени по каталога; вашата платформа подава поръчки и получава промени на статусите им.	Първоначална синхронизация, ръчно съпоставяне в административния интерфейс на Hype Server и проверка на целия път на поръчката.
hype-reports	Hype изпраща справочни данни; вашият клиент заявява справки и получава резултатите им.	Първоначална синхронизация с използваеми връзки между идентификаторите и проверка на целия процес за справка.

Последователността при настройване е:

1. Настройте интеграцията и получете данните за достъп.
2. Поддържайте обработката на задачи във вашия клиент през цялата първоначална синхронизация.
3. Изчакайте процесът да стане synced, а интеграцията active.
4. За hype-custom завършете ръчното съпоставяне в Hype Server.
5. Проверете целия процес за поръчка или справка и разрешете нормална работа.

Статус active не означава готовност за поръчки при custom интеграция

active означава, че първоначалната синхронизация е завършила. Той не удостоверява, че човек е съпоставил статусите на поръчки, каналите за доставка и видовете плащане. Тези връзки трябва да се запазят след активиране и преди изпращане на поръчки.

1. Настройте връзката

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

Получете идентификатора на интеграцията, Bearer токена на акаунта и URL адреса на средата. Съхранявайте данните за правилния акаунт и среда; вижте удостоверяване и среди.

Подгответе обработчика си на задачи преди стартиране на синхронизацията. Създаването на интеграция стартира първоначалната синхронизация; ако клиентът ви не обработва задачи, процесът чака. Уговорете настройката на връзката с поддръжката на Hype.

2. Какво означава една стъпка на синхронизация

Процесът, наричан pipeline, е подреден списък от типове обекти за извличане. Една стъпка може да създаде много задачи, затова „стъпка 4“ не означава „четвъртия запис“. Включените в шаблона типове обекти определят конкретните стъпки и общия им брой.

При всяка стъпка:

1. HES събира записите, нужни за текущия тип обект.
2. Когато HES изисква вашите записи, клиентът ви получава задача с type, равен на GET; върнете масив от записи с постоянни идентификатори.
3. Когато записи от Hype трябва да се приложат във вашата система, клиентът ви получава задачи за създаване или промяна; обработете всяка задача и върнете идентификатора на съответния ваш запис.
4. HES използва резултатите, за да свърже записите между системите.
5. Следващата стъпка започва едва след успешно завършване на цялата работа по текущата. Продължете да извличате задачи и да отчитате резултати по време на синхронизацията.

Вашият обработчик използва GET /tasks/{platform}/{entity} за получаване на работа и PUT /tasks/{platform}/{entity} за отчитане на резултати, като {platform} е hype-custom или hype-reports. Полето type на задачата описва исканата операция; то е отделно от HTTP метода за извличане или отчитане.

Тип задача	Действие на обработчика	Успешен response
GET	Връща съществуващите ви записи от съответния тип.	Масив от записи с постоянни идентификатори.
POST / PUT	Създава, намира или променя запис във вашата система. За същия запис използвайте съществуващия идентификатор.	Един обект с получения id от вашата платформа.

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

За всяка задача върнете entity_task_id, резултата от обработката в status и response. HTTP 204 от адреса за отчитане означава, че резултатът е приет; не означава завършване на целия процес. Продължете да извличате задачи за всички включени типове обекти и направете обработчиците безопасни за повторно изпълнение.

Какво означават статусите

Статус на интеграцията	Значение и следващо действие
inactive	Интеграцията не работи. Може да е новосъздадена или изключена.
syncing	Първоначалната синхронизация е в ход. Поддържайте обработката на задачи във вашия клиент активна.
active	Първоначалният процес е завършил. Изпълнете описаните по-долу стъпки за конкретния тип интеграция.
aborted	Синхронизацията е завършила с грешка или е спряна. Проверете съобщението на процеса и отстранете причината с поддръжката на Hype преди продължаване или повторно стартиране.
error	Грешка в интеграцията изисква проверка.

Използвайте GET /api/hype-custom/integrations/{id}?include=pipeline или GET /api/hype-reports/integrations/{id}?include=pipeline според типа интеграция. Когато има процес на синхронизация, отговорът включва pipeline.status, pipeline.progress.step, pipeline.progress.from, pipeline.progress.task_id и pipeline.message.

Статусите на процеса са pending, processing, synced, failed и stopped. Процесът може да чака неотчетена задача без ограничение. Ако стъпка завърши с грешка, предишната завършена работа остава; повторното стартиране не я отменя.

3. Първоначално настройване на Hype Custom

Стандартната custom конфигурация има следните 11 стъпки. Интеграция с по-ограничен шаблон може да има по-малко.

Стъпка	Източник и обект	Какво постига стъпката
1	Hype: категории	Създава или намира категориите във вашата платформа и свързва идентификаторите им. Артикулите зависят от тези връзки.
2	Hype: салони	Синхронизира зоните на обекта преди масите им.
3	Hype: маси	Синхронизира масите със съпоставените референции към салони.
4	Hype: артикули	Синхронизира каталога, включително връзките към категории и цените за конкретното меню.
5	Hype: добавки	Синхронизира добавките чрез връзките за артикули от стъпка 4.
6	Hype: статуси на поръчки	Съхранява наличните статуси от Hype за последващо ръчно съпоставяне.
7	Hype: канали за доставка	Съхранява наличните канали от Hype за последващо ръчно съпоставяне.
8	Hype: видове плащане	Съхранява наличните видове плащане от Hype за последващо ръчно съпоставяне.
9	Вашата платформа: статуси на поръчки	Отговорете на GET задача за orderRequestStatus с вашите статуси и идентификатори.
10	Вашата платформа: канали за доставка	Отговорете на GET задача за orderDeliveryChannels с вашите канали и идентификатори.
11	Вашата платформа: видове плащане	Отговорете на GET задача за orderPaymentTypes с вашите видове плащане и идентификатори.

Стъпки 6-11 събират възможните стойности от двете системи. Те не определят автоматично кой статус, канал или вид плащане има същото значение в другата система. Еднаквите имена не създават връзка между идентификаторите.

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

След active: съпоставете стойностите в Hype Server

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

Стойности за съпоставяне	Защо са нужни на поръчките
Статуси на заявки за поръчки	Преобразуват жизнения цикъл на вашата поръчка в статуси на Hype и връщат промените обратно.
Канали за доставка	Свързват вашите варианти за доставка или вземане със съответните канали в Hype.
Видове плащане	Свързват вашите начини на плащане със съответните видове в Hype.

Съпоставете съответстващите стойности и запазете връзките. Обхванете всяка стойност, която интеграцията ще изпраща или получава. Например вашият идентификатор за плащане card-online и идентификаторът за картово плащане в Hype са различни, дори и двата да се показват като „Карта“.

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

Проверете поръчка преди пускане в работа

1. Потвърдете active/synced и запазените ръчни връзки.
2. Изпратете тестова поръчка чрез POST /webhook/hype-custom/orderRequests със съпоставени артикули, добавки, статуси, канали и плащания. Включвайте маса само ако е съпоставена.
3. HES приема webhook заявката с 204, преобразува идентификаторите и поставя доставката към Hype Server в опашка. Проверете дали поръчката действително се появява в Hype; самото приемане на webhook не е достатъчно.
4. Променете статуса на поръчката в Hype. Извлечете задачата от /tasks/hype-custom/orderRequests, приложете върнатата промяна и я отчетете.
5. Разрешете реални поръчки след успешен двупосочен тест. Продължете да обработвате задачи за каталога и статусите и преглеждайте ръчните връзки при нови стойности.

Вижте ръководството за custom разработчици за реализация на обработчика и custom API справочника за форматите на данните.

4. Първоначално настройване на Hype Reports

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

При всички включени текущи типове за Reports процесът има две фази:

Фаза	Ред на стъпките	Какво прави Reports клиентът
Hype предоставя справочни данни, стъпки 1-7	Категории → салони → маси → менюта → потребители → фискални устройства → основни категории	Извлича задачи от /tasks/hype-reports/{entity}, обработва създаването/промяната и връща съответните Reports идентификатори. Тези отговори създават връзките.
Reports предоставя своите записи, стъпки 8-14	Категории → фискални устройства → основни категории → менюта → салони → маси → потребители	Отговаря на GET задачите с масиви от свои записи или [] за тип, който не съхранява. HES записва стойностите от тази страна.

Всяка стъпка внася различен набор справочни записи в HES:

Обект	Значение
Категории	Идентификатори и имена на категории артикули. Съпоставените идентификатори могат да се използват в revenue-by-category.
Салони	Зони в обекта. Идентификаторите им се използват за връзките на масите и поддържаните филтри за справки.
Маси	Масите в тези зони, включително връзката на всяка маса към салона.
Менюта	Менюта с датите и признаците за активно/основно меню. Съпоставените идентификатори могат да се използват в revenue-by-menu.
Потребители	Записи за персонал/оператори. Съпоставените идентификатори могат да се използват в справки с филтър по потребител.
Фискални устройства	Идентификатори, имена и признаци за активност на фискалните устройства. Съпоставените идентификатори могат да се използват в revenue-by-fiscal-device.
Основни категории	Идентификатори и имена на основните категории. Съпоставените идентификатори могат да се използват в revenue-by-main-category.

Имената на обектите в адресите са categories, saloons, tables, menus, users, fiscalDevices и mainCategories. Общият брой стъпки зависи от шаблона на интеграцията. Салоните са преди масите, защото масата сочи към своя салон.

След завършване интеграцията става active. Reports връзките се създават чрез резултатите от задачите; ръчното съпоставяне на статуси, канали и плащания за custom интеграции не се прилага. Преди справка проверете дали нужните обекти имат използваеми връзки между идентификаторите. Отчитане на обект без идентификатор може да позволи завършване на синхронизацията без такава връзка. Правете това само за салони и маси: ако категория, меню, потребител, фискално устройство или основна категория е отчетена без идентификатор, следващата промяна на този запис в Hype спира синхронизацията на цялата интеграция, докато връзката не бъде оправена.

Проверете справка преди пускане в работа

1. Заявете малка справка чрез POST /api/v1/integrations/{integration_id}/reports/{report}. Изпратете поддържаните филтри със съпоставените Reports идентификатори.
2. HES връща 202, jobId и pollUrl и управлява генерирането асинхронно.
3. Проверявайте върнатия pollUrl, докато статусът стане COMPLETED, FAILED или CANCELLED. Клиентът ви чете тези статуси; HES ги променя с напредването на обработката.
4. При COMPLETED прочетете data и проверете периода, филтрирането и идентификаторите. Обработвайте грешка или отмяна, вместо да проверявате безкрайно. Продължете да обработвате задачи за справочните данни при промени в тях.

Не тествайте филтър с несъпоставени идентификатори: HES ги премахва и ако не останат стойности, не се прилага филтър за този тип обект. Първо проверете съпоставянето, за да не обхване справката повече записи от предвиденото.

Вижте ръководството за Reports разработчици за данни на обектите, типове справки, ограничения и примери за заявки и отговори.