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

Plan Özelliği: kpi_push_measurement etkin olmalı
API Anahtarı: Tenant'ınız için en az bir aktif API anahtarı
Hedef kimliği (kpiId): KPI Kaydı'ndaki KPI'ın kimliği (Hedefler & Takip → KPI Takibi, KPI detayı → Entegrasyon sekmesi) veya bir OKR Anahtar Sonucunun kimliği
Hedef tipi (kpiType): KPI veya OKR_KEY_RESULT

Kırıcı değişiklik (0.5.0, ölçüm tarihi)

periodStart, periodEnd ve periodicity alanları kaldırıldı; gönderilirse 400 MEASUREMENT_PERIOD_FIELDS_REMOVED döner. KPI hedefinde measurementDate (YYYY-MM-DD) zorunludur; "bu ay" varsayılanı yoktur. Aynı tarihte kayıt varsa güncellenir. OKR_KEY_RESULT hedefi Anahtar Sonucun gerçekleşen değerini günceller ve tarih almaz.

Kırıcı değişiklik (KPI Kaydı)

kpiType sözleşmesi sadeleşti. Yalnızca iki değer kabul edilir:

Tip	Hedef
`KPI`	KPI Kaydı'ndaki bir KPI (`/kpis`). Raporlar aynı KPI'ı kullandığı için ölçüm, KPI'ı kullanan tüm raporlarda görünür.
`OKR_KEY_RESULT`	OKR Anahtar Sonucu

Eski aile değerleri (THEME_KPI, BSC_KPI, ASIS_KPI, SWOT_KPI, PESTLE_KPI, KPI_DEFINITION, PRODUCT_SCORECARD_KPI vb.) artık 400 döner; uyumluluk katmanı yoktur. Eski rapor bazlı KPI kimlikleri de geçersizdir. Entegrasyonlarınızı KPI Kaydı'ndaki KPI kimliği ve kpiType: "KPI" ile güncelleyin.

Tüm rapor türlerindeki KPI'lar (Porter ve BCG dahil) KPI Kaydı üzerinden push alabilir.

API Anahtarlarını Yönetme

API Anahtarı Oluşturma

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

Yeni API Anahtarı düğmesine tıklayın
Açıklayıcı bir isim girin (ör: "CI/CD Pipeline", "İzleme Sistemi")
İsteğe bağlı olarak bir son kullanma tarihi belirleyin
Oluştur düğmesine tıklayın
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.

API anahtarı sınırı

Anahtar sayısı grubun etkin yetki setindeki max_push_api_keys sınırına tabidir. Hazır seçimin adı tek başına sabit bir sayı belirlemez. Sınır dolduysa kullanılmayan anahtarı iptal edin veya yöneticinizle etkin sınırı inceleyin. İptal etmek anahtarın sonraki çağrılarını engeller.

Ölçüm Gönderme

Örneklerdeki https://your-api-host.example yerine kurulumunuzun API taban adresini kullanın. Web uygulaması adresine otomatik /api eklemeyin; yalnızca API yapılandırmanız bu öneki içeriyorsa kullanın. KPI detayındaki Push API ile Ölçüm Gönder bölümü doğru API adresini, KPI kimliğini ve kpiType değerini doldurur. Tenant kimliği anahtardan belirlenir; isteğe ayrıca tenant veya rapor kimliği eklemeniz gerekmez.

Tekli Ölçüm

curl -X POST https://your-api-host.example/integrations/push/measurement \
  -H "x-api-key: cos_api_anahtariniz" \
  -H "Content-Type: application/json" \
  -d '{
    "kpiId": "kpi-kimligi-buraya",
    "kpiType": "KPI",
    "measurementDate": "2026-09-30",
    "actual": 85.5,
    "target": 100
  }'

Başarılı yanıt: {"success": true, "kpiType": "KPI", "kpiId": "...", "measurementDate": "2026-09-30", "operation": "CREATED", "recordId": "..."}. Aynı tarihte kayıt varsa güncellenir ve operation: "UPDATED" döner.

Toplu Ölçüm (en fazla 50)

curl -X POST https://your-api-host.example/integrations/push/measurements/batch \
  -H "x-api-key: cos_api_anahtariniz" \
  -H "Content-Type: application/json" \
  -d '{
    "measurements": [
      {
        "kpiId": "kpi-kimligi-1",
        "kpiType": "KPI",
        "measurementDate": "2026-09-30",
        "actual": 85.5,
        "target": 100
      },
      {
        "kpiId": "anahtar-sonuc-kimligi-2",
        "kpiType": "OKR_KEY_RESULT",
        "actual": 42
      }
    ]
  }'

