Öz kodunuzla vitrin (headless)

Adi yol — bizim vitrinimiz və ya saytınızdakı vidjetlər. Lakin saytı sizin tərtibatçınız və ya agentliyiniz yazırsa və düzən tamamilə özünüzün olmalıdırsa, üçüncü variant işləyir: siz bizdən məlumatları və sifariş qəbulunu götürürsünüz, bütün frontend-i isə istənilən stekdə özünüz edirsiniz.

Məlumatların oxunması açar və avtorizasiya tələb etmir: vitrində açıq olan hər şey JSON-da da açıqdır.

Harada qurulur: Marketinq → «Mənim saytım» → «Öz kodunuzla vitrin» kartı. Orada həmçinin — filialınızın manifest ünvanı, texniki sənədləşmə və JSON-sxemlərə keçidlər və vebhukların qurulması. Heç nəyi aktivləşdirmək lazım deyil: məlumatlar həmişə dərc olunur.

storefront.json manifesti#

Tərtibatçının bilməli olduğu yeganə ünvan:

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

Manifestdə — qalan hər şey:

Müqavilə versiyalaşdırılır (contractVersion), yanında isə JSON-sxemlər var — onlarla məlumatları yoxlamaq və tiplər generasiya etmək rahatdır. Naməlum sahələrə məhəl qoyulmamalıdır: müqavilə uyğunluğu pozmadan genişlənir.

Məlumatlar və şəkillər#

Vitrinin göstərdiyi hər şey fayllarla əlçatandır: dillər üzrə menyu və kataloq, filialın profili (ad, ünvan, iş saatları, kontaktlar, tənzimləmələr), səhifələr və məqalələr, kolleksiyalar, rəylər.

Böyük kataloqlar üçün manifest api rejiminə keçir: menyu faylında yüngülləşdirilmiş seçim olur, tam kartlar fayl-fayl və ya filtrlər və alt kateqoriyalarla kataloq API-si vasitəsilə götürülür.

Şəkillər — bizim CDN-dən, manifestdəki şablona uyğun bir neçə ölçüdə; foto yeniləndikdə yol versiyalaşdırılır, buna görə keşi «əbədi» saxlamaq olar.

Bütün bu sorğuları əl ilə yazmaq vacib deyil: @cenaly/storefront npm paketi var — müqavilənin tipləşdirilmiş klienti (manifest, profil, kataloqun hər iki rejiminin menyusu, sifarişin rəsmiləşdirilməsi), şəkil URL-lərinin qurucusu və React hook-ları. Paketin statik yığımlar üçün ayrı giriş nöqtəsi (@cenaly/storefront/static: saytın ünvan xəritəsi, sitemap.xml, robots.txt, şəkillərə keçidlər) və konsol əmri cenaly-storefront var — filialın bütün məlumatlarının qovluğa çıxarılması, ünvanların siyahısı və manifesti izləyən, publishId dəyişən kimi sizin yığımınızı işə salan watch rejimi. O, həmçinin klonlayıb sadəcə rəngini dəyişə biləcəyiniz Next.js başlanğıc layihəsinin əsasını təşkil edir.

Sifarişlər və qonaq API#

Sifarişlərin qəbulu, sifarişin statusu, axtarış və rezervasiyalar — qonaq API vasitəsilə: avtorizasiyasız, ünvan manifestdən götürülür, spesifikasiya — OpenAPI 3.1. Ayrıca kommersiya konturu var: kuponlar, çatdırılmanın hesablanması, formalar, abunəliklər. Ətraflı — AI-agentlər üçün Guest API, eyni interfeys.

Saytınızın yaratdığı sifariş ümumi «Sifarişlər» bölməsinə düşür və adi qaydalarla yaşayır: statuslar, mətbəx, kuryerlər, qəbzlər, bildirişlər.

Dəyişikliklər barədə vebhuklar#

CDN-i sorğu ilə yoxlamamaq üçün hadisələrə abunə olun:

• menu.updated — menyu və ya kataloq yenidən generasiya olunub;
• profile.updated — filialın profili dəyişib;
• pages.updated — səhifələr və məqalələr dəyişib.

