Бронирования и лист ожидания

Настройте доступ

Администратор заведения настраивает и публикует публичный канал бронирования, правила, разрешённые origin сайта и доставку кода подтверждения. Используйте выданный publicHandle. Браузерные запросы сохраняют фактический разрешённый Origin; отсутствующий или запрещённый origin может быть отклонён. Если метод объявляет x-hallify-connection-id, это необязательный несекретный заголовок выбора настроенного представления, который не заменяет права выданного доступа.

Маршрут кабинета: /venues/:venueId/reservations → Правила → Публичный канал. Для настройки требуется reservations.rules.manage. Origin сайта состоит из протокола, имени хоста и необязательного порта, без пути.

Гарантия настраивается для своего периода обслуживания в Правила → Периоды обслуживания: NONE, DEPOSIT, PREPAID или CARD_HOLD, сумма за бронь или гостя, минимальное число гостей, сроки оплаты и бесплатной отмены, допустимость удержания при поздней отмене и неявке. Изменение политики сохраняет ранее принятые условия. Привязки ресторанного эквайринга для RESERVATION_GUARANTEE настраиваются отдельно в защищённом кабинете.

Widget configuration, availability, guarantee offers и новые intents используют фактический изолированный frame Origin и текущий storefrontWidgetContext. Обычные canonical/headless сценарии сохраняют нативный допуск Origin. Повтор исходного intent и приватное manage-продолжение сохраняют точные parent/connection provenance; обновление presentation proof не продлевает нативные сроки.

Открыть Hallify

Первый успешный сценарий

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

Прочитайте конфигурацию, доступные нативные способы проверки контакта и доступность по локальной дате заведения и числу гостей. Выберите точный период обслуживания и слот.
Запросите guarantee-offer для этих servicePeriodId, scheduledAt и partySize. Если гарантия обязательна, покажите точные условия и получите согласие гостя до создания намерения бронирования.
Создайте намерение бронирования с принятым guaranteeTermsHash, если гарантия обязательна, актуальными версиями условий/политики конфиденциальности и Idempotency-Key. Удалённый лист ожидания использует отдельный контракт намерения.
Сохраните исходные идентификатор и срок намерения. Прочитайте текущее состояние проверки и запросите фактически доставленный код до истечения срока кода и удержания.
Подтвердите намерение со своим сохранённым ключом команды. Храните исходный результат и доступ управления отдельно от nullable-обогащения текущим состоянием.
Прочитайте свою бронь. Если её актуальная нативная гарантия требует оплаты, перейдите в отдельный guest-payments с настоящими правами RESERVATION_MANAGE. Подтверждайте бронь только при разрешении текущих allowedActions и серверных правил.

Проверьте точный слот и digest гарантии

Чтение предложения не создаёт бронь, удержание вместимости или платёж. Оно связывает выбранный слот, число гостей, нативную ревизию периода, вид гарантии, способ расчёта, точную сумму с двумя десятичными знаками и валюту, абсолютные dueAt, freeCancellationAt и noShowAfter, правила удержания и версии условий/конфиденциальности.

При required: true покажите полученные terms, получите явное согласие и дословно передайте termsHash как guaranteeTermsHash в намерении бронирования. Не рассчитывайте свою сумму или digest. Изменение слота, числа гостей или политики требует нового просмотра; устаревшее согласие отклоняется без незаметного пересчёта.

NONE или число гостей ниже порога политики возвращает required: false, terms: null и termsHash: null. Это явное отсутствие денежного обязательства. Отсутствующий ответ, запрещённый origin или недоступный эквайринг не означают NONE. Ниже приведён синтетический ответ NONE, а не реальная бронь.

Примеры запросов

{
  "required": false,
  "terms": null,
  "termsHash": null
}

Получить точные нативные условия гарантии для выбранного слота

Разделяйте исходную квитанцию намерения и текущую проверку

Создание намерения возвращает исходные intentId, verificationId и expiresAt вместе с обогащением currentState/current. Потерянный ответ восстанавливается повтором с исходным ключом и тем же телом. currentState: UNAVAILABLE и current: null не отменяют исходную команду и не разрешают создавать ещё одно намерение.

read-intent раскрывает только обезличенное состояние своего канала и исходного request fingerprint при текущих правах Origin/presentation. Одного идентификатора недостаточно. Чтение не возвращает контакт, код, детали брони или manage-токен, не создаёт бронь и не продлевает срок. Метод объявлен публичным; не придумывайте отдельный Bearer-токен намерения.

Используйте serverTime, expired и canVerify вместе с verification.expiresAt, attemptsRemaining, canResend и resendAvailableAt. Срок кода отделён от срока намерения/удержания. Доставка в очереди или отправке не завершена; sent/delivered не подтверждают код. UNKNOWN или сбой не разрешают заменяющую отправку. Ответ resend — исходное принятие команды с отдельными текущими сведениями о доставке.

При неизвестном результате verify повторите ту же команду для восстановления исходного ответа. Чтение использованного намерения не раскрывает и не продлевает доступ управления. Новое намерение после доказанного истечения создаётся лишь при отсутствии неразрешённой конвертации; заново запросите доступность и проверьте условия.

Читайте фактическое состояние перед действием

Результат verify сохраняет исходные идентификатор, номер, ревизию, статус, события и выданный manage-доступ. Отдельные currentState/current содержат текущее разрешённое представление управления; оно может быть недоступно без изменения сохранённой квитанции. Следующие команды управления тоже сохраняют исходный бизнес-результат и сообщают manageAccessState для исходного преемника доступа.

