Push Ölçüm API'si

Hedef Kitle: Admin, Geliştirici
Sayfa Tipi: Nasıl Yapılır + Referans
Plan Özelliği: kpi_push_measurement (tenant'ınız için etkin olmalıdır)

---

Genel Bakış

Push Ölçüm API'si, dış sistemlerin API anahtarları ile kimlik doğrulaması yaparak doğrudan COS'a KPI ölçümleri göndermesini sağlar. Pull modelinden farklı olarak (COS'un API'lerinizden veri çektiği model), Push modeli CI/CD pipeline'larınızın, cron job'larınızın veya uygulamalarınızın hazır olduğunda ölçüm göndermesine izin verir.

Nasıl Çalışır

Dış Sistem                               COS
──────────                         ─────────────
                                   
  Uygulamanız / CI/CD  ──POST──►  /integrations/push/measurement
  (x-api-key ile)                    │
                                     ├─ API anahtarını doğrula
                                     ├─ KPI sahipliğini kontrol et
                                     └─ Ölçümü yaz

---

Ön Koşullar

1. Plan Özelliği: kpi_push_measurement etkin olmalı
2. API Anahtarı: Tenant'ınız için en az bir aktif API anahtarı
3. KPI ID: Ölçüm göndermek istediğiniz KPI'nın UUID'si
4. KPI Tipi: Desteklenen KPI varlık tiplerinden biri

Desteklenen KPI Tipleri

Tip	Açıklama
SWOT_KPI	SWOT Analizi KPI'sı
PESTLE_KPI	PESTLE Analizi KPI'sı
THEME_KPI	Stratejik Tema KPI'sı
KPI_DEFINITION	Bağımsız KPI Tanımı
BSC_KPI	Balanced Scorecard KPI'sı
ASIS_KPI	Mevcut Durum Analizi KPI'sı
OKR_KEY_RESULT	OKR Anahtar Sonucu
PRODUCT_SCORECARD_KPI	Ürün Scorecard KPI'sı

---

API Anahtarlarını Yönetme

API Anahtarı Oluşturma

COS kenar çubuğunda Platform → API Anahtarları bölümüne gidin veya /platform/api-keys adresine gidin.

1. Yeni API Anahtarı düğmesine tıklayın
2. Açıklayıcı bir isim girin (ör: "CI/CD Pipeline", "İzleme Sistemi")
3. İsteğe bağlı olarak bir son kullanma tarihi belirleyin
4. Oluştur düğmesine tıklayın
5. Anahtarı hemen kopyalayın — tekrar gösterilmeyecektir

warning

API anahtarları yalnızca oluşturma anında gösterilir. Anahtarı güvenli bir yerde saklayın (ör: secrets manager veya environment variable). Anahtarı kaybederseniz yeni bir tane oluşturmanız gerekir.

API Anahtarını İptal Etme

Bir anahtar tehlikeye girdiyse veya artık gerekmiyorsa, anahtar satırındaki silme düğmesine tıklayın ve onaylayın. İptal edilen anahtarlar tekrar etkinleştirilemez.

Plan Limitleri

Plan	Maks API Anahtarı
Free	3
Business	5
Enterprise	Sınırsız

---

Ölçüm Gönderme

Tekli Ölçüm

curl -X POST https://cos-adresiniz.com/api/integrations/push/measurement \
  -H "x-api-key: cos_api_anahtariniz" \
  -H "Content-Type: application/json" \
  -d '{
    "kpiId": "kpi-uuid-buraya",
    "kpiType": "KPI_DEFINITION",
    "actual": 85.5,
    "target": 100,
    "periodStart": "2025-06-01T00:00:00Z",
    "periodEnd": "2025-06-30T23:59:59Z"
  }'

Toplu Ölçüm (en fazla 50)

