Etalase dengan kode sendiri (headless)

Jalur biasa adalah etalase kami atau widget di situs Anda. Namun jika situs ditulis oleh developer atau agensi Anda dan tampilannya harus sepenuhnya milik Anda, ada opsi ketiga: Anda mengambil data dan penerimaan pesanan dari kami, dan seluruh frontend Anda buat sendiri, dengan stack apa pun.

Membaca data tidak memerlukan kunci atau otorisasi: semua yang publik di etalase juga publik dalam JSON.

Di mana pengaturannya: Marketing → "Situs saya" → kartu "Etalase dengan kode sendiri". Di sana juga ada alamat manifes cabang Anda, tautan ke dokumentasi teknis dan skema JSON, serta pengaturan webhook. Tidak ada yang perlu diaktifkan: data selalu dipublikasikan.

Manifes storefront.json#

Satu-satunya alamat yang perlu diketahui developer:

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

Di manifes ada semua sisanya:

Kontrak diberi versi (contractVersion), dan di sebelahnya ada skema JSON — cocok untuk memvalidasi data dan menghasilkan tipe. Kolom yang tidak dikenal harus diabaikan: kontrak diperluas tanpa merusak kompatibilitas.

Data dan gambar#

Semua yang ditampilkan etalase tersedia sebagai file: menu dan katalog per bahasa, profil cabang (nama, alamat, jam operasional, kontak, pengaturan), halaman dan artikel, koleksi, ulasan.

Untuk katalog besar, manifes beralih ke mode api: di file menu ada sampel ringan, kartu lengkap diambil per file atau melalui API katalog dengan filter dan subkategori.

Gambar — dari CDN kami, dalam beberapa ukuran sesuai templat dari manifes; saat foto diperbarui, jalurnya diberi versi, sehingga cache bisa disimpan "selamanya".

Menulis semua permintaan ini secara manual tidak wajib: ada paket npm @cenaly/storefront — klien kontrak bertipe (manifes, profil, menu kedua mode katalog, pembuatan pesanan), pembuat URL gambar, dan hook React. Paket ini punya titik masuk terpisah untuk build statis (@cenaly/storefront/static: peta alamat situs, sitemap.xml, robots.txt, tautan gambar) dan perintah konsol cenaly-storefront — snapshot semua data cabang ke folder, daftar alamat, dan mode watch yang memantau manifes dan menjalankan build Anda begitu publishId berubah. Paket ini juga menjadi dasar proyek awal berbasis Next.js yang bisa dikloning dan sekadar diubah tampilannya.

Pesanan dan API tamu#

Penerimaan pesanan, status pesanan, pencarian, dan reservasi — melalui API tamu: tanpa otorisasi, alamat diambil dari manifes, spesifikasi — OpenAPI 3.1. Secara terpisah ada kontur komersial: kupon, perhitungan pengiriman, formulir, langganan. Selengkapnya — Guest API untuk agen AI, antarmuka yang sama.

Pesanan yang dibuat oleh situs Anda masuk ke bagian umum "Pesanan" dan berjalan sesuai aturan biasa: status, dapur, kurir, struk, notifikasi.

Webhook tentang perubahan#

Agar tidak melakukan polling ke CDN, berlanggananlah pada event:

• menu.updated — menu atau katalog diregenerasi;
• profile.updated — profil cabang berubah;
• pages.updated — halaman dan artikel berubah.

Di body event disertakan publishId — cocok untuk membangun ulang halaman statis atau mereset cache ISR. Jika Anda menetapkan secret, permintaan ditandatangani dengan HMAC-SHA256 dan datang dengan header X-Meni-Signature — verifikasi tanda tangan sebelum membangun ulang apa pun; untuk deploy hook Vercel/Netlify, secret tidak perlu dibuat. Hingga lima alamat per cabang, dan setelah sepuluh kegagalan berturut-turut langganan dinonaktifkan sendiri (di akun terlihat pengiriman terakhir dan penghitung error; menyimpan ulang pengaturan mengaktifkannya kembali).

Alamat seperti apa yang diterima server. Hanya https://, tanpa login dan kata sandi di URL itu sendiri, dan host wajib publik: alamat lokal, internal, dan layanan (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) ditolak saat penyimpanan. Untuk debugging di mesin Anda sendiri, jalankan tunnel dengan alamat https publik.

Kapan terjadi pengulangan. Timeout dan respons 5xx, 408, 429 diulang — yaitu hal-hal yang tampak seperti gangguan sementara. Respons 4xx lainnya dianggap error permanen: tidak ada pengulangan, percobaan langsung masuk ke penghitung kegagalan.

Webhook diatur di kartu "Etalase dengan kode sendiri" dan tersedia pada paket berbayar; membaca data selalu tersedia.

Dari mana memulai#

1. Buka Marketing → "Situs saya" → "Etalase dengan kode sendiri" dan salin alamat manifes.
2. Muat manifes dan darinya — data menu dan profil (atau pasang paket @cenaly/storefront dan berikan slug cabang kepadanya). Tidak perlu kunci apa pun pada langkah ini.
3. Bangun halaman dengan framework Anda; untuk pesanan gunakan API tamu.
4. Tambahkan webhook agar situs dibangun ulang saat ada perubahan — atau, jika tidak ada alamat publik untuk menerima event, jalankan cenaly-storefront watch: ia sendiri memantau publishId di manifes dan menjalankan build Anda.

Deskripsi teknis lengkap — melalui tautan "Dokumentasi developer" di kartu yang sama; di sebelahnya ada tautan ke panduan terpisah untuk situs statis dan ke skema JSON. Ada proyek awal siap pakai berbasis Next.js, dan seluruh dokumentasi diduplikasi dalam bentuk llms.txt untuk asisten AI developer — termasuk llms.txt pribadi cabang Anda di CDN.

Bagian terkait#

• Situs saya — widget, jika tidak perlu menulis ulang seluruh situs
• Guest API untuk agen AI — Guest API yang sama
• API dan MCP untuk PBX Anda sendiri — akses agen AI dan CRM ke teleponi
• Toko online — apa saja yang datang dalam data katalog

Pertanyaan umum#

Apakah perlu membayar untuk membaca data? Tidak. JSON publik tersedia di Paket apa pun — ini adalah file yang sama yang digunakan oleh etalase kami. Yang berbayar adalah webhook.

Bagaimana dengan SEO? Sepenuhnya di sisi Anda: Anda menyusun halaman sendiri dan mengelola markup sendiri. Data untuk microdata (JSON-LD) tersedia dalam kontrak.

Apakah bisa digabungkan dengan etalase sendiri? Ya. Etalase kami, widget, dan situs Anda sendiri bekerja dengan data yang sama dan satu keranjang Pesanan.