# Сайт, витрина и формы Source: Locale: ru releaseGitSha: 0bb11ef116e17ec64c802d5476eaff442e53d252 sourceContentDigest: 9ec7bf9c1d7591d9d6c92550ab00a2ac068706d46c96e90aa255bdea1cb54041 Version: 4 Опубликуйте сайт своего бизнеса, настройте форму обращения и переход к покупке. В TelegaFirst сайт помогает начать разговор с AI-фронт-офисом в Telegram, а команда продолжает работу в Telegram-супергруппах. Заявка с сайта сохраняется сразу: переход посетителя в мессенджер помогает установить его личность, но не является условием сохранения обращения. ## Подготовка и адреса Сначала пройдите [вход и настройку бизнеса](https://telegafirst.com/docs/getting-started), проверьте активный slug и доступный `tools/list`. Для сайта нужны полномочия владельца и scopes конкретной операции. MCP использует предусмотренный credential владельца или интеграции; перечисленные REST-маршруты принимают `X-Api-Key` либо `Authorization: Bearer tgf_*`, а не surface-session JWT. Полномочия проверяются при каждом вызове. | Действие | Scope | | - | - | | Статус своего домена | `domain:read` | | Запрос подключения, проверка DNS, отключение | `domain:write` | | Загрузка/публикация сайта, формы, выдача checkout key | `site:write` | | Manifest, чтение файла через MCP, список имён секретов | `site:read` | | Настройки витрины | `storefront:read` / `storefront:write` | | Анонимный checkout relay | `orders` | | Чтение ответов форм через MCP | `pull:form_submissions` | | Отправка и отметка обработки через Hub/MCP | `push:form_submissions` | `Client.slug` — единственный читаемый tenant-адрес публичной поверхности. Товар, форма, событие и публичная заявка используют opaque `UniversalLink.code`; публичную ссылку нельзя построить из их номера. Для управления формой используется отдельный числовой `seqNum` своего tenant, для управления ответом — его собственный `seq_num`. Внутренний PK не передаётся ни в одну из этих поверхностей. [Идентификаторы](https://telegafirst.com/docs/identifiers-and-pagination). Две зоны `.ru` и `.com` обязательны на запуске. Это отдельные юридические и платёжные зоны; русский — язык по умолчанию, а язык оператора определяется настройкой бизнеса. Домены и примеры ниже — контрактные иллюстрации: `acme.ru`, UUID и ссылки `*.test` не подтверждают зарегистрированный домен или опубликованный сайт. Хосты сервисов берите из актуального ответа и настройки окружения. ## Прямая ссылка, открывающая страницу как мини-приложение `site_list_pages` / `GET /api/v1/tools/site/pages` отдают у каждой страницы `mini_app_links`, а на верхнем уровне — `mini_app_home`: по ссылке на Telegram, MAX и VK. Такая ссылка открывает опубликованную страницу внутри мини-приложения бота (`mini_app_home` — главную мини-приложения: `?startapp` без значения, в VK — без `#`), её можно вставить в текст рассылки. Ссылка несёт только opaque-код страницы, без номера. Если канал не откроет мини-приложение, `url` равен `null`, а `reason` говорит почему: `channel_not_connected` — мессенджер не подключён; `channel_surface_not_native` — мессенджер не открывает мини-приложения по ссылке; `mini_app_not_opened` — адрес мини-приложения ещё не зарегистрирован: он записывается при первом открытии мини-приложения бота, адрес которого задаётся в настройках бота (в Telegram — Mini App URL в BotFather); `page_not_published` — страница не показывается посетителям; `page_not_addressed` — у страницы ещё нет кода, опубликуйте её снова. По такой ссылке не считаются переходы `/r/l/`, а имя бота зашито в саму ссылку. ## Один адрес на зону У бизнеса ровно один публичный адрес в каждой зоне. Пока свой домен этой зоны не активен, это технический адрес платформы вида `{slug}.<зона сайтов>`: возьмите его из `site_list_pages` → `hosts` (`kind: "platform"`), не собирайте руками. Когда свой домен зоны становится `ACTIVE`, он занимает это место, а технический адрес отвечает постоянным редиректом 308 на тот же путь своего домена; ссылки, уже выданные на технический адрес, продолжают работать. Поддомена `shop.` нет: сайт, вход, витрина, оформление заказа и кабинет покупателя живут на одном адресе. На этом адресе пути делятся на три класса (без учёта регистра, путь `/x` включает `/x/...`): | Класс | Пути | Кто отвечает | | - | - | - | | Платформенные | `/auth`, `/checkout`, `/cart`, `/account`, `/refund`, `/l`, `/f`, `/product`, `/events`, `/booking`, `/widget`, `/miniapp`, `/api`, `/__telegafirst`, `/.well-known/acme-challenge` | всегда платформа; bundle с файлом под таким путём отклоняется целиком с 422 `SITE_PATH_RESERVED` | | Заменяемые | `/`, `/shop`, `/privacy`, `/terms`, `/refunds`, `/bio`, `/robots.txt`, `/sitemap.xml`, `/llms.txt`, `/.well-known` | ваш файл, если он есть в bundle; иначе автоматическая страница платформы | | Сайт | всё остальное | ваш bundle | Каталог всегда открывается по `/shop`. Корень `/` показывает ваш `index.html`. Без него на оплаченном тарифе там тот же каталог с `rel="canonical"` на `/shop`, поэтому `index.html` можно снять отдельно через `site_delete_page`; на бесплатном уровне корень без `index.html` ведёт себя как прежде. Карточка товара — `/product/{code}` с opaque кодом; ссылка «купить сейчас» — `/product/{code}?buy=1`: страница сама проводит вход и создаёт заказ, сам переход по ссылке ничего не записывает. В MCP товар каталога несёт `public_url` и `buy_url`; берите адреса оттуда. Скрипты service worker (`sw.js`, `service-worker.js`, `*-sw.js`) не принимаются ни под каким путём: тот же отказ `SITE_PATH_RESERVED`. ## Подключение своего домена 1. Прочитайте `domain_status` или `GET /api/v1/tools/domain`. Параметр `zone=ru` / `zone=com` выбирает свою зону; без него возвращается массив текущих подключений. 2. Вызовите `domain_add_request` или `POST /api/v1/tools/domain` с непустым HTTP `Idempotency-Key`. Передавайте bare hostname без схемы, пути и порта. Пример тела: ```json { "domain": "acme.ru", "zone": "ru" } ``` REST 201 не означает, что DNS уже проверен. Например, при anti-phishing admission ответ содержит `ownerStatus:"screening"`, `created:false`, `domain.status:"PENDING_DNS"` и `failedReason:"domain_screening_pending"`. Следуйте `instructions`: пока проверка безопасности не завершена, не публикуйте ни записи направления трафика, ни verification TXT. Повторный `domain_add_request` сообщает текущий admission status; не заменяйте его угадыванием DNS token. 3. После допуска опубликуйте точные DNS-записи из возвращённой инструкции, затем вызовите `domain_verify` / `POST /api/v1/tools/domain/verify` с `{"zone":"ru"}` и HTTP idempotency key. Проверка принимает только свою зону, не чужой hostname. Пример ещё незавершённого результата REST 201: ```json { "domain": { "domain": "acme.ru", "zone": "ru", "status": "PENDING_DNS", "dnsVerifiedAt": null, "certIssuedAt": null, "failedReason": "domain_screening_pending" }, "verified": false, "pendingReason": "screening_pending" } ``` `verified:false` — ожидаемый результат незавершённой проверки. После screening DNS может сообщать `nxdomain`, `mismatch`, `ambiguous`, `timeout` или `resolver_error`; сверяйте возвращённые `pendingReason` и записи. Распространение DNS зависит от вашего TTL. Успешная проверка переводит свой домен в `VERIFIED`; сертификат выпускается при первом HTTPS-обращении, а не доказывается одним ответом 201. 4. Чтобы отключить домен через MCP, сначала вызовите `domain_prepare_unlink`. Покажите человеку замороженные домен/зону из `payload` и срок действия `expires_at` возвращённой квитанции. Только после финального подтверждения человеком вызовите `domain_execute_unlink`: его JSON-тело содержит ровно `preparation_id` (UUID) и `payload_hash` (64 строчных hex-символа), скопированные без изменений из одной и той же квитанции подготовки. Подготовка не разрешает автоматическое отключение. Исполнение прекращает routing и обслуживание сертификата; новое подключение снова требует DNS-проверки. Существующий REST `DELETE /api/v1/tools/domain/{zone}` — отдельная прямая операция владельца. У неё нет выдуманных REST prepare/execute twins; человек должен заранее понимать эффект. ## Загрузка файлов и публикация Сайт, витрина, вход и кабинет живут на одном хосте вашего бизнеса, поэтому любой скрипт ваших страниц — ваш собственный или сторонний, который вы подключили, — выполняется рядом с сессией покупателя на этом хосте. Такой скрипт может от имени покупателя читать его профиль, заказы и платежи в вашем магазине, создавать заказы и рисовать страницу, похожую на оплату. Данные других бизнесов и платёжные данные карт ему недоступны. Подключайте только скрипты, которым доверяете так же, как своей CRM. Публикуйте на каноническом UGC-хосте бизнеса в `*.telegafirstsite.ru` или `*.telegafirstsite.com`, либо на его подключённом и проверенном custom-домене. Tenant UGC на основном домене платформы запрещён. Возьмите допустимый хост из настройки своего бизнеса; пример ниже иллюстративный и не подтверждает существующий сайт. Допустимый хост и подходящий тариф — предпосылки публикации. `site_request_upload` / `POST /api/v1/tools/site/request-upload` принимает `host`, необязательный `mode` и непустой массив файлов. По умолчанию `mode` равен `merge`: объявите новые или изменённые файлы; omitted bio, бинарные assets, gate-конфигурация и references сохранённых файлов остаются на месте. Переданные файлы заменяют одноимённые пути вместе с их declarations. Явный `mode: "replace"` означает полный snapshot: перечислите весь целевой сайт; отсутствующие файлы и правила доступа намеренно удаляются. Этот режим выбирается при выдаче ticket и не меняется при publish. Укажите путь относительно bundle, фактический размер UTF-8/бинарных байтов и MIME. `references`, когда нужны, — пути зависимостей внутри того же bundle; сервер проверяет их после объединения с сохранёнными файлами, и отсутствующая или недопустимая зависимость отклоняется. Квота проверяется по всему результирующему сайту, включая сохранённые файлы, а не только по patch. Пример добавления одной страницы с default merge: ```json { "host": "demo.telegafirstsite.ru", "files": [ { "path": "p/tripwire/index.html", "sizeBytes": 15, "contentType": "text/html" } ] } ``` REST 201 возвращает `uploadId` UUID, канонический `host`, `mode`, `baseManifestDigest` (строчный SHA-256 или `null`, если исходного manifest нет) и `uploads` с `path`, staging `key`, presigned `putUrl`, `expiresAt`. Base определяется сервером и закрепляется ticket; caller `baseManifestDigest`, `baseManifest` и `clientId` запрещены. Ссылки действуют 300 секунд. Не сочиняйте UUID или staging key: возьмите их из своего ответа. Загрузите каждый файл HTTP PUT непосредственно по его `putUrl`, сохранив заявленные content type и byte length. Неправильный размер не превращает ticket в разрешение загрузить дополнительные байты. Только после успешных PUT вызовите `site_publish` / `POST /api/v1/tools/site/publish`, снова с HTTP idempotency key: ```json { "host": "demo.telegafirstsite.ru", "uploadId": "11111111-1111-4111-8111-111111111111" } ``` UUID иллюстративный: нужен ticket того же tenant и закреплённого host. Перепривязать ticket к другому host нельзя; publish не принимает новый mode или base. Если исходный manifest или правила доступа изменились, ответ — 409 `SITE_BUNDLE_STALE`: получите новый ticket, выполните его PUT и затем publish. Не повторяйте stale ticket как разрешение перезаписать чужое изменение. Пример результата REST 201: ```json { "host": "demo.telegafirstsite.ru", "uploaded": ["p/tripwire/index.html"], "deleted": [], "unchanged": ["bio/index.html", "assets/app.js"], "manifestDigest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "attributionSnippet": "", "pageUrls": [ { "path": "p/tripwire/index.html", "url": "https://demo.telegafirstsite.ru/p/tripwire/index.html" } ] } ``` `uploaded` — записанные пути, `deleted` — удалённые, `unchanged` — сохранённые без записи. Delta Sync вычисляет изменения по фактическим staged bytes; `index.html` записывается последним. `pageUrls` содержит только HTML-пути этого ticket, которые действительно завершили публикацию. Сохранённая bio-страница не выдаётся как новая landing. Открывайте точный URL из результата; не выводите homepage, extensionless URL или live-ссылку из одного успешного upload ticket. После успеха staged файлы потреблены. Для нового deploy получите новые upload URLs; старый ticket нельзя использовать как постоянный источник контента. Размер всего сайта, размер одного видеофайла и суточный бюджет загрузок ограничиваются тарифом; число файлов сайта ограничено одинаково на всех тарифах. Суточный бюджет считает тикеты — один на запрос `site_request_upload`, сколько бы файлов он ни объявлял, — и байты объявленных файлов. Сервер проверяет заявленные размеры до выдачи URLs и реальные размеры перед публикацией. Конкретные числа своего тарифа берите из `details` отказа или из описания тарифа: документация их не повторяет. ### Сборка сайта из HTML-прототипа HTML, сохранённый из браузера или собранный генератором, часто несёт изображения, видео и шрифты прямо в странице как `data:` URL. Такой файл не публикуется: один HTML-тег читается только до фиксированного размера, и тег с крупным встроенным ресурсом отклоняется кодом `SITE_HTML_TAG_TOO_LARGE`. Встроенные `