curl -X POST https://cos-adresiniz.com/api/integrations/push/measurements/batch \
  -H "x-api-key: cos_api_anahtariniz" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": [
      {
        "kpiId": "kpi-uuid-1",
        "kpiType": "KPI_DEFINITION",
        "actual": 85.5,
        "target": 100,
        "periodStart": "2025-06-01T00:00:00Z",
        "periodEnd": "2025-06-30T23:59:59Z"
      },
      {
        "kpiId": "kpi-uuid-2",
        "kpiType": "BSC_KPI",
        "actual": 42,
        "periodStart": "2025-06-01T00:00:00Z",
        "periodEnd": "2025-06-30T23:59:59Z"
      }
    ]
  }'

İstek Alanları

Alan	Tip	Zorunlu	Açıklama
kpiId	string	✅	KPI'nın UUID'si
kpiType	string	✅	KPI varlık tipi (yukarıdaki tabloya bakın)
actual	number	✅	Gerçekleşen ölçüm değeri
target	number	❌	Dönem için hedef değer
forecast	number	❌	Tahmin değeri
periodStart	string	❌	ISO 8601 tarih. Varsayılan: mevcut ayın başlangıcı
periodEnd	string	❌	ISO 8601 tarih. Varsayılan: mevcut ayın sonu

---

Kod Örnekleri

Python

import requests

API_KEY = "cos_api_anahtariniz"
BASE_URL = "https://cos-adresiniz.com/api"

response = requests.post(
    f"{BASE_URL}/integrations/push/measurement",
    headers={
        "x-api-key": API_KEY,
        "Content-Type": "application/json",
    },
    json={
        "kpiId": "kpi-uuid-buraya",
        "kpiType": "KPI_DEFINITION",
        "actual": 85.5,
        "target": 100,
    },
)

print(response.status_code, response.json())

JavaScript / Node.js

const API_KEY = 'cos_api_anahtariniz';
const BASE_URL = 'https://cos-adresiniz.com/api';

const response = await fetch(`${BASE_URL}/integrations/push/measurement`, {
  method: 'POST',
  headers: {
    'x-api-key': API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    kpiId: 'kpi-uuid-buraya',
    kpiType: 'KPI_DEFINITION',
    actual: 85.5,
    target: 100,
  }),
});

const data = await response.json();
console.log(data);

---

Kimlik Doğrulama

Tüm Push API istekleri, geçerli ve aktif bir API anahtarı ile x-api-key header'ını içermelidir.

Hata Yanıtları

Durum	Anlamı
401	Eksik veya geçersiz API anahtarı
403	Anahtar iptal edilmiş, süresi dolmuş veya tenant pasif
400	Geçersiz istek gövdesi (doğrulama hatası)
404	KPI bulunamadı veya tenant'a ait değil
429	İstek limiti aşıldı

Güvenlik Notları

• API anahtarları depolama öncesi hash'lenir (SHA-256) — COS ham anahtarları asla saklamaz
• Anahtarlar yönetim için 8 karakterlik ön ek (cos_xxxx) ile tanımlanır
• lastUsedAt her başarılı istekte güncellenir
• Anahtarları düzenli olarak döndürmek için son kullanma tarihi belirleyin
• Tehlikeye giren anahtarları hemen iptal edin

---

Uygulama İçi Push Kod Parçacığı

Bir KPI detay çekmecesini görüntülerken, Push API bölümü (kpi_push_measurement etkinken görünür) KPI ID ve tipi önceden doldurulmuş kullanıma hazır kod parçacıkları sunar. Sadece YOUR_API_KEY kısmını gerçek anahtarınızla değiştirin.

---

Push vs Pull Karşılaştırması

Özellik	Push API	Pull Entegrasyonu
Yön	Dış Sistem → COS	COS → Dış Sistem
Kimlik Doğrulama	API Anahtarı (x-api-key)	JWT + yapılandırılmış endpoint
Zamanlama	İsteğe bağlı (çağıran karar verir)	Cron tabanlı (COS zamanlayıcısı)
Kurulum	API anahtarı oluştur, HTTP POST gönder	Endpoint + binding yapılandır
Plan Özelliği	kpi_push_measurement	kpi_api_integration
En İyi Kullanım	CI/CD, olay güdümlü, webhook	Dış API'lerin periyodik sorgulanması