API Genel Bakış
Hedef Kitle: Entegrasyon geliştirenler ve uygulama yöneticileri
Adres ve kimlik doğrulama
Kurulumunuzun yapılandırılmış API taban adresini kullanın. Aşağıdaki yollar bu adrese göredir; web uygulamasının adresine kendiliğinden /api veya /api/v1 eklemeyin.
Korumalı kullanıcı çağrılarında Authorization: Bearer <access_token>, şirket kapsamlı çağrılarda ayrıca X-Tenant-ID: <tenant_id> gerekir. Kullanıcı yalnız yetkili olduğu şirket ve kayıtlara erişir; başlığa bir şirket kimliği yazmak erişim sağlamaz. JSON gönderirken Content-Type: application/json kullanın.
Kimlik doğrulama rehberi giriş, refresh cookie, şirket değiştirme ve çıkışı açıklar. Push Ölçüm API'si ise ayrı x-api-key kullanır; push anahtarı kullanıcı JWT'sinin yerine geçmez.
Sık kullanılan çağrılar
| Yöntem | Yol | İşlem |
|---|---|---|
| POST | /auth/login | E-posta/şifre ile access token ve refresh oturumu |
| POST | /auth/session | HttpOnly refresh cookie ile yeni access token |
| POST | /auth/refresh | Hâlâ geçerli access token ile yenileme |
| POST | /auth/logout | Geçerli token ve refresh oturumunu sonlandırma |
| POST | /auth/session/logout | Refresh oturumunu access token olmadan sonlandırma |
| GET | /auth/profile | Hesap ve üyelik bağlamı |
| POST | /auth/switch-tenant | Yetkili şirkete geçiş |
| GET | /plans/resource-usage | Şirketin kaynak kullanımı ve limitleri |
| GET | /plans/effective/:groupId | Grubun etkin yetkileri |
| GET | /plans/my-groups | Kullanıcının gruplarının etkin yetkileri |
| GET | /kpis | KPI Kaydı listesi |
| POST | /kpis | KPI oluşturma |
| GET / PATCH / DELETE | /kpis/:id | KPI detayı / güncelleme / silme |
| POST | /kpis/:id/retire, /kpis/:id/reactivate | Emekliye ayırma / yeniden etkinleştirme |
| GET / POST | /kpis/:id/measurements | Ölçümleri listeleme / ekleme |
| PATCH / DELETE | /kpis/:id/measurements/:measurementId | Ölçümü güncelleme / silme |
| GET | /kpis/:id/usages, /kpis/:id/audit | Rapor kullanımları / KPI geçmişi |
| PUT | /kpis/:id/success-criteria | Başarı kriterini sürüm kontrolüyle kaydetme |
| GET / POST | /kpi-usages/:parentType/:parentId | Raporun KPI kullanımlarını listeleme / ekleme |
| PUT | /kpi-usages/:parentType/:parentId/weights | Rapor ağırlıklarını güncelleme |
| PATCH / DELETE | /kpi-usages/:parentType/:parentId/:usageId | Tek kullanımı güncelleme / kaldırma |
| GET | /reports/performance/units, /reports/performance/persons, /reports/performance/my | Yetki kapsamındaki performans raporları |
| GET | /dashboard/admin, /dashboard/unit-leader, /dashboard/member, /dashboard/strategy-compass | Rol ve kayıt kapsamı uygulanan pano verileri |
| GET | /ai-assistant/models, /ai-assistant/agents | Kullanılabilir model ve agent seçenekleri |
| GET / POST | /ai-assistant/conversations | Kendi sohbetlerini listeleme / oluşturma |
| GET / PATCH / DELETE | /ai-assistant/conversations/:id | Kendi sohbetini okuma / düzenleme / silme |
| POST | /ai-assistant/agui/:agentId | AG-UI isteği; cevap JSON yerine SSE olay akışıdır |
| POST | /ai-assistant/conversations/:id/cancel | Etkin sohbet çalışmasını durdurma |
Listedeki her yöntem yalnız yazıldığı yolda geçerlidir. :id gibi yer tutucuları gerçek kimlikle değiştirin. Liste, her kaynağın bütün alt işlemlerini içermez.
Modül yollarını bulma
Organizasyon /org, ürünler /products, plan dönemleri /strategic-cycles, misyon/vizyon /mission-vision, durum raporları /current-states, analizler /resources-vrio, /pestle, /porter-5, /bcg-matrix, /digital-maturity, /excellence-assessments, /product-scorecard, /findings; SWOT /swot, odak alanları /strategic-themes, OKR /new-okr öneklerindedir. Bunlar modül önekleridir; her önekte aynı GET/POST/PATCH işlemleri bulunduğu anlamına gelmez.
Süper Yönetici SaaS'ta yetki kataloğunu GET /admin/entitlements/catalog, grupları GET /admin/entitlements/sets, tek seti GET/PUT /admin/entitlements/sets/:groupId ile yönetir. Kaydetmede güncel expectedVersion gerekir; eşzamanlı değişiklik 409 ile reddedilir. On-prem kurulumda set yönetimi kapalıdır; lisans ve dosyadaki katalog kullanılır.
Geliştirme/staging ortamında /api Swagger arayüzü yöntem, body, sorgu parametreleri ve yanıt şemalarını gösterir; üretimde bu arayüz kapalıdır.
Hatalar ve işlem güvenliği
- 400: Alan/format veya iş kuralı hatası; cevap açıklamasını kontrol edin.
- 401: Oturum veya token geçersiz. Geçerli refresh cookie varsa oturumu yenileyin.
- 403: Rol, şirket/kayıt kapsamı, menü, modül veya kurulum lisansı nedeniyle erişim yok.
- 404: Kaynak bulunamadı veya bu kapsamda erişilemiyor.
- 409: Sürüm/eşzamanlı değişiklik çakışması; güncel veriyi okuyup yeniden değerlendirin.
- 422: Kaynak limiti gibi iş kuralı engeli.
- 429: Ucun hız sınırı aşıldı. Sınırlar uca ve yapılandırmaya göre değişir.
Başarısız yazma isteğini sonucu bilinmeden körlemesine tekrar göndermeyin; çift kayıt/ölçüm riskini ilgili uç sözleşmesine göre yönetin. Hata yanıtındaki code ve message alanlarını saklarken token veya gizli anahtarları kayda eklemeyin.