Hadisənin gövdəsində publishId gəlir — onunla statik səhifələri yenidən yığmaq və ya ISR-keşi sıfırlamaq rahatdır. Əgər sirr təyin etmisinizsə, sorğu HMAC-SHA256 ilə imzalanır və X-Meni-Signature başlığı ilə gəlir — nəyisə yenidən yığmazdan əvvəl imzanı yoxlayın; Vercel/Netlify deploy-hook-u üçün sirr yaratmaq lazım deyil. Filial başına beş ünvana qədər, on uğursuz cəhddən sonra isə abunəlik özü söndürülür (kabinetdə son çatdırılma və xəta sayğacı görünür; tənzimləmələri yenidən yadda saxlamaq onu geri qoşur).

Server hansı ünvanı qəbul edəcək. Yalnız https://, URL-in özündə login və parol olmadan, host isə mütləq publik olmalıdır: lokal, daxili və xidməti ünvanlar (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) yadda saxlanarkən rədd edilir. Öz maşınınızda sazlama üçün publik https ünvanlı tunel qaldırın.

Təkrar nə vaxt olur. Taymautlar və 5xx, 408, 429 cavabları təkrarlanır — yəni müvəqqəti nasazlığa bənzəyənlər. Hər hansı digər 4xx cavabı daimi xəta sayılır: təkrar olmayacaq, cəhd dərhal uğursuzluq sayğacına gedir.

Vebhuklar «Öz kodunuzla vitrin» kartında qurulur və ödənişli planlarda əlçatandır; məlumatların oxunması isə həmişə əlçatandır.

Haradan başlamalı#

1. Marketinq → «Mənim saytım» → «Öz kodunuzla vitrin» bölməsini açın və manifest ünvanını kopyalayın.
2. Manifesti yükləyin və ondan — menyu və profil məlumatlarını (ya da @cenaly/storefront paketini qoşun və ona filialın slaqını ötürün). Bu addımda heç bir açar lazım deyil.
3. Səhifələri öz freymvorkunuzla yığın; sifarişlər üçün qonaq API-dən istifadə edin.
4. Dəyişikliklər baş verdikcə saytı yenidən yığmaq üçün vebhuk əlavə edin — ya da hadisələri qəbul etmək üçün publik ünvan yoxdursa, cenaly-storefront watch işə salın: o, manifestdəki publishId-ni özü izləyir və yığımınızı işə salır.

Tam texniki təsvir — həmin kartdakı «Tərtibatçı sənədləşməsi» keçidində; yanında statik sayt üzrə ayrı təlimat və JSON-sxemlərə keçidlər var. Hazır Next.js başlanğıc layihəsi var, bütün sənədləşmə isə tərtibatçının İİ-assistentləri üçün llms.txt şəklində təkrarlanır — CDN-dəki filialınızın fərdi llms.txt-i də daxil olmaqla.

Əlaqəli bölmələr#

• Mənim saytım — saytı tamamilə yenidən yazmaq lazım deyilsə, vidjetlər
• AI agentləri üçün Guest API — həmin qonaq API-si
• Öz ATS-niz üçün API və MCP — AI agentlərinin və CRM-in telefoniyaya çıxışı
• İnternet mağazası — kataloq məlumatlarında məhz nə gəlir

Tez-tez verilən suallar#

Məlumatların oxunması üçün ödəniş etmək lazımdır? Xeyr. Publik JSON-lar istənilən Planda əlçatandır — bunlar bizim vitrinimizin istifadə etdiyi həmin fayllardır. Ödənişli olanlar vebhuklardır.

SEO ilə vəziyyət necədir? O, tamamilə sizin tərəfinizdədir: səhifələri özünüz yığırsınız və işarələməni özünüz idarə edirsiniz. Mikroişarələmə (JSON-LD) üçün məlumatlar kontraktda var.

Öz vitrinimlə birləşdirmək mümkündür? Bəli. Bizim vitrin, vidjetlər və sizin öz saytınız eyni məlumatlarla və eyni Sifariş səbəti ilə işləyir.