Ana İçeriğe Geç
🛡️ Kurumsal Altyapı: Çok şubeli zincir markaların merkezi sinir sistemi. 14 Gün Ücretsiz Kayıt Olun →
⚡ OMURGA STOREFRONT API v1.0

Tek Kaynaktan Web Vitrini & Şube Haritası Senkronizasyonu

Google Business Profile ve Omurga Refleks üzerindeki tüm şube, adres, çalışma saati, koordinat, yemek kartı ve olanak verilerinizi kurumsal web sitenize (WordPress, Next.js, mobil uygulama veya ERP) çift iş yapmadan anlık aktarın.

CANLI GATEWAY https://api.omurgasystems.com/v1
Refleks'te API Anahtarı Üret → 5 Dk Hızlı Başlangıç ↓

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.

ADIM 1
Şubeleri Yayına Onaylayın

Refleks panelinde şube detayındaki Web Vitrin Ayarları sekmesinden yayın durumunu published yapın.

ADIM 2
API Anahtarı Oluşturun

Entegrasyonlar & API ekranından rfx_live_... anahtarınızı üretin. Ham anahtar güvenlik gereği tek sefer gösterilir.

ADIM 3
ETag & Webhook Bağlayın

Sitenizde yanıtı yerel önbelleğe yazın; değişiklik olduğunda Refleks sitenizi HMAC-SHA256 imzalı webhook ile anında uyarır.

Performans Altın Kuralı (Sıfır TTFB Yükü): Son kullanıcı tarayıcısından doğrudan 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 — İlk İstek & ETag Önbellek Kontrolü
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.

GET /v1/locations Yayına onaylanmış tüm açık ve kalıcı kapalı şubeleri listeler.
GET /v1/locations/{slug_veya_store_id} Tekil şube vitrin profilini slug veya store_id ile döner.
GET /v1/health Kimlik doğrulaması gerektirmeyen canlı ağ geçidi sağlık kontrolü.
Sorgu Parametresi Tip Açıklama
brandstringÇoklu marka barındıran hesaplarda marka adı filtresi (Growth & Enterprise).
citystringİl bazlı filtreleme (ör. İstanbul, İzmir).
statusstringall (varsayılan), open, closed_temporarily veya closed_permanently.
updated_sinceISO-8601Yalnızca belirtilen tarihten sonra güncellenen şubeleri getirir (delta senkronizasyon).
Örnek Yanıt — GET /v1/locations
{
  "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"
    }
  ]
}
SEO & UX Mimari Önerisi: Yeni keşfedilen Google Business Profile lokasyonları onayınız olmadan API'ye düşmez (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-Eventlocation.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-256sha256= ö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.

API Anahtarı Oluştur → Paketleri Karşılaştır