İstek Alanları

Alan	Tip	Zorunlu	Açıklama
`kpiId`	`string`	✅	KPI Kaydı'ndaki KPI kimliği veya Anahtar Sonuç kimliği; kütüphane öğesi kimliği değildir
`kpiType`	`string`	✅	`KPI` veya `OKR_KEY_RESULT`
`measurementDate`	`string`	✅ (`KPI`)	Ölçüm tarihi, `YYYY-MM-DD` (saat dilimi yok). Bir KPI'da her tarihe tek kayıt olur; aynı tarih tekrar gönderilirse kayıt güncellenir. `OKR_KEY_RESULT` için gönderilmez (400 `FIELD_NOT_SUPPORTED_FOR_KEY_RESULT`).
`actual`	`number`	✅	Gerçekleşen ölçüm değeri. Sonlu bir JSON sayısı olmalıdır; `"85.5"` gibi metin 400 döner. Anahtar Sonuçta "Gerçekleşen" alanını günceller; ilerleme elle girişteki gibi hesaplanır.
`target`	`number`	❌	Hedef; gönderilmezse, null veya boşsa aynı KPI'ın `measurementDate` tarihinden önceki en yakın ölçümündeki hedef kullanılır. Açıkça gönderilen `0` korunur. Kullanılabilir önceki hedef yoksa `0` olur.
`forecast`	`number`	❌	Tahmin değeri (yalnız `KPI`). Anahtar Sonuç için 400 `FIELD_NOT_SUPPORTED_FOR_KEY_RESULT`.
`statusNote`	`string`	❌	Durum notu
`idempotencyKey`	`string`	❌	Yalnız `KPI`; kırılımlı gönderimde zorunlu. Aynı anahtarı yalnız aynı istek için tekrar kullanın.
`configurationVersion`, `categoryValues`		❌	Yalnız kırılımlı `KPI`. "Kategorilerin toplamı" yönteminde toplam sunucuda hesaplanır ve tüm aktif kategoriler gönderilmelidir (400 `CATEGORY_VALUES_INCOMPLETE`); "Elle girilen toplam" yönteminde `actual` toplamı zorunludur (400 `MANUAL_TOTAL_REQUIRED`).

Anahtar Sonuç gövdesi yalnız {kpiType, kpiId, actual, target?, statusNote?} alanlarını alır; yanıt operation: "UPDATED" ve güncel progress içerir. Onaylı OKR planında saklı değerden farklı bir target 403 OKR_LOCKED döner; gerçekleşen değer güncellenebilir.

Kod Örnekleri

Python

import requests

API_KEY = "cos_api_anahtariniz"
BASE_URL = "https://your-api-host.example"

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

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

JavaScript / Node.js

const API_KEY = 'cos_api_anahtariniz';
const BASE_URL = 'https://your-api-host.example';

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-kimligi-buraya',
    kpiType: 'KPI',
    measurementDate: '2026-09-30',
    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.

Uç nokta dış HTTP istemcilerinden çağrılabilir; anonim istek veya yalnızca oturum JWT'si ile ölçüm gönderilemez. Yetkili kullanıcı COS'a giriş yapıp Ayarlar → API Anahtarları ekranında anahtar oluşturur ve dış sistem bu anahtarı kullanır. Tenant bağlamı anahtardan belirlenir; başka tenant'ın KPI'ına kayıt yapılamaz. Tenant'ın kpi_push_measurement plan özelliği açık olmalıdır.

Önceki hedef yalnızca aynı kpiType ve kpiId hedefinden alınır; ortak kütüphane öğesinden veya başka KPI'dan alınmaz. Önceki ölçüm, gönderilen measurementDate tarihinden önceki en yakın tarihli kayıttır. Ekranda bu hedef önceden doldurulur ve kullanıcı değiştirebilir. İstek alanları ve hedef varsayılanı.

Hata Yanıtları

Tekli istek (/integrations/push/measurement): reddedilen istek HTTP hatası döner ve gövde makine tarafından okunabilir bir errorCode taşır. res.ok kontrol eden istemciler reddedilen ölçümü kabul edilmiş sanmaz.

