Өз кодыңыздағы витрина (headless)

Әдеттегі жол — біздің витрина немесе сіздің сайтыңыздағы виджеттер. Бірақ сайтты сіздің әзірлеушіңіз немесе агенттік жазып жатса және вёрстка толығымен өзіңіздікі болуы керек болса, үшінші нұсқа жұмыс істейді: сіз бізден деректер мен тапсырыс қабылдауды аласыз, ал бүкіл фронтендті өзіңіз кез келген стекте жасайсыз.

Деректерді оқу кілттер мен авторизацияны талап етпейді: витринада жария болғанның бәрі JSON-да да жария.

Қайда бапталады: Маркетинг → «Менің сайтым» → «Өз кодыңыздағы витрина» карточкасы. Сол жерде — филиалыңыздың манифест адресі, техникалық құжаттама мен JSON-схемаларға сілтемелер және вебхуктерді баптау. Ештеңе қосудың қажеті жоқ: деректер әрқашан жарияланады.

storefront.json манифесі#

Әзірлеушіге білу қажет жалғыз адрес:

https://cdn.cenaly.com/{ДОМЕН}/storefront.json

Манифестте қалғанының бәрі бар:

Блок	Ішінде не бар
`location`	Идентификатор, слаг, вертикаль (мейрамхана, дүкен, қонақүй, салон)
`languages`	Әдепкі тіл және қосылған тілдердің тізімі
`currency`	Валюта коды мен таңбасы
`cdnBase` + `data`	Мәзірге, профильге, беттерге, коллекцияларға, пікірлерге және «осынымен бірге сатып алады» ұсыныстарына апарар жолдар
`catalog`	Каталог режимі: бәрі файлдарда немесе файл бойынша карточкалар мен каталог API-і
`images`	Суреттер базасы, жол үлгілері (элемент пен галерея фотосы, видео, санаттар, коллекциялар, мұқаба мен логотип, favicon) және қолжетімді өлшемдер
`api`	Қонақ API-інің адрестері, OpenAPI спецификациялары, коммерциялық контур, MCP-эндпоинт және тапсырыстың тікелей мәртебелерінің WebSocket-і
`publishId`, `publishedAt`	Жарияланым идентификаторы: деректер әр қайта жасалғанда өзгереді

Контракт нұсқаланады (contractVersion), ал қасында JSON-схемалар жатыр — олар бойынша деректерді валидациялау және типтерді генерациялау қолайлы. Белгісіз өрістерді елемеу керек: контракт үйлесімділікті бұзбай кеңейеді.

Деректер мен суреттер#

Витрина көрсететіннің бәрі файлдар түрінде қолжетімді: мәзір мен каталог тілдер бойынша, филиал профилі (атауы, мекенжайы, жұмыс уақыты, байланыстары, баптаулары), беттер мен мақалалар, коллекциялар, пікірлер.

Үлкен каталогтар үшін манифест api режиміне ауысады: мәзір файлында жеңілдетілген іріктеме жатыр, толық карточкалар файл бойынша немесе сүзгілері мен ішкі санаттары бар каталог API-і арқылы алынады.

Суреттер — біздің CDN-нен, манифесттегі үлгі бойынша бірнеше өлшемде; фото жаңартылғанда жол нұсқаланады, сондықтан кэшті «мәңгілікке» ұстауға болады.

Осы сұраулардың бәрін қолмен жазу міндетті емес: @cenaly/storefront npm-пакеті бар — контрактің типтелген клиенті (манифест, профиль, каталогтың екі режиміндегі мәзір, тапсырысты рәсімдеу), сурет URL-дерін құрастырушы және React-хуктер. Пакеттің статикалық жинақтарға арналған жеке кіру нүктесі бар (@cenaly/storefront/static: сайт адрестерінің картасы, sitemap.xml, robots.txt, суреттерге сілтемелер) және cenaly-storefront консоль командасы — филиалдың барлық деректерінің папкаға түсірілген суреті, адрестер тізімі және манифестті қадағалап, publishId өзгерген бойда сіздің жинағыңызды іске қосатын watch режимі. Ол сондай-ақ клондап, жай ғана қайта бояуға болатын Next.js старттық жобасының негізінде жатыр.

Тапсырыстар мен қонақ API-і#

Тапсырыс қабылдау, тапсырыс мәртебесі, іздеу және броньдау — қонақ API-і арқылы: авторизациясыз, адрес манифесттен алынады, спецификация — OpenAPI 3.1. Бөлек коммерциялық контур бар: купондар, жеткізуді есептеу, формалар, жазылымдар. Толығырақ — AI-агенттерге арналған Guest API, сол интерфейс.

