Настройте доступ
В Hallify выберите заведение → Настройки → Обслуживание → настройки ресурсов → Интеграции. Администратор с правом preorders.external.manage создаёт ключ, выбирает каналы продаж и разрешения. В публичном канале настройте активный канал и служебного пользователя. Одноразово скопируйте ключ на свой сервер.
Маршрут кабинета: /venues/:venueId/settings/fulfillment. Для четырёх методов выдайте catalog:read, quotes:write, orders:write и orders:read; webhooks:manage назначается отдельно. Замените :venueId идентификатором выбранного заведения.
Первый успешный сценарий
Выполните шаги по порядку. Откройте каждый метод для точного тела, обязательных заголовков и схемы ответа.
- Выполните GET catalog с разрешённым salesChannelId; сохраните идентификатор меню, токен графа, currency, timeZone и deliveryMethods.
- Выполните POST quotes с этим каталогом, выбранными товарами, способом исполнения и допустимым будущим временем. Для DELIVERY выберите возвращённый deliveryMethod и сохраните один исходный Idempotency-Key до отправки. Сохраните quoteId, quoteToken, возвращённый deliveryQuoteId и expiresAt.
- Выполните POST orders с принятым расчётом, его исходным выбором доставки и deliveryQuoteId при наличии, совпадающими входными данными и новым Idempotency-Key заказа. Сохраняйте этот ключ заказа и точное тело для каждого исходного повтора. Сохраните orderId, fulfillmentId и ревизию.
- Используйте GET orders/{orderId} или настроенные webhooks для получения состояния в пределах доступа партнёра.
Разделяйте подготовку доставки, клиентский сбор и вызов курьера
Перевозчика настраивает уполномоченный администратор: /organizations/:organizationId/delivery-connections для подключений и версий секретов, затем /venues/:venueId/settings/delivery для способов доставки, политики сбора и привязок пункта выдачи. Пути account API: /organizations/{organizationId}/delivery-connections и /organizations/{organizationId}/venues/{venueId}/delivery/policy или /delivery/bindings. Партнёрский ключ не даёт права настройки или staff-вызова курьера. Настроенный маршрут LIVE не доказывает боевую квалификацию перевозчика или региона.
Разрешённый каталог возвращает currency, timeZone и предварительный список deliveryMethods. Для DELIVERY доступны SELF, UBER_DIRECT или WOLT_DRIVE только при текущей доступности. Отсутствие deliveryMethod сохраняет SELF и должно сохраняться при исходном повторе; другие serviceMode должны опускать поле. Wolt Drive требует настоящие latitude/longitude точки доставки. Не выдумывайте координаты и не считайте строку адреса уже геокодированной.
POST quotes требует Idempotency-Key для DELIVERY. Он сохраняет подготовку EXTERNAL demand под текущими правами credential, выполняет ограниченную работу с перевозчиком вне нативной транзакции и выпускает нативный расчёт только после разрешения исходной подготовки доставки. Для не-DELIVERY это условное требование не вводится. Сохраняйте точные исходные ключ, тело, канал продаж и ID расчётов. PREORDER_DELIVERY_QUOTE_UNKNOWN, PREORDER_DELIVERY_QUOTE_NOT_READY, таймаут или потерянный ответ требуют явного исходного повтора; не выделяйте заменяющий ключ и не отправляйте другой расчёт ради восстановления.
Читайте код ошибки API из SdkError.apiCode и отдельно учитывайте SdkError.outcome. UNKNOWN обозначает неопределённый результат запроса и не устанавливает текущее бизнес-состояние доставки. SDK не выполняет автоматические повторы. При явном восстановлении используйте сохранённый исходный Idempotency-Key и точное тело, включая исходное отсутствие deliveryMethod.
При создании заказа удерживайте нативные quoteToken и deliveryQuoteId вместе; расчёт клиентского demand отличается от последующего staff dispatchQuoteId. Принятый клиентский сбор остаётся зафиксированным в валюте нативного заказа. Последующие стоимость перевозчика и срок отправки принадлежат отдельному staff-офферу и не меняют клиентское соглашение. Неопределённый исходный результат нужно разрешить до нового расчёта после истечения срока или изменения входных данных.
GET orders/{orderId} возвращает fulfillment.deliveryMethod, deliveryFeeAmount и безопасный deliveryTracking с нормализованным состоянием, ETA и requiresAttention. В партнёрском deliveryTracking.trackingUrl всегда null. Отсутствие tracking не доказывает ошибку или отмену доставки. Staff-вызов, отмена/readback перевозчика и локальное прерывание не входят в эти четыре партнёрские операции и публичный allowlist SDK. Состояние курьера не доказывает оплату и не выполняет отмену еды или возврат.
Состояния, повторы и восстановление
Расчёт ограничен по времени и используется один раз. После разрешения исходного результата получите новый при истечении срока или существенных изменениях. Идемпотентный повтор сохраняет исходные запрос и результат; он не продлевает срок и не ищет замену доставки. Начальное исполнение — HELD или CONFIRMED по политике; успешное создание не означает оплату или завершение. В этих четырёх партнёрских методах нет общего списка, отмены или изменения заказа.