Geliştiriciler · API ve webhook

Verin kapalı kutuda durmaz. API, webhook, takvim.

Workout OS ve Workout Studio aynı kurallarla konuşur: anahtarla okunan ve yazılan bir REST API, imzalı webhook'lar, olay akışı ve ICS takvim adresleri. Tüm ücretli paketlerde tam erişim, ücretsiz pakette salt okuma. API'yi büyük paketlere saklamıyoruz.

Entegrasyon için yaz

REST API

Üye/danışan, üyelik/paket, ödeme, ders ve rezervasyon, katılım. İmleçli sayfalama, updated_since ile artımlı eşitleme, tutarlar kuruş cinsinden.

İmzalı webhook

Olay başına abonelik, HMAC SHA-256 imza, 7 denemeli yeniden gönderim, ölü mektup kutusu ve tek tıkla yeniden gönder.

Takvim (ICS)

Eğitmen ve üye için gizli takvim adresi: dersler ve randevular Google, Apple ya da Outlook takvimine düşer.

OpenAPI 3.1

Makine okunur belge API'nin kendisinden anahtarsız alınır; şemalar API'nin doğrulamada kullandığı şemalardan üretilir.

Hangi pakette ne var?

Plan farkı yalnızca hız sınırında. Yazma yetkileri ve webhook'lar tüm ücretli paketlerde açık.

Paket	API	Webhook	İstek / dakika / anahtar
Ücretsiz (Salon ve Stüdyo)	Salt okuma	Yok (olay akışını sorgula)	60
Salon, Pro · Solo, Stüdyo	Tam (okuma + yazma)	Var	600
Zincir · Stüdyo+	Tam (okuma + yazma)	Var	1200

Ücretsiz pakete dönersen hiçbir şey silinmez: yazma anahtarları okumaya devam eder, yazma istekleri 403 plan_read_only döner, webhook'lar durur.

Yetkiler (scope)

Anahtar Ayarlar → Entegrasyonlar'da oluşturulur, bir kez gösterilir ve yalnızca SHA-256 özeti saklanır. Authorization: Bearer ile gönderilir; her anahtar yalnızca kendi işletmesini görür.

Workout OS (wosk_…)

read:members: Üyeler, kapı erişim beslemesi, member.* ve success.* olayları
read:contact: Üyelere telefon ve e-posta ekler (gizlilik kısıtlı üyelerde asla)
read:memberships: Üyelikler ve membership.* olayları
read:payments: Ödemeler ve üyelik tutarları
read:classes: Ders türleri, seanslar, rezervasyonlar ve booking.* olayları
read:attendance: Girişler ve attendance.recorded olayları
write:members: Üye oluştur ve güncelle
write:payments: Elle ödeme kaydı: nakit, kart (POS), havale
write:bookings: Derse kaydet ve iptal et
write:events: Kapı sisteminden giriş olayı

Workout Studio (wstk_…)

read:clients: Danışanlar (iletişim bilgisi olmadan)
read:contact: Telefon ve e-posta; telefonla ya da e-postayla arama
read:packages: Paketler ve paket türleri
read:bookings: Hizmetler, eğitmenler, seanslar, rezervasyonlar, etkinlikler
read:payments: Ödemeler; paket ve bilet tutarları
write:clients: Danışan oluştur ve güncelle
write:bookings: Rezervasyon oluştur ve iptal et
write:payments: Elle ödeme kaydı: nakit, kart (POS), havale

Sağlık verisi (formlar, cevaplar, ölçümler), personel notları, doğum tarihi ve fotoğraf API'den hiçbir zaman dönmez.

Olaylar

Her olay, değişiklikle aynı veritabanı işleminde kaydedilir (outbox): kaydedilen değişiklik olayını kaybetmez. Webhook yerine olay akışını da sorgulayabilirsin (30 gün saklanır, her pakette).

Workout OS

member.created
member.updated
membership.created
membership.renewed
membership.frozen
membership.expired
membership.cancelled
payment.recorded
booking.created
booking.cancelled
attendance.recorded
access.status_changed
success.case_opened

Workout Studio

client.created
client.updated
package.sold
package.renewed
package.expired
booking.created
booking.cancelled
booking.attended
booking.no_show
payment.recorded
event_ticket.created
event_ticket.cancelled
success.case_opened

Olay zarfı (iki üründe aynı)

{
  "id": "0b6f0a52-6a1e-4a8e-9f1e-3c4f0d3a2b11",
  "type": "payment.recorded",
  "created_at": "2026-10-23T14:02:00.000Z",
  "tenant_id": "730c3ef8-…",
  "api_version": "2026-10-23",
  "data": { "payment": { "id": "…", "amountKurus": 50000, "currency": "TRY", "method": "cash" } }
}

Headers

X-WorkoutOS-Event: payment.recorded
X-WorkoutOS-Delivery: <delivery uuid>
Idempotency-Key: <event id>
X-WorkoutOS-Signature: t=1761228120,v1=<hex>

İmza doğrulama

v1 = HMAC_SHA256(gizli anahtar, "<t>.<ham gövde>"), küçük harf hex. Ham gövde baytlarıyla, sabit zamanlı karşılaştırmayla doğrula; 5 dakikadan eski zaman damgasını reddet.

