1. 5-Minute Quickstart & Authentication
Omurga Storefront API operates exclusively with read-only and tenant-isolated Bearer keys. Your Google OAuth tokens and admin credentials are never exposed externally.
From the Refleks Branches list or the Storefront Settings tab in branch details, approve the status as published to go live.
Integrations & API — generate your rfx_live_... key from this screen. For security, the raw secret is displayed only once.
Cache the response locally on your server; whenever data changes, Refleks notifies your site immediately via an HMAC-SHA256 signed webhook.
api.omurgasystems.com directly from end-user browsers. Store your API key server-side (WordPress, Next.js ISR, or Redis) and pass the If-None-Match header for ETag caching. When data is unchanged, the API returns 304 Not Modified within milliseconds.
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 kotayı koruyun: curl -i https://api.omurgasystems.com/v1/locations \ -H "Authorization: Bearer rfx_live_a8f9d2e1_ornekAnahtarDegeri" \ -H 'If-None-Match: "W/\"rfx-1-9b74c9897bac770ffc029102\""'
2. REST API Endpoints & Universal Storefront Schema
All responses are served in UTF-8 application/json format. Restaurant, café, hotel, clinic, and retail networks are all served through the same standardized schema.
/v1/locations
Bearer
Lists all approved active and permanently closed branches.
/v1/locations/{slug_veya_store_id}
Bearer
Returns a single branch storefront profile by slug or store_id identifier.
/v1/media/{tenant_id}/{filename}
Public CDN
Serves responsive GBP-optimized .webp (960w, -480w, -320w) branch cover images.
/v1/health
Public
Unauthenticated live gateway health check.
| Query Parameter | Type | Description |
|---|---|---|
brand | string | Brand name filter for multi-brand accounts (Growth & Enterprise). |
city | string | City filter (e.g., Istanbul, Izmir). |
status | string | all (default), open, closed_temporarily or closed_permanently. |
updated_since | ISO-8601 | Returns only branches updated after the given timestamp (delta sync). |
{
"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",
"cover_image_url": "https://api.omurgasystems.com/v1/media/1/branch-9901-a1b2c3d4.webp",
"action_links": {
"menu_url": "https://menu.ornekmarka.com",
"order_url": null,
"reservation_url": null
},
"accepted_payments": ["Multinet", "Pluxee (Sodexo)", "Edenred (Ticket)", "Setcard"],
"amenities": ["oyun-alani", "wifi", "teras"],
"custom_fields": {}
},
"content_hash": "e3b0c44298fc1c149afbf4c8996fb924",
"updated_at": "2026-10-29T01:45:00Z"
}
]
}
draft_pending). Permanently closed branches return open_status: "CLOSED_PERMANENTLY" to preserve SEO URL authority (preventing 404 drops); we recommend keeping HTTP 200 and suggesting nearby open branches via the Haversine GPS formula. You can also embed google.rating_average and google.review_count directly inside Schema.org/LocalBusiness JSON-LD (aggregateRating) without rendering visual star ratings on store cards.
3. Real-Time Webhook Events, Auto-Retry & HMAC-SHA256
Whenever branch hours, phone numbers, cover photos, QR menu links, or publish status change, Refleks computes a content digest (content_hash) and dispatches a signed POST request to your HTTPS endpoint only on genuine data changes.
| HTTP Header / Mechanism | Description |
|---|---|
X-Refleks-Event | location.published, location.updated, location.status_changed, location.unpublished or ping. |
X-Refleks-Delivery | Unique delivery identifier for idempotent processing and tracing (e.g., whd_91f0c2...). |
X-Refleks-Timestamp | Unix timestamp (in seconds) when the request was generated. Enforce a ±300-second tolerance window against replay attacks. |
X-Refleks-Signature-256 | sha256= prefixed HMAC-SHA256(signing_secret, timestamp + "." + raw_body) digest. |
| Automatic Retry & Replay | If the target server does not return 2xx , the persistent delivery queue retries at 30s → 2m → 15m → 1h intervals, with one-click Replay available in the dashboard. |
<?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. Plan Quotas, Rate Limits & Production Safety
Storefront API access and real-time webhook capacity are enforced via a Redis-backed sliding-window layer based on your Omurga Refleks plan. Every response includes X-RateLimit-Limit and X-RateLimit-Remaining headers.
| Feature / Quota | Boutique & Local | Pro | Growing Chains | Enterprise Franchise |
|---|---|---|---|---|
| REST Pull API & WebP Media CDN | — | ✓ Active | ✓ Active | ✓ Active |
| Real-Time Outbound Webhooks & Retry | — | — (Polling / Cron) | ✓ 2 Target URLs | ✓ 10 Target URLs |
| Active API Keys & Rate Limit | — | 1 Key • 30 req/min | 2 Keys • 60 req/min | Unlimited • 300 req/min |
| Brand-Scoped Key Isolation | — | — | ✓ Brand-Scoped Key | ✓ Multi-Brand & Holding |
| Zero-Downtime Key Rotation & IP Allowlist | — | Instant Revoke | Instant Revoke | ✓ 24h Dual-Key Grace & IP Allowlist |
🛡️ Anti-Wipeout Circuit Breaker
If active branch count drops by more than 20% in a single sync, preserve your local cache and alert admins; wire the previous_slugs array to automatic 301 redirects.
🔑 Zero-Downtime Key Rotation
On Enterprise plans, rotating an API key keeps the previous key valid for a 24-hour grace period so you can update CI/CD and server environment variables with zero downtime.
📊 Live Telemetry & Replay
Monitor 24-hour and 7-day 200 OK, 304 Not Modified cache hit ratios, 401/429 security alerts, and webhook delivery logs graphically in Refleks.