Сіздің сайтыңыз жасаған тапсырыс жалпы «Тапсырыстар» бөліміне түседі және әдеттегі ережелер бойынша өмір сүреді: мәртебелер, ас үй, курьерлер, чектер, хабарламалар.

Өзгерістер туралы вебхуктер#

CDN-ді сұраумен мазаламау үшін оқиғаларға жазылыңыз:

menu.updated — мәзір немесе каталог қайта жасалды;
profile.updated — филиал профилі өзгерді;
pages.updated — беттер мен мақалалар өзгерді.

Оқиға денесінде publishId келеді — ол бойынша статикалық беттерді қайта жинау немесе ISR-кэшті тазарту қолайлы. Егер секрет орнатсаңыз, сұрау HMAC-SHA256-пен қол қойылып, X-Meni-Signature тақырыбымен келеді — бірдеңені қайта жинамас бұрын қолтаңбаны тексеріңіз; Vercel/Netlify deploy-хугі үшін секрет орнатудың қажеті жоқ. Бір филиалға бес адреске дейін, ал қатарынан он сәтсіздіктен кейін жазылым өзі өшеді (кабинетте соңғы жеткізілім мен қате санауышы көрінеді; баптауларды қайта сақтау оны қайта қосады).

Сервер қандай адресті қабылдайды. Тек https://, URL-дің өзінде логин мен құпиясөзсіз, және хост жария болуға міндетті: жергілікті, ішкі және қызметтік адрестер (localhost, 10.0.0.0/8, 192.168.0.0/16, 172.16.0.0/12, 100.64.0.0/10, 169.254.169.254) сақтау кезінде қабылданбайды. Өз машинаңызда жөндеу үшін жария https-адресі бар туннель көтеріңіз.

Қайта жіберу қашан болады. Таймауттар мен 5xx, 408, 429 жауаптары қайталанады — яғни уақытша ақауға ұқсайтын нәрсе. Кез келген басқа 4xx жауабы тұрақты қате болып саналады: қайта жіберу болмайды, әрекет бірден сәтсіздік санауышына кетеді.

Вебхуктер «Өз кодыңыздағы витрина» карточкасында бапталады және ақылы жоспарларда қолжетімді; деректерді оқу әрқашан қолжетімді.

Неден бастау керек#

Маркетинг → «Менің сайтым» → «Өз кодыңыздағы витрина» ашып, манифест адресін көшіріңіз.
Манифестті жүктеп, одан — мәзір мен профиль деректерін алыңыз (немесе @cenaly/storefront пакетін орнатып, оған филиал слагіңізді беріңіз). Бұл қадамда ешқандай кілт қажет емес.
Беттерді өз фреймворкіңізбен жинаңыз; тапсырыстар үшін қонақ API-ін пайдаланыңыз.
Өзгерістер болған сайын сайтты қайта жинау үшін вебхук қосыңыз — немесе оқиғаларды қабылдайтын жария адрес жоқ болса, cenaly-storefront watch іске қосыңыз: ол манифесттегі publishId-ді өзі қадағалап, сіздің жинағыңызды іске қосады.

Толық техникалық сипаттама — сол карточкадағы «Әзірлеуші құжаттамасы» сілтемесінде; қасында статикалық сайт туралы жеке нұсқаулыққа және JSON-схемаларға сілтемелер бар. Next.js-те дайын старттық жоба бар, ал бүкіл құжаттама әзірлеушінің ИИ-ассистенттеріне арналған llms.txt түрінде қайталанады — оның ішінде CDN-дегі филиалыңыздың жеке llms.txt-і де бар.

Қатысты бөлімдер#

Менің сайтым — сайтты толығымен қайта жазудың қажеті болмаса, виджеттер
AI-агенттерге арналған Guest API — сол қонақ API
Өз АТС-іңіздің API және MCP — ИИ-агенттер мен CRM-нің телефонияға қол жеткізуі
Интернет-дүкен — каталог деректерінде нақты не келеді

Жиі қойылатын сұрақтар#

Деректерді оқығаны үшін төлеу керек пе? Жоқ. Ашық JSON кез келген жоспарда қолжетімді — бұл біздің витрина пайдаланатын сол файлдар. Ақылы болып вебхуктер саналады.

SEO ше? Ол толығымен сіздің жағыңызда: беттерді өзіңіз жинайсыз және таңбалауды өзіңіз басқарасыз. Микротаңбалауға арналған деректер (JSON-LD) келісімшартта бар.

Өз витринаңызбен біріктіруге бола ма? Иә. Біздің витрина, виджеттер және сіздің жеке сайтыңыз бір деректермен және бір тапсырыс себетімен жұмыс істейді.