Skip to main content
🛡️ Enterprise Infrastructure: The central nervous system for multi-branch brands. Sign Up Free for 14 Days →
⚡ OMURGA STOREFRONT API v1.0

Single-Source Storefront & Store Locator Synchronization

Instantly stream all your branch, address, business hours, GPS coordinate, payment option, cover photo, and amenity data from Google Business Profile and Omurga Refleks to your corporate website (WordPress, Next.js, mobile app, or ERP) with zero duplicate work.

● LIVE GATEWAY https://api.omurgasystems.com/v1
PROTOCOL ARCHITECTURE ● 200 OK • v1.0
  • Authentication Read-Only Bearer (SHA-256)
  • Caching & Latency ETag / 304 (<15ms)
  • Real-Time Event Delivery HMAC-SHA256 + 4x Retry
  • Branch Media Optimization GBP → WebP (960/480/320w)
  • Rate Limiting Layer Redis Sliding-Window

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.

STEP 1 Approve Branches for Publishing

From the Refleks Branches list or the Storefront Settings tab in branch details, approve the status as published to go live.

STEP 2 Generate an API Key

Integrations & API — generate your rfx_live_... key from this screen. For security, the raw secret is displayed only once.

STEP 3 Connect ETag & Webhooks

Cache the response locally on your server; whenever data changes, Refleks notifies your site immediately via an HMAC-SHA256 signed webhook.

Performance Golden Rule (Zero TTFB Overhead): Never call 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 — Initial Request & ETag Cache Validation
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.

GET /v1/locations Bearer Lists all approved active and permanently closed branches.
GET /v1/locations/{slug_veya_store_id} Bearer Returns a single branch storefront profile by slug or store_id identifier.
GET /v1/media/{tenant_id}/{filename} Public CDN Serves responsive GBP-optimized .webp (960w, -480w, -320w) branch cover images.
GET /v1/health Public Unauthenticated live gateway health check.
Query Parameter Type Description
brandstringBrand name filter for multi-brand accounts (Growth & Enterprise).
citystringCity filter (e.g., Istanbul, Izmir).
statusstringall (default), open, closed_temporarily or closed_permanently.
updated_sinceISO-8601Returns only branches updated after the given timestamp (delta sync).
Sample Response — 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",
        "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"
    }
  ]
}
SEO & UX Architecture Tip: Newly discovered Google Business Profile locations never appear in the API without your explicit approval (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-Eventlocation.published, location.updated, location.status_changed, location.unpublished or ping.
X-Refleks-DeliveryUnique delivery identifier for idempotent processing and tracing (e.g., whd_91f0c2...).
X-Refleks-TimestampUnix timestamp (in seconds) when the request was generated. Enforce a ±300-second tolerance window against replay attacks.
X-Refleks-Signature-256sha256= prefixed HMAC-SHA256(signing_secret, timestamp + "." + raw_body) digest.
Automatic Retry & ReplayIf 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.

Ready to Connect Your Website to the Refleks Backbone?

Generate your API key in seconds from your Refleks dashboard or onboard together with our engineering team.