Используйте текущее чтение управления для revision, allowedActions, serverTime, guarantee и pendingAgreement. Историческая квитанция не доказывает текущее подтверждение, оплату или восстановление. Чтение не продлевает grantExpiresAt. При истечении, замещении доступа или необходимости повторного доказательства не используйте старый статус как право и не создавайте вымышленный токен.

При финансовом изменении слота/числа гостей самим гостем покажите новое точное предложение и передайте guaranteeTermsHash с текущим expectedRevision в change-reservation. Текущий manage-доступ подтверждает согласие этого гостя. Квитанция agreementChange может оставаться ACCEPTED, пока фактическая бронь сохраняет старый слот до завершения распоряжения средствами и активации. Следуйте текущему состоянию без повторного создания изменения.

Лист ожидания управляется отдельно. Приглашённую запись можно принять только в её текущем окне и при разрешении allowedActions; CLAIM переводит её в CLAIMED и не создаёт бронь. Публичный handle не открывает полный список броней ресторана.

Явно подтвердите контакт и примите CHANGE или RESTORE

Финансовое CHANGE или RESTORE, предложенное сотрудником, использует точное замороженное соглашение changeId. Ссылка на предложение или значение контакта не дают прав управления и оплаты. Публичные методы проверяют и принимают существующее предложение; публичной команды сотрудника для создания предложения или восстановления нет.

Challenge использует тип/значение контакта существующего гостя и отображаемое имя. Передайте возвращённую capability и фактически доставленный код в verify в том же Origin/request-контексте. Успешная проверка сопоставляет реального нативного гостя до раскрытия предложения и выдаёт отдельную capability принятия. Проверка сама не принимает условия и не восстанавливает бронь.

Покажите action, предложенные начало/конец, число гостей и offer из проверенного agreement. После явного согласия передайте capability и точный agreement.planHash в accept. planHash связывает всё предложение и отличается от offer.termsHash и digest платёжного согласия. У challenge, verify и accept свои сохранённые Idempotency-Key и неизменные тела повторов.

Принятие возвращает original и отдельно manageToken, manageTokenExpiresAt, manageAccessState и currentState/current. Исходное ACCEPTED — сохранённое свидетельство согласия. Ранее списанные средства должны быть фактически возвращены, старая авторизация — освобождена, а исходные незавершённые платежи — разрешены до допуска по вместимости и активации. Постановка распоряжения в очередь ещё не завершает его.

Текущие состояния предложения: PENDING, ACCEPTED, ACTIVATED, EXPIRED и SUPERSEDED. Отменённая, просроченная бронь или неявка остаётся терминальной до активации; одно согласие её не восстанавливает. Активация перепроверяет замороженный источник, сроки, коммерческий доступ и вместимость. Ошибка или истечение не продлевают срок, не заменяют условия и не разрешают новую оплату гарантии. Читайте текущее управление и сохраняйте исходную команду для восстановления.

Оплатите настоящую нативную гарантию

Откройте гостевой платёжный доступ с kind: RESERVATION_MANAGE, resourceId равным UUID нативной брони и её текущей приватной manage-capability при фактическом Origin источника. Сервер определяет точную текущую нативную гарантию. Лист ожидания, идентификатор предложения, observer ticket, контактный код или аккаунт не заменяют этот источник.

Настоящие bill/quote гарантии содержат purpose: RESERVATION_GUARANTEE и данные guarantee без целей Order. В quote гарантии передаются только purpose, допустимый merchantBindingId и locale; полностью опустите targets и requestedTipAmount. Сервер определяет principal, нулевые чаевые, валюту и capture mode. Проверьте юридического получателя и точное сохранённое платёжное согласие дополнительно к условиям бронирования.

DEPOSIT и PREPAID используют AUTOMATIC capture. CARD_HOLD использует MANUAL authorization и не является списанными деньгами. Для выполнения нативной гарантии нужны аутентифицированные данные провайдера о точной сумме и действующей авторизации, срок которой покрывает принятый период защиты. Редирект провайдера, исходная квитанция checkout PREPARED или согласие с условиями этого не доказывают.

Сохраняйте исходную платёжную команду и разделяйте чтение квитанции/прогресса и явное финансовое восстановление. При UNKNOWN исходный результат не разрешён; автоматическая новая команда или оплата недопустима. Перечитайте guarantee и allowedActions в нативном управлении; не превращайте acknowledgement checkout в подтверждение брони или ACTIVATED соглашения.

Разделяйте финансовые права гостя и сотрудника

forfeitGuarantee и applyGuaranteeCredit — защищённые операции сотрудников вне публичного/headless allowlist. Поздняя отмена или неявка не запускает публичное автоматическое списание с карты. Удержание сотрудником следует исходным принятым условиям и реальным данным провайдера/Financial. Зачёт применяет списанный principal DEPOSIT/PREPAID к настоящему Order рассаженной компании при правах сотрудника; гость не может подставить угаданные Order или плательщика. Форма зачёта сотрудника получает реальную текущую ревизию Order через защищённый Order GetById и передаёт её вместе с ревизией брони. Это поле чтения не даёт публичных гостевых/headless прав и не добавляет guest endpoint.

Примеры синтетические и не выполняют бронирование, проверку контакта или запрос провайдера. Исходники поддерживают hosted/shared/custom и изолированное widget-бронирование с теми же нативными условиями, явным согласием и исходным восстановлением. JS/TS SDK не добавляет staff permissions или финансовое согласие. Database, browser, deployed-domain и merchant/provider квалификации остаются отдельными.