​
Geliştirme Ortamı

Hemen Builders geliştirme akışı üç ortamı birlikte düşünür:
  • Lokal geliştirici makinesi.
  • https://dev.hemenmagaza.com simülasyon ve entegrasyon ortamı.
  • Production tenant ve storefront domain’leri.
Amaç, uygulamanın localde hızlı geliştirilmesi ama tenant verisinin, credential’ın ve webhook payload’ının her ortamda izole kalmasıdır.

​
Ortam URL’leri

OrtamKullanım
http://localhost:*Uygulama arayüzü veya webhook listener local testleri.
http://{tenant}.localhostLokal tenant admin paneli.
https://dev.hemenmagaza.comBuilders API, token, webhook ve MCP simülasyon tabanı.
https://builders.hemenmagaza.comPublic developer dokümantasyonu.

​
Önerilen env değerleri

SDK, CLI ve MCP tarafında ortak kullanılabilecek değerler: 
HEMEN_BUILDERS_API_BASE_URL=https://dev.hemenmagaza.com
HEMEN_BUILDERS_TOKEN=YOUR_ACCESS_TOKEN
HEMEN_BUILDERS_TENANT_ID=velunamora
Local app geliştirme için: 
HEMEN_BUILDERS_APP_URL=http://localhost:3000
HEMEN_BUILDERS_WEBHOOK_URL=https://your-tunnel.example.com/webhooks/hemen

​
Local app URL

Embedded admin app veya public app arayüzü geliştirirken app’iniz bir HTTP server olarak çalışır. Örnek: 
npm run dev -- --port 3000
Geliştirme sırasında app URL’iniz: 
http://localhost:3000
Production için app URL’i HTTPS olmalıdır.

​
Tunnel kullanımı

Webhook veya embedded iframe testlerinde platformun local makinenize erişmesi gerekir. Bu nedenle local server’ı public HTTPS URL ile açmanız gerekir. Örnek tunnel URL’i: 
https://erp-connector-dev.example-tunnel.com
Bu URL şu alanlarda kullanılabilir:
  • Webhook endpoint URL’i.
  • Embedded app embedded_url.
  • OAuth callback URL’i.
  • App action iframe URL’i.

​
Allowed origins

Browser veya iframe tabanlı app’lerde origin allowlist zorunludur. App kaydında izin verilen origin yoksa iframe, App Bridge veya browser tabanlı çağrılar reddedilmelidir. Örnek origin listesi: 
http://localhost:3000
https://erp-connector-dev.example-tunnel.com
https://app.example.com
Origin sadece scheme + host + port bilgisidir. Path içermez.

​
Tenant izolasyonu

Her app, token, webhook ve storefront script işlemi tenant scope içinde çalışır. Kurallar:
  • Tenant admin sadece kendi tenant_id kayıtlarını görür.
  • Süperadmin tenant filtresiyle global görünüm alabilir.
  • Builders tabloları merkezi connection’dadır ama kayıt erişimi tenant guard ile sınırlandırılır.
  • Secret, token ve webhook secret düz metin saklanmaz.
  • Süperadmin bypass işlemleri dahil audit log yazılır.

​
Geliştirme kontrol listesi

Localden gerçek entegrasyona geçmeden önce:
  • App active durumda mı?
  • App scope seti yeterli ama minimum mu?
  • client_secret güvenli kasada mı?
  • Webhook URL’i HTTPS mi?
  • App origin allowlist’e eklendi mi?
  • Token alınabiliyor mu?
  • İlk API isteği 401/403 dönmeden çalışıyor mu?
  • Webhook endpoint’i idempotent mi?