Durum	`errorCode`	Anlamı
`401`	—	Eksik veya geçersiz API anahtarı
`403`	— / `FORBIDDEN`	Anahtar iptal edilmiş, süresi dolmuş, tenant pasif veya plan özelliği kapalı; (anahtar açıksa) hedefin aktif bağlaması yok; onaylı OKR planında hedef değişikliği (`OKR_LOCKED`) veya pasif birim
`400`	`INVALID`	Geçersiz gövde, sayı yerine metin değer veya desteklenmeyen `kpiType` (eski aile değerleri dahil)
`400`	`MEASUREMENT_PERIOD_FIELDS_REMOVED`	`periodStart`, `periodEnd` veya `periodicity` gönderildi
`400`	`FIELD_NOT_SUPPORTED_FOR_KEY_RESULT`	Anahtar Sonuç için `measurementDate`, `forecast` veya `categoryValues` gönderildi
`400`	`CATEGORY_VALUES_INCOMPLETE` / `MANUAL_TOTAL_REQUIRED`	Kırılımlı gönderimde eksik kategori değeri / eksik elle toplam
`404`	`NOT_FOUND`	KPI veya Anahtar Sonuç bulunamadı ya da anahtarın tenant'ına ait değil
`409`	`KPI_RETIRED`	KPI emekliye ayrılmış; ölçüm kabul edilmez
`409`	`CONFLICT`	Idempotency anahtarı veya kırılım sürümü çakışması
`422`	`CYCLE_LOCKED`	Anahtar Sonucun OKR dönemi kapalı (`CLOSED`/`COMPLETED`)
`429`	—	İstek limiti aşıldı

Toplu istek (/integrations/push/measurements/batch, en fazla 50): her öğe ayrı işlenir. Yanıt 200 döner; total, succeeded, failed sayıları ve öğe başına results içerir. Başarısız öğede success: false, errorCode (INVALID, NOT_FOUND, KPI_RETIRED, CYCLE_LOCKED, CONFLICT, FORBIDDEN, ERROR) ve açıklama bulunur; diğer öğeler yazılmaya devam eder.

{
  "total": 2, "succeeded": 1, "failed": 1,
  "results": [
    { "success": true, "kpiType": "KPI", "kpiId": "kpi-kimligi-1", "measurementDate": "2026-09-30", "operation": "CREATED", "recordId": "..." },
    { "success": false, "kpiType": "OKR_KEY_RESULT", "kpiId": "anahtar-sonuc-kimligi-2", "errorCode": "CYCLE_LOCKED", "error": "..." }
  ]
}

Kurallar

Push, KPI'ı kullanan raporların veya plan döneminin kapalı olmasından etkilenmez; aktif KPI'a her zaman yazılabilir.
Emekli KPI'a yazılamaz (KPI_RETIRED).
Kapalı OKR dönemindeki Anahtar Sonuca yazılamaz (CYCLE_LOCKED).
Her yazım KPI'ın Geçmiş sekmesine Push API kanalı ve API anahtarı kimliğiyle düşer.
Bağlama gerekliliği: Varsayılan olarak push, anahtarın tenant'ındaki herhangi bir aktif KPI'a, bir entegrasyon bağlaması olmasa da kabul edilir. Kurulum yöneticisi PUSH_REQUIRE_ACTIVE_BINDING ayarını açarsa push yalnızca hedef KPI veya Anahtar Sonucun aktif bir bağlaması varsa kabul edilir; aksi halde 403 FORBIDDEN döner. Bu ayarın varsayılanı ürün kararı olarak değerlendirilmektedir; kurulumunuzdaki değeri yöneticinize sorun.

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ığı

KPI Takibi'nde KPI detayının Entegrasyon sekmesinde veya rapordaki KPI detay çekmecesinde, Push API bölümü (kpi_push_measurement etkinken görünür) KPI kimliği ve kpiType: "KPI" ö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ı

Genel Bakış​

Nasıl Çalışır​

Ön Koşullar​

API Anahtarlarını Yönetme​

API Anahtarı Oluşturma​

API Anahtarını İptal Etme​

API anahtarı sınırı​

Ölçüm Gönderme​

Tekli Ölçüm​

Toplu Ölçüm (en fazla 50)​

İstek Alanları​

Kod Örnekleri​

Python​

JavaScript / Node.js​

Kimlik Doğrulama​

Hata Yanıtları​

Kurallar​

Güvenlik Notları​

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

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