Giriş
Hemen Builders, Hemen Mağaza üzerinde çalışan uygulama ve entegrasyonların geliştirildiği güvenli developer platformudur. İlk hedef, mağazaya özel private app entegrasyonlarını hızlı ve kontrollü şekilde çalıştırmak; ikinci hedef ise public app, embedded admin app, marketplace ve partner yayınlama akışını aynı omurga üzerinde büyütmektir. Bu bölüm sadece API listesi değildir. Bir geliştiricinin sıfırdan uygulama oluşturup token alması, API çağırması, webhook bağlaması, gerektiğinde admin paneline action eklemesi ve ileride uygulamasını yayınlaması için takip edeceği yol haritasıdır.App türleri
Hemen Builders tarafında app kayıtları şu tiplerle modellenir:| Tip | Durum | Kullanım |
|---|---|---|
private | Çalışır MVP | Tek mağaza için oluşturulan özel API credential ve entegrasyonlar. Ana geliştirme yolu budur. |
webhook_listener | Çalışır MVP | Ana amacı event almak ve dış sisteme aktarmak olan entegrasyonlar. webhooks:write scope’u ile API üzerinden yönetilebilir. |
embedded_admin | Beta | Tenant admin panelinde iframe içinde çalışan ve App Bridge ile konuşan admin uygulamaları. |
public | Roadmap | Marketplace’te yayınlanması planlanan, çok mağazalı uygulamalar. Review ve publishing akışı gerektirir. |
internal | İç kullanım | Hemen Mağaza’nın kendi operasyonel veya servis içi uygulamaları. |
Nereden başlamalıyım?
Önerilen ilk adım
Private app oluştur
Tenant admin panelinden credential üret, token al ve ilk API isteğini gönder.
Event tabanlı entegrasyon
Webhook bağla
Sipariş, ürün ve stok olaylarını imzalı payload ile dış sistemlere taşı.
Developer journey
- Private app oluşturun: Tenant admin panelindeki Builders alanından uygulama kaydı ve credential üretin.
- Scope seçin: Uygulamanın gerçekten ihtiyacı olan minimum yetkileri verin.
- Token alın:
client_credentialsakışıyla access token üretin. - API çağırın: Token’ı
Authorization: Bearerheader’ı ile kullanın. - Webhook bağlayın: Gerekiyorsa
webhooks:writescope’u ile event aboneliği ekleyin. - SDK/CLI kullanın: Lokal geliştirmeyi ve tekrar eden işleri hızlandırın.
- Public app’e hazırlanın: Çok mağazalı kullanım, App Bridge, action, plan ve review gereksinimlerini tamamlayın.
Scope mantığı
Hemen Builders scope’ları yüksek seviyeli developer izinleridir. Gerektiğinde HemenHeadless scope’larına çevrilir.| Builders scope | Açıklama | Headless karşılığı |
|---|---|---|
products:read | Ürün ve katalog verilerini okuma | catalog:read |
orders:read | Sipariş verilerini okuma | order:read |
customers:read | Müşteri verilerini okuma | customer:read |
cart:write | Sepet işlemleri | cart:write |
checkout:write | Checkout işlemleri | checkout:write |
webhooks:write | Webhook endpoint yönetimi | webhook:manage |
storefront_scripts:write | Storefront script kaydı yönetimi | - |
mcp:use | MCP araçlarını kullanma | - |
orders:read dışına çıkmamalıdır.
Public app durumu
Public app, marketplace ve embedded admin app akışı sistemde modellenmiştir; ancak ilk üretim kullanımı private app ve webhook geliştirme akışıdır. Public app yayınlama tarafında review, plan, bölge, allowed store ve analytics yüzeyleri kademeli olarak aktif edilir.Şu an çalışan API yüzeyi
| Yüzey | Endpoint | Durum |
|---|---|---|
| Scope listesi | GET /api/builders/v1/scopes | Çalışır |
| App token kontrolü | GET /api/builders/v1/apps/me | Çalışır, Bearer token ister |
| OAuth token | POST /builders/oauth/token | Çalışır |
| Webhook oluşturma | POST /api/builders/v1/webhooks | Çalışır, webhooks:write ister |
| Webhook delivery listesi | GET /api/builders/v1/webhook-deliveries | Çalışır, webhooks:write ister |
| Webhook test payload | POST /api/builders/v1/webhooks/{id}/test | Çalışır, imzalı test delivery üretir |
| Storefront script oluşturma | POST /api/builders/v1/storefront-scripts | Çalışır, storefront_scripts:write ister |
| Storefront script listesi | GET /api/storefront/{storefront}/builders/scripts | Çalışır, tenant context ister |
| Admin App Bridge | HemenAppBridge.js | Beta |
| Public app publishing | Süperadmin review ekranları | Beta/Roadmap |
Bu kategorideki sayfalar
- Hızlı Başlangıç: İlk private app ve token akışı.
- Geliştirme Ortamı:
dev.hemenmagaza.com, local URL, tunnel ve origin prensipleri. - Authentication: Token alma, header formatı, rotate/revoke ve hata kodları.
- Hemen CLI: Terminal tabanlı geliştirme komutları.
- Hemen SDK: JavaScript SDK modülleri ve örnek kullanım.
- Webhook Entegrasyonu: Event, imza, retry ve delivery detayları.
- Uygulama Aksiyonları: Admin panel ekranlarına action ekleme modeli.
- Private Apps: Mağazaya özel entegrasyonların yönetimi.
- Yayınlama: Public app review ve marketplace hazırlık süreci.