​
Hızlı Başlangıç

Bu rehber, Hemen Builders ile ilk çalışan entegrasyonu kurmak içindir. En güvenli başlangıç yolu private app oluşturmak, minimum scope seçmek ve client_credentials akışıyla token almaktır.

​
Gereksinimler

  • Hemen Mağaza tenant admin hesabı.
  • Tenant domain’i: örnek velunamora.localhost veya production tenant domain’i.
  • Hemen Builders menüsüne erişim.
  • API isteği atabileceğiniz bir terminal veya HTTP client.
Geliştirme ve simülasyon URL’i: 
https://dev.hemenmagaza.com

​
1. Builders panelini açın

Tenant admin panelinde: 
https://{tenant-domain}/admin/builders
Lokal örnek: 
http://velunamora.localhost/admin/builders
Bu ekran sadece ilgili tenant’ın app, token, webhook, script ve audit log kayıtlarını gösterir. Merkezi Builders tabloları tenant database içinde değil, platform mysql bağlantısında tutulur; her kayıt tenant_id ile izole edilir.

​
2. Private app oluşturun

Panelde Private API Anahtarları alanından yeni app oluşturun. Önerilen ilk değerler:
AlanÖrnek
App adıERP Connector Dev
Tipprivate
Statusactive
Scopeproducts:read, orders:read
Webhook da bağlayacaksanız webhooks:write scope’unu ekleyin. Storefront script yönetimi için storefront_scripts:write gerekir.

​
3. Client secret üretin

Private app oluşturulduğunda sistem bir client_id ve client_secret üretir. Secret güvenlik kuralları:
  • Secret düz metin saklanmaz.
  • Panelde sadece üretildiği anda gösterilir.
  • Sistemde hash ve son 4 karakter tutulur.
  • Kaybedilirse rotate edilmelidir.

​
4. Token alın

Token endpoint: 
POST https://dev.hemenmagaza.com/builders/oauth/token
Örnek istek: 
curl -X POST "https://dev.hemenmagaza.com/builders/oauth/token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
    "grant_type": "client_credentials",
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "scope": "products:read orders:read"
  }'
Başarılı response: 
{
  "access_token": "hm_live_or_dev_token",
  "token_type": "Bearer",
  "expires_in": 0,
  "scope": "products:read orders:read"
}
expires_in değeri ortam konfigürasyonuna göre değişebilir. Mevcut geliştirme konfigürasyonunda süre sınırsız kabul edilebilir; production’da süreli token politikası uygulanabilir.

​
5. İlk API kontrolünü yapın

Önce token’ın hangi Builders app kaydına bağlı olduğunu kontrol edin: 
curl "https://dev.hemenmagaza.com/api/builders/v1/apps/me" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json"
Başarılı response ilgili app’in tenant_id, approved_scopes ve bağlı Headless client bilgisini döndürür. Scope registry endpoint’i token gerektirmeden okunabilir: 
curl "https://dev.hemenmagaza.com/api/builders/v1/scopes" \
  -H "Accept: application/json"

​
6. İlk webhook kaydını ekleyin

webhooks:write scope’u olan bir app ile panelden veya API üzerinden webhook endpoint’i ekleyebilirsiniz. Örnek endpoint: 
https://example.com/webhooks/hemen
Önerilen ilk event seti: 
order.created
order.paid
product.updated
API örneği: 
curl -X POST "https://dev.hemenmagaza.com/api/builders/v1/webhooks" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  --data '{
    "name": "ERP Orders",
    "url": "https://example.com/webhooks/hemen",
    "events": ["order.created"],
    "max_attempts": 5
  }'
Webhook secret sadece oluşturma response’unda görünür; kaybedilirse yeni endpoint oluşturmanız veya panelden yenilemeniz gerekir.

​
Sık görülen hatalar

HataMuhtemel sebep
invalid_clientclient_id veya client_secret hatalı, app aktif değil ya da secret rotate edildi.
invalid_scopeİstenen scope app için onaylı değil.
401 unauthenticatedBearer token eksik, hatalı veya revoke edilmiş.
403 scope deniedToken geçerli ama işlem için gerekli scope yok.

​
Sonraki adımlar