Ръководство за разработчици: интеграция с Hype Custom

Справочник: hype-custom-integration.mdДокументация в Postman: https://documenter.getpostman.com/view/52109283/2sBXc8oNnL

1. Цел

Ръководството обяснява как да изградите интеграция, готова за реална работа с адаптера Hype Custom в Hype Exchange Service (HES).

Използвайте този документ за:

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

Използвайте отделния API справочник за:

точните схеми на обектите
пълни примери за данни
примери за заявки и отговори за всеки API адрес

2. Общ модел

HES е посредник между акаунт в Hype POS и акаунт във вашата платформа.

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

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

За това интеграцията ви трябва да реализира:

обработчик на задачи
клиент за изпращане на webhooks

Доставката до Hype е асинхронна. Успешният webhook отговор означава, че HES е приел заявката ви. Проверете дали поръчката се появява в Hype и продължете да извличате вашите orderRequests задачи за промени на статуса.

3. Източници и посоки на данните

Обработвайте обектите според следните правила:

Обект	Основна посока	Забележки
Категории	Hype -> вашата платформа	Нужни преди синхронизацията на артикули за съпоставяне на `categoryId`
Салони	Hype -> вашата платформа	Нужни преди синхронизацията на маси
Маси	Hype -> вашата платформа	`saloonId` трябва вече да е съпоставен
Артикули	Hype -> вашата платформа	Нужни преди добавките и референциите в поръчки
Добавки	Hype -> вашата платформа	В рамките на менюто и зависими от артикулите
Заявки за поръчки	Двупосочно	Създавате/променяте чрез webhook; Hype връща промени на статус чрез задачи
Канали за доставка	При първоначалната синхронизация	За съпоставяне на идентификатори
Видове плащане	При първоначалната синхронизация	За съпоставяне на идентификатори
Статуси на заявки за поръчки	При първоначалната синхронизация	За съпоставяне на идентификатори

При ежедневна работа:

структурата на менюто и планът на обекта се управляват от Hype
създаването на поръчки се управлява от външната платформа
промените на статуса на поръчките се връщат от Hype чрез задачи за orderRequests

4. Основни изисквания

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

Всички заявки изискват:

http

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

Среди

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

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

