ვიტრინა საკუთარ კოდზე (headless)

ჩვეულებრივი გზა — ჩვენი ვიტრინა ან ვიჯეტები თქვენს საიტზე. მაგრამ თუ საიტს წერს თქვენი დეველოპერი ან სააგენტო და აწყობა უნდა იყოს სრულიად საკუთარი, მოქმედებს მესამე ვარიანტი: თქვენ ჩვენგან იღებთ მონაცემებსა და შეკვეთების მიღებას, ხოლო მთელ ფრონტენდს აკეთებთ თავად, ნებისმიერ სტეკზე.

მონაცემების წაკითხვა არ მოითხოვს გასაღებებსა და ავტორიზაციას: ყველაფერი, რაც საჯაროა ვიტრინაზე, საჯაროა JSON-შიც.

სად კონფიგურირდება: მარკეტინგი → „ჩემი საიტი“ → ბარათი „ვიტრინა საკუთარ კოდზე“. იქვეა — თქვენი ლოკაციის მანიფესტის მისამართი, ბმულები ტექნიკურ დოკუმენტაციასა და JSON-სქემებზე და ვებჰუკების კონფიგურაცია. ჩართვა არაფრის არის საჭირო: მონაცემები ქვეყნდება ყოველთვის.

storefront.json მანიფესტი#

ერთადერთი მისამართი, რომელიც დეველოპერმა უნდა იცოდეს:

https://cdn.meni.ge/{DOMAIN}/storefront.json

მანიფესტშია ყველაფერი დანარჩენი:

კონტრაქტი ვერსიონირდება (contractVersion), ხოლო იქვე განთავსებულია JSON-სქემები — მათი მეშვეობით მოსახერხებელია მონაცემების ვალიდაცია და ტიპების გენერირება. უცნობი ველები უნდა დააიგნოროთ: კონტრაქტი ფართოვდება თავსებადობის დარღვევის გარეშე.

მონაცემები და სურათები#

ყველაფერი, რასაც ვიტრინა აჩვენებს, ხელმისაწვდომია ფაილების სახით: მენიუ და კატალოგი ენების მიხედვით, ლოკაციის პროფილი (სახელწოდება, მისამართი, სამუშაო საათები, კონტაქტები, პარამეტრები), გვერდები და სტატიები, კოლექციები, შეფასებები.

დიდი კატალოგებისთვის მანიფესტი გადადის api რეჟიმში: მენიუს ფაილში განთავსებულია შემსუბუქებული ამონაკრები, ხოლო სრული ბარათები იტვირთება თითო-თითო ფაილად ან კატალოგის API-ს მეშვეობით ფილტრებითა და ქვეკატეგორიებით.

სურათები — ჩვენი CDN-იდან, რამდენიმე ზომაში მანიფესტის შაბლონის მიხედვით; ფოტოს განახლებისას მისამართის გზა ვერსიონირდება, ამიტომ ქეშის შენახვა შესაძლებელია „სამუდამოდ“.

ყველა ამ მოთხოვნის ხელით დაწერა აუცილებელი არ არის: არსებობს npm-პაკეტი @cenaly/storefront — კონტრაქტის ტიპიზებული კლიენტი (მანიფესტი, პროფილი, მენიუ კატალოგის ორივე რეჟიმისთვის, შეკვეთის გაფორმება), სურათების URL-ების შემქმნელი და React-ჰუკები. პაკეტს გააჩნია ცალკე შესვლის წერტილი სტატიკური ბილდებისთვის (@cenaly/storefront/static: საიტის მისამართების რუკა, sitemap.xml, robots.txt, სურათების ბმულები) და კონსოლის ბრძანება cenaly-storefront — ლოკაციის ყველა მონაცემის ასლი საქაღალდეში, მისამართების სია და watch რეჟიმი, რომელიც აკვირდება მანიფესტს და უშვებს თქვენს ბილდს, როგორც კი შეიცვლება publishId. ის ასევე უდევს საფუძვლად Next.js-ის სტარტერ პროექტს, რომლის დაკლონვა და მარტივად თქვენს სტილზე მორგება შეგიძლიათ.

შეკვეთები და სტუმრის API#

შეკვეთების მიღება, შეკვეთის სტატუსი, ძიება და ჯავშნები — სტუმრის API-ის მეშვეობით: ავტორიზაციის გარეშე, მისამართი აღებულია მანიფესტიდან, სპეციფიკაცია — OpenAPI 3.1. ცალკე არსებობს კომერციული კონტური: კუპონები, მიწოდების გაანგარიშება, ფორმები, გამოწერები. დეტალურად — Guest API AI-აგენტებისთვის, იგივე ინტერფეისი.