İmza anahtarı (whsec_…) bir kez gösterilir, istediğin an yenilenir; yenileme sırasında başlıkta birden fazla v1 olabilir
Idempotency-Key = olay kimliği: her uç ve her yeniden denemede aynıdır, mükerreri bununla ele
Teslimatlar birden fazla ve sırasız gelebilir: created_at ile sırala

Node.js

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(secret, rawBody, header, toleranceSec = 300) {
  const t = /(?:^|,)t=(\d+)/.exec(header ?? "")?.[1];
  const sigs = [...(header ?? "").matchAll(/v1=([0-9a-f]{64})/g)].map((m) => Buffer.from(m[1], "hex"));
  if (!t || sigs.length === 0 || Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  return sigs.some((s) => s.length === expected.length && timingSafeEqual(s, expected));
}

Teslim güvencesi

10 saniye içinde 2xx dönmezse 1 dk, 5 dk, 30 dk, 2 sa, 6 sa ve 24 sa sonra yeniden denenir (7 deneme)
Sonra ölü mektup kutusuna düşer; tek teslimatı ya da tüm başarısızları tek tıkla yeniden gönderirsin
Uç 1 saat boyunca hata verirse sahibe bildirim gider; 3 gün kesintisiz hatada uç kendiliğinden kapanır
Entegrasyon sağlığı ekranı: 24 saat / 7 gün başarı oranı, bekleyen ve başarısız sayısı, son hata kodu

Yazmada Idempotency-Key

Her yazma isteği Idempotency-Key başlığı ister (1–255 görünür karakter, ör. kendi sipariş numaran). Anahtar işletme başına 24 saat saklanır.

Aynı anahtar + aynı istek: ilk yanıt aynen döner, Idempotent-Replayed: true
Aynı anahtar + farklı gövde: 422 idempotency_key_reused
Aynı anda gelen iki istek: ikincisi birincinin sonucunu bekler, tek kayıt yazılır
Başarısız istek anahtarı harcamaz: düzeltip aynı anahtarla yeniden dene

Hız sınırı

Her yanıt IETF RateLimit başlıklarını taşır; sınır aşılınca 429 rate_limited ve Retry-After döner.

RateLimit-Limit: 600
RateLimit-Remaining: 597
RateLimit-Reset: 41
RateLimit-Policy: 600;w=60

Takvim beslemesi (ICS)

Eğitmen kendi derslerini ve seanslarını, üye ya da danışan kendi rezervasyonlarını takvim uygulamasına ekler. Her pakette.

RFC 5545, saatler UTC, işletmenin saat dilimi X-WR-TIMEZONE ile
İptal edilen rezervasyon STATUS:CANCELLED, bekleme listesi TENTATIVE
Son 30 gün ile önümüzdeki 180 gün
Adres gizlidir; yenilenince eskisi hemen geçersiz olur

Kapı ve turnike sistemleri (Salon)

Donanım satmıyoruz; salonun mevcut kapı sistemi yazılım düzeyinde bağlanır. Erişim durumu, resepsiyondaki elle giriş kuralıyla aynı karardan gelir.

Erişim listesi: allowed, expired, frozen, debt, blocked
Artımlı değişiklikler ve access.status_changed webhook'u
Kapıdan giriş olayı yazma: ziyaret geçmişine, otomasyonlara ve raporlara düşer
Elle yükleme için izinli üyeler CSV'si

Belgeler

OpenAPI 3.1 belgesi her işletmenin API adresinde /v1/external/openapi.json yolundan anahtarsız alınır; adres panelde Ayarlar → Entegrasyonlar'da yazar. Herkese açık geliştirici belgeleri hazırlanıyor; o zamana kadar örnek istekler ve kurulum için bize yaz.

Postman, Insomnia ya da openapi-generator ile istemci üretebilirsin
Zapier ve Make: webhook ile bağlanır
Hata biçimi: { statusCode, code, message, fields? }, mesaj işletmenin dilinde

Sık sorulanlar

API hangi paketlerde var?

Tüm ücretli paketlerde tam erişim (okuma, yazma, webhook). Ücretsiz pakette salt okuma: veriyi okuyabilir ve olay akışını sorgulayabilirsin. Paketler arasındaki tek fark hız sınırı.

API kullanmak ek ücretli mi?

Hayır. API, webhook ve takvim beslemesi paket fiyatına dahildir.

Kapı ya da turnike sistemimi bağlayabilir miyim?

Evet, yazılım düzeyinde. Kapı sistemin erişim listesini ve değişiklikleri API ya da webhook ile alır, girişleri geri bildirir. Donanım satmıyor ve kurmuyoruz.

Sağlık verisi API'den çıkar mı?

Hayır. Sağlık formları, ölçümler, personel notları, doğum tarihi ve fotoğraf API'den hiçbir zaman dönmez. İletişim bilgisi ayrı bir yetki ister.

Webhook ulaşmazsa ne olur?

7 kez yeniden denenir, sonra ölü mektup kutusuna düşer ve panelden yeniden gönderilir. Olaylar ayrıca 30 gün olay akışında durur.

Muhasebe programıma doğrudan bağlanıyor mu?

Doğrudan bağlantı yok. Raporlar → Muhasebe'den yevmiye, hareket listesi, Xero ya da QuickBooks CSV'si indirilir. e-Fatura entegrasyonu değildir.

Demo

İşletmeni 20 dakikada gösterelim.

Salon mu, stüdyo mu, ikisi birden mi? Kendi verinle gösterelim. Taahhüt yok.

Demo iste Fiyatları gör WhatsApp'tan yazın