1. 5 Dakikada Hızlı Başlangıç & Kimlik Doğrulama
Omurga Storefront API, yalnızca okuma yetkili (read-only) ve kiracıya özel yalıtılmış Bearer anahtarlarıyla çalışır. Google OAuth belirteçleriniz veya yönetici parolalarınız asla dış dünyaya açılmaz.
Refleks panelinde şube detayındaki Web Vitrin Ayarları sekmesinden yayın durumunu published yapın.
Entegrasyonlar & API ekranından rfx_live_... anahtarınızı üretin. Ham anahtar güvenlik gereği tek sefer gösterilir.
Sitenizde yanıtı yerel önbelleğe yazın; değişiklik olduğunda Refleks sitenizi HMAC-SHA256 imzalı webhook ile anında uyarır.
api.omurgasystems.com çağırmayın. API anahtarınızı sunucu tarafında (WordPress, Next.js ISR veya Redis) saklayın ve If-None-Match başlığı ile ETag önbelleklemesi kullanın. Veri değişmediğinde API milisaniyeler içinde 304 Not Modified döner.
curl -i https://api.omurgasystems.com/v1/locations \ -H "Authorization: Bearer rfx_live_a8f9d2e1_ornekAnahtarDegeri" \ -H "Accept: application/json" # Sonraki periyodik kontrollerde ETag göndererek bant genişliği ve kotayı koruyun: curl -i https://api.omurgasystems.com/v1/locations \ -H "Authorization: Bearer rfx_live_a8f9d2e1_ornekAnahtarDegeri" \ -H 'If-None-Match: "9b74c9897bac770ffc029102a200c5de"'
2. REST API Uç Noktaları & Evrensel Mağaza Şeması
Tüm yanıtlar UTF-8 application/json formatındadır. Restoran, kafe, otel, klinik ve perakende ağlarının tamamı aynı standart şema üzerinden servis edilir.
/v1/locations
Yayına onaylanmış tüm açık ve kalıcı kapalı şubeleri listeler.
/v1/locations/{slug_veya_store_id}
Tekil şube vitrin profilini slug veya store_id ile döner.
/v1/health
Kimlik doğrulaması gerektirmeyen canlı ağ geçidi sağlık kontrolü.
| Sorgu Parametresi | Tip | Açıklama |
|---|---|---|
brand | string | Çoklu marka barındıran hesaplarda marka adı filtresi (Growth & Enterprise). |
city | string | İl bazlı filtreleme (ör. İstanbul, İzmir). |
status | string | all (varsayılan), open, closed_temporarily veya closed_permanently. |
updated_since | ISO-8601 | Yalnızca belirtilen tarihten sonra güncellenen şubeleri getirir (delta senkronizasyon). |
{
"ok": true,
"meta": {
"count": 1,
"active_count": 1,
"permanently_closed_count": 0,
"etag": "W/\"rfx-1-9b74c9897bac770ffc029102\"",
"generated_at": "2026-10-29T02:00:00Z"
},
"items": [
{
"location_id": "accounts/101/locations/9901",
"external_code": "104",
"slug": "alacati-carsi",
"previous_slugs": [],
"brand": "Örnek Marka",
"display_name": "Alaçatı Çarşı",
"open_status": "OPEN",
"is_open_for_business": true,
"is_temporarily_closed": false,
"is_permanently_closed": false,
"address": { "formatted": "Alaçatı Mah. Kemalpaşa Cad. No:82 Çeşme / İzmir", "district": "Çeşme", "city": "İzmir", "country_code": "TR" },
"coordinates": { "lat": 38.2829, "lng": 26.3765 },
"contact": { "phone": "0232 716 66 00", "email": "[email protected]", "website_url": "https://ornekmarka.com" },
"google": { "place_id": "ChIJ...", "maps_url": "https://maps.google.com/?cid=...", "rating_average": 4.6, "review_count": 1240 },
"hours": {
"timezone": "Europe/Istanbul",
"display_text": "08:30 - 01:00",
"weekly": [{ "day": "MONDAY", "day_tr": "Pazartesi", "is_closed": false, "open": "08:30", "close": "01:00" }],
"special": []
},
"storefront": {
"venue_category": "street",
"action_links": { "menu_url": "https://menu.ornekmarka.com", "order_url": null, "reservation_url": null },
"accepted_payments": ["Multinet", "Pluxee (Sodexo)", "Edenred (Ticket)", "Setcard", "MetropolCard"],
"amenities": ["oyun-alani", "wifi", "teras"],
"custom_fields": {}
},
"content_hash": "e3b0c44298fc1c149afbf4c8996fb924",
"updated_at": "2026-10-29T01:45:00Z"
}
]
}
draft_pending). Kalıcı kapanan şubeler ise URL otoritesini (404 kaybını) önlemek için open_status: "CLOSED_PERMANENTLY" olarak döner; bu sayfalarda HTTP 200 koruyup Haversine GPS formülüyle en yakın açık şubeleri önermeniz tavsiye edilir. Ayrıca google.rating_average ve google.review_count verisini kartlarda görsel yıldız basmadan doğrudan Schema.org/Restaurant veya LocalBusiness JSON-LD (aggregateRating) içinde kullanabilirsiniz.
3. Anlık Webhook Olayları & HMAC-SHA256 İmza Doğrulama
Şube çalışma saati, telefon, QR menü bağlantısı veya yayın durumu değiştiğinde Refleks içerik özetini (content_hash) hesaplar ve yalnızca gerçek değişikliklerde hedef HTTPS adresinize imzalı POST isteği gönderir.
| HTTP Başlığı / Olay | Açıklama |
|---|---|
X-Refleks-Event | location.published, location.updated, location.status_changed, location.unpublished veya ping. |
X-Refleks-Timestamp | İsteğin üretildiği Unix saniye zaman damgası. Tekrarlama (replay) saldırılarına karşı ±300 saniye tolerans kontrolü yapın. |
X-Refleks-Signature-256 | sha256= önekiyle HMAC-SHA256(signing_secret, timestamp + "." + raw_body) özeti. |
<?php
$rawBody = file_get_contents('php://input');
$timestamp = $_SERVER['HTTP_X_REFLEKS_TIMESTAMP'] ?? '';
$signature = $_SERVER['HTTP_X_REFLEKS_SIGNATURE_256'] ?? '';
$secret = getenv('REFLEKS_WEBHOOK_SECRET'); // whsec_...
if (abs(time() - (int) $timestamp) > 300) {
http_response_code(401);
exit('Expired timestamp');
}
$expected = 'sha256=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
// İmza doğrulandı: yerel mağaza önbelleğini /v1/locations üzerinden yenileyin
http_response_code(200);
echo json_encode(['received' => true]);
4. Paket Kotaları, Hız Limitleri & Üretim Güvenliği
Storefront API erişimi ve anlık webhook kapasitesi Omurga Refleks abonelik paketinize göre otomatik tanımlanır. Tüm yanıtlarda X-RateLimit-Limit ve X-RateLimit-Remaining başlıkları döner.
| Özellik / Kota | Butik & Yerel | Pro | Büyüyen Zincirler | Enterprise Franchise |
|---|---|---|---|---|
REST Pull API (/v1/locations) |
— | ✓ Aktif | ✓ Aktif | ✓ Aktif |
| Anlık Outbound Webhooks | — | — (Polling / Cron) | ✓ 2 Hedef URL | ✓ 10 Hedef URL |
| Aktif API Anahtarı & Hız Limiti | — | 1 Anahtar • 30 istek/dk | 2 Anahtar • 60 istek/dk | Sınırsız • 300 istek/dk |
| Marka Bazlı İzolasyon (Brand Scope) | — | — | ✓ Marka Seçimli Anahtar | ✓ Çoklu Marka & Holding |
| Kesintisiz Anahtar Rotasyonu & IP Kısıtı | — | Anlık İptal | Anlık İptal | ✓ 24 Saat Çift Anahtar & IP Allowlist |
🛡️ Anti-Wipeout Sigortası
CMS entegrasyonunuzda aktif şube sayısının tek seferde %20'den fazla düşmesi halinde yerel önbelleği silmek yerine yönetici uyarısı üretin; previous_slugs dizisini otomatik 301 yönlendirmesine bağlayın.
🔑 Sıfır Kesintili Anahtar Yenileme
Enterprise paketinde anahtar yenilediğinizde eski anahtarınız 24 saat boyunca geçerliliğini korur; böylece CI/CD ve sunucu ortam değişkenlerinizi sıfır kesintiyle güncelleyebilirsiniz.
Web Sitenizi Refleks Omurgasına Bağlamaya Hazır mısınız?
Refleks panelinizden saniyeler içinde API anahtarınızı üretin veya teknik ekibimizle birlikte kurulum yapın.