შეკვეთა, რომელიც თქვენმა საიტმა შექმნა, ხვდება საერთო განყოფილებაში „შეკვეთები" და ცხოვრობს ჩვეულებრივი წესებით: სტატუსები, სამზარეულო, კურიერები, ჩეკები, შეტყობინებები.

ვებჰუკები ცვლილებების შესახებ#

CDN-ის გამოკითხვის (polling) თავიდან ასაცილებლად, გამოიწერეთ ივენთები:

• menu.updated — მენიუ ან კატალოგი თავიდან დაგენერირდა;
• profile.updated — ლოკაციის პროფილი შეიცვალა;
• pages.updated — გვერდები და სტატიები შეიცვალა.

ივენთის ტანში (body) მოდის publishId — მისი მეშვეობით მოსახერხებელია სტატიკური გვერდების თავიდან აწყობა ან ISR-ქეშის გასუფთავება. თუ მიუთითეთ საიდუმლო გასაღები (secret), მოთხოვნა დამოწმდება 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) შენახვისას უარყოფილი იქნება. საკუთარ მოწყობილობაზე გამართვისთვის (debug) გაუშვით გვირაბი (tunnel) საჯარო https-მისამართით.

როდის ხდება გამეორება. მეორდება ტაიმაუტები და 5xx, 408, 429 პასუხები — ანუ ყველაფერი, რაც დროებით შეფერხებას ჰგავს. ნებისმიერი სხვა 4xx პასუხი მუდმივ შეცდომად ითვლება: განმეორება არ მოხდება, მცდელობა პირდაპირ წარუმატებლობების მრიცხველში აღირიცხება.

ვებჰუკები კონფიგურირდება ბარათში „ვიტრინა საკუთარ კოდზე“ და ხელმისაწვდომია ფასიან ტარიფებზე; მონაცემების წაკითხვა ყოველთვის ხელმისაწვდომია.

რით დავიწყოთ#

1. გახსენით მარკეტინგი → „ჩემი საიტი“ → „ვიტრინა საკუთარ კოდზე“ და დააკოპირეთ მანიფესტის მისამართი.
2. ჩამოტვირთეთ მანიფესტი და მისგან — მენიუსა და პროფილის მონაცემები (ან დააყენეთ პაკეტი @cenaly/storefront და გადაეცით მას ლოკაციის სლაგი). ამ ეტაპზე არანაირი გასაღები არ არის საჭირო.
3. ააწყვეთ გვერდები თქვენი ფრეიმვორკით; შეკვეთებისთვის გამოიყენეთ სტუმრის API.
4. დაამატეთ ვებჰუკი, რათა საიტი ხელახლა აეწყოს ცვლილებებისთანავე, — ან, თუ მოვლენების მისაღებად საჯარო მისამართი არ გაქვთ, გაუშვით cenaly-storefront watch: ის თავად ადევნებს თვალს publishId-ს მანიფესტში და გაუშვებს თქვენს აწყობას.

სრული ტექნიკური აღწერა — იმავე ბარათში ბმულზე „დეველოპერის დოკუმენტაცია“; იქვეა ბმულები სტატიკური საიტის ცალკეულ სახელმძღვანელოზე და JSON-სქემებზე. ხელმისაწვდომია მზა სასტარტო პროექტი Next.js-ზე, ხოლო მთელი დოკუმენტაცია დუბლირებულია llms.txt-ის სახით დეველოპერის AI-ასისტენტებისთვის — მათ შორის თქვენი ლოკაციის პერსონალური llms.txt CDN-ზე.

დაკავშირებული განყოფილებები#

• ჩემი საიტი — ვიჯეტები, თუ საიტის სრულად ხელახლა დაწერა საჭირო არ არის
• Guest API AI-აგენტებისთვის — იგივე სტუმარი-API
• ტელეფონიის API და MCP — AI-აგენტებისა და CRM-ის წვდომა ტელეფონიასთან
• ონლაინ მაღაზია — რა ზუსტად ჩამოდის კატალოგის მონაცემებში

ხშირად დასმული კითხვები#

საჭიროა თუ არა მონაცემების წაკითხვის გადახდა? არა. საჯარო JSON ხელმისაწვდომია ნებისმიერ ტარიფზე — ეს იგივე ფაილებია, რომლებსაც ჩვენი ვიტრინა იყენებს. ფასიანია მხოლოდ ვებჰუკები.

რა ხდება SEO-სთან? ის მთლიანად თქვენს მხარეზეა: გვერდებს თავად აწყობთ და თავად მართავთ სემანტიკურ მარკირებას. მიკროსემანტიკის მონაცემები (JSON-LD) კონტრაქტში არის.

შესაძლებელია თუ არა საკუთარ ვიტრინასთან შეთავსება? დიახ. ჩვენი ვიტრინა, ვიჯეტები და თქვენი საკუთარი საიტი მუშაობს ერთსა და იმავე მონაცემებთან და ერთ შეკვეთების კალათასთან.