1000 заявки в минута за всеки токен за /tasks/hype-custom/* и /webhook/hype-custom/*
60 заявки в минута за всеки токен за /api/hype-custom/* (интеграции и задания в опашката)
при 429 изчакайте и опитайте отново по-късно; отговорът няма хедър Retry-After, затова използвайте собствено забавяне

5. Какво трябва да реализира вашата платформа

Надеждната интеграция изисква поне:

Процес за периодично извличане на задачи от /tasks/hype-custom/*
Обработчици за всеки тип обект и операции POST, PUT и GET
Изпращане на групирани резултати към PUT /tasks/hype-custom/{entity}
Webhook клиент за POST и PUT /webhook/hype-custom/orderRequests
Съхраняване на собствените идентификатори и достатъчно състояние за безопасно повторно изпълнение
Наблюдение на статуса на интеграцията и грешките в опашката

Препоръчително поведение:

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

6. Справочник за API адресите

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

Използвайте ги за получаване на работа от HES:

text

GET /tasks/hype-custom/{entity}
PUT /tasks/hype-custom/{entity}

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

categories
saloons
tables
items
supplements
orderRequests
orderDeliveryChannels
orderPaymentTypes
orderRequestStatus

Webhook адреси

Използвайте ги за изпращане на данни към HES:

text

POST /webhook/hype-custom/{entity}
PUT  /webhook/hype-custom/{entity}

Поддържани публични webhook обекти:

orderRequests
orderDeliveryChannels
orderPaymentTypes
orderRequestStatus

Адреси за наблюдение и поддръжка

Използвайте ги за проверка на състоянието и инструменти за поддръжка:

text

GET    /api/hype-custom/integrations
GET    /api/hype-custom/integrations/{integrationId}
GET    /api/hype-custom/integrations/{integrationId}/queue-jobs
DELETE /api/hype-custom/integrations/{integrationId}/queue-jobs/{jobId?}

7. Реализиране на обработчика на задачи

Правила за извличане на задачи

За всеки тип обект GET /tasks/hype-custom/{entity} връща масив от чакащи задачи:

json

[
  {
    "id": "9a101f76-f1c8-47c2-a19f-259150bb62e0",
    "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 е идентификаторът на HES задачата, който трябва да върнете като entity_task_id
type определя операцията за изпълнение във вашата система
status винаги е 0 при извличане на задачата
празният масив означава, че няма работа; това не е грешка

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

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

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

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

Върнете резултатите чрез:

text

PUT /tasks/hype-custom/{entity}

Тяло на заявката:

json

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

Задължително поведение:

винаги изпращайте вътрешното поле status
ако пропуснете status, HES в момента го приема за 500
при успешна задача, различна от GET, върнете response, различен от null, с id на обекта, когато сте създали или намерили реален запис
при успешна GET задача върнете в response масив с вашите записи от този тип; всеки запис трябва да има постоянен id
статус 2xx без използваем response може да остави HES без идентификатори за автоматично свързване или без стойности за ръчно съпоставяне
изключение: задачи за салони/маси могат да се отчетат с response: {}, когато платформата не моделира план на обекта; синхронизацията продължава без връзки за тях
можете да изпратите резултати за няколко задачи в една заявка
HTTP отговорът от HES е 204 No Content; реалният резултат от вашата обработка се предава в status на всеки елемент

Примерна структура на обработчика

async function syncEntity(entity: string) {
  const tasks = await hes.get(`/tasks/hype-custom/${entity}`)
  if (tasks.length === 0) return

  const results = []

  for (const task of tasks) {
    try {
      const response = await processTask(task)

      results.push({
        entity_task_id: task.id,
        status: response.created ? 201 : 200,
        response: response.payload,
      })
    } catch (error) {
      results.push({
        entity_task_id: task.id,
        status: 422,
        response: { message: String(error) },
      })
    }
  }

  await hes.put(`/tasks/hype-custom/${entity}`, results)
}

Стратегия за извличане

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

След активиране на интеграцията продължете да извличате поне:

categories
saloons
tables
items
supplements
orderRequests

Задачи за типовете за първоначална настройка се появяват само при първоначалната синхронизация, защото Hype не изпраща промени по каналите за доставка, видовете плащане и статусите на поръчки:

orderDeliveryChannels
orderPaymentTypes
orderRequestStatus

8. Реализиране на webhook клиента

Основен webhook за ежедневна работа

Основните webhook операции при нормална работа са:

text

POST /webhook/hype-custom/orderRequests
PUT  /webhook/hype-custom/orderRequests

Използвайте ги, когато:

клиент направи нова поръчка във вашата платформа
трябва да промените поръчка, която още подлежи на редакция в Hype
трябва да изпратите по-късна промяна на статуса на поръчка

Забележка за обработката:

успешна webhook заявка връща 204 No Content, когато HES приеме данните, а не когато Hype POS вече ги е приложил
за потвърждение от получателя следете състоянието на интеграцията, заданията в опашката или последващите задачи за orderRequests, върнати от Hype

Важни правила за заявки за поръчки

не изпращайте поръчки, преди интеграцията да е синхронизирана и нужните съпоставяния да съществуват
tableId е незадължителен, но ако присъства, трябва вече да е съпоставен чрез самостоятелната синхронизация на маси
id на артикулите трябва да сочат към вече синхронизирани артикули
id на добавките трябва да сочат към вече синхронизирани добавки
tip е незадължителна брутна сума, по подразбиране 0; включете я в total и в платената paymentTypes[].amount
paymentTypes[].status трябва да е completed или pending; Hype Server третира другите стойности като неплатени
статусите на плащане се прилагат, когато Hype прикачи (приеме) поръчката; дотогава webhook за промяна заменя paymentTypes, а промени на статуса на плащане след приемането се игнорират
след приемане/свързване на поръчката в Hype последващите промени се основават на статуса; не разчитайте на късна промяна на всички данни

Webhooks за първоначална настройка

Тези адреси са предназначени основно за първоначална настройка:

POST / PUT /webhook/hype-custom/orderDeliveryChannels
POST / PUT /webhook/hype-custom/orderPaymentTypes
POST / PUT /webhook/hype-custom/orderRequestStatus

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

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

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

Ред на стъпките

Стъпка	Обект	Цел
1	Категории	Hype -> вашата платформа
2	Салони	Hype -> вашата платформа
3	Маси	Hype -> вашата платформа
4	Артикули	Hype -> вашата платформа
5	Добавки	Hype -> вашата платформа
6	Статуси на заявки за поръчки	Събиране на стойности от Hype за ръчно съпоставяне
7	Канали за доставка	Събиране на стойности от Hype за ръчно съпоставяне
8	Видове плащане	Събиране на стойности от Hype за ръчно съпоставяне
9	Статуси на заявки за поръчки	Събиране на вашите стойности чрез `GET` задача за ръчно съпоставяне
10	Канали за доставка	Събиране на вашите стойности чрез `GET` задача за ръчно съпоставяне
11	Видове плащане	Събиране на вашите стойности чрез `GET` задача за ръчно съпоставяне

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

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

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

Какво да очаквате от процеса

изпълнява се една стъпка наведнъж и тя блокира следващата
една стъпка може да създаде много задачи; всички трябва да завършат преди следващата стъпка
няма краен срок за стъпката; тя чака извличане и отчитане без ограничение
ако спрете извличането на задачи, интеграцията остава в syncing
при грешка вече създадените връзки остават; няма връщане назад

Условия за пускане в работа

Приемайте интеграцията за готова за поръчки само когато:

GET /api/hype-custom/integrations/{id}?include=pipeline показва active
статусът на процеса е synced или няма останал активен процес
вашата страна е завършила първоначалните GET задачи за статуси, канали и плащания
след активиране някой е отворил интеграцията в административния интерфейс на Hype Server, съпоставил е статусите, каналите за доставка и видовете плащане и е запазил връзките
тестова поръчка достига Hype и промяната на статуса ѝ се връща към вашата платформа

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

10. Съпоставяния и зависимости

Съпоставянето на идентификатори е основното изискване

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

Затова:

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

Допълнителни правила за зависимостите

tableId е незадължителен, но ако го изпратите, трябва вече да е съпоставен
ако платформата не използва салони/маси, отчетете задачите с response: {} и пропускайте tableId във всички webhooks за поръчки
връзките за добавките идват само от самостоятелната синхронизация на supplements; задачите за артикули не съдържат данни за добавки
Hype обновява съпоставения статус в задачите orderRequests. Други върнати полета може да са запазени от по-рано съхранени данни; обработвайте тези задачи като известия за статус.

11. Обработка и диагностика на грешки

Чести HTTP грешки

Статус	Значение
`401`	Липсващ или невалиден Bearer токен
`404`	Грешен адрес, непознат обект в задачите или непознат `entity_task_id`
`429`	Надвишен брой заявки
`500`	Вътрешна грешка в HES; също заявка за задания в опашката на интеграция извън вашия акаунт или webhook `POST` за неподдържан обект

HES никога не връща 422 за задачи или webhooks. Webhooks приемат всяко JSON тяло с 204 и грешките се появяват по-късно при асинхронната обработка; проверете заданията в опашката. Webhook PUT за неподдържан обект връща 200 с {"error": "Resource can't be found"}, затова третирайте всеки отговор на webhook, различен от 204, като неуспех.

Чести проблеми с интеграцията

Симптом	Вероятна причина	Какво да проверите
Webhook заявката е приета, но поръчката още не се вижда в Hype	Доставката още чака или е завършила с грешка	Проверете статуса на интеграцията и грешките в опашката; свържете се с поддръжката на Hype, ако доставката остава блокирана
Опашката показва грешка за липсващ свързан обект	Референцията още не е съпоставена	Проверете артикули, маси, добавки, статуси, плащания и канали за доставка
Масите не се синхронизират	Липсва връзка за салона	Проверете дали салоните са завършили първи
Добавките не се синхронизират	Липсва връзка за артикула	Проверете дали артикулите са завършили първи
Задачата е отчетена успешно, но връзката липсва	Не е върнат `response.id` или е пропуснат `status`	Върнете `2xx` и попълнен отговор, освен при умишлено потвърждение без салон/маса

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

При липсваща зависимост по време на текуща синхронизация HES може временно да спре опашката и да опита отново. Обикновено това е цикъл с пауза около 60 секунди. Причината най-често е липсващо съпоставяне, а не проблем в комуникацията.

Проверки при работа

Използвайте тези адреси за диагностика:

GET /api/hype-custom/integrations
GET /api/hype-custom/integrations/{integrationId}
GET /api/hype-custom/integrations/{integrationId}/queue-jobs

Проверявайте:

статус на интеграцията: inactive, syncing, active, aborted, error
статус на процеса: pending, processing, synced, failed, stopped
задания, блокирани заради несъпоставен обект

12. Списък за проверка на реализацията

съхранявайте HES Bearer токен за всяка интеграция/акаунт
реализирайте извличане на задачи за всички документирани типове обекти
направете обработчиците идемпотентни
винаги отчитайте резултати с entity_task_id, status и response
включвайте id от вашата платформа при успешни задачи, различни от GET, когато съществува реален обект
обработвайте първоначалните GET задачи за статуси, канали за доставка и плащания с масиви от постоянни идентификатори
след active завършете и запазете ръчното съпоставяне на статуси, канали и плащания в административния интерфейс на Hype Server, преди да изпращате поръчки
всяка поръчка трябва да сочи към вече съпоставени артикули, добавки и статуси
записвайте идентификаторите на HES задачите и получените идентификатори на обектите за проследимост
следете адресите за интеграции и задания при първоначалната синхронизация

API справочник: hype-custom-integration.md
Postman колекция: https://documenter.getpostman.com/view/52109283/2sBXc8oNnL

Ръководство за разработчици: интеграция с Hype Custom ​

1. Цел ​

2. Общ модел ​

3. Източници и посоки на данните ​

4. Основни изисквания ​

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

Среди ​

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

5. Какво трябва да реализира вашата платформа ​

6. Справочник за API адресите ​

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

Webhook адреси ​

Адреси за наблюдение и поддръжка ​

7. Реализиране на обработчика на задачи ​

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

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

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

Примерна структура на обработчика ​

Стратегия за извличане ​

8. Реализиране на webhook клиента ​

Основен webhook за ежедневна работа ​

Важни правила за заявки за поръчки ​

Webhooks за първоначална настройка ​

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

Ред на стъпките ​

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

Какво да очаквате от процеса ​

Условия за пускане в работа ​

10. Съпоставяния и зависимости ​

Съпоставянето на идентификатори е основното изискване ​

Допълнителни правила за зависимостите ​

11. Обработка и диагностика на грешки ​

Чести HTTP грешки ​

Чести проблеми с интеграцията ​

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

Проверки при работа ​

12. Списък за проверка на реализацията ​

13. Свързани документи ​

Ръководство за разработчици: интеграция с Hype Custom

1. Цел

2. Общ модел

3. Източници и посоки на данните

4. Основни изисквания

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

Среди

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

5. Какво трябва да реализира вашата платформа

6. Справочник за API адресите

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

Webhook адреси

Адреси за наблюдение и поддръжка

7. Реализиране на обработчика на задачи

Правила за извличане на задачи

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

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

Примерна структура на обработчика

Стратегия за извличане

8. Реализиране на webhook клиента

Основен webhook за ежедневна работа

Важни правила за заявки за поръчки

Webhooks за първоначална настройка

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

Ред на стъпките

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

Какво да очаквате от процеса

Условия за пускане в работа

10. Съпоставяния и зависимости

Съпоставянето на идентификатори е основното изискване

Допълнителни правила за зависимостите

11. Обработка и диагностика на грешки

Чести HTTP грешки

Чести проблеми с интеграцията

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

Проверки при работа

12. Списък за проверка на реализацията

13. Свързани документи