CM

CozumMerkezi API

v1

CozumMerkezi REST API

Widget entegrasyonu, operator islemleri ve webhook yapilandirmasi icin API referansi.

Base URL: https://cozummerkezi.net/api/v1

Kimlik Dogrulama

Widget API — API Key

Header: X-API-Key: CM_XXXXXXXXXXXX

Operator API — Bearer Token (Sanctum)

Header: Authorization: Bearer {token}

Origin Whitelist (v1.8.4+)

Tenant'a izinli_originler tanımlandıysa, Widget API çağrılarındaki Origin / Referer header'ı bu listedeki scheme+host ile birebir eşleşmeli. Eşleşmezse 403 Forbidden döner. Whitelist boşsa (varsayılan) tüm origin'ler kabul edilir. Portal: /portal/widget sayfasından ekle/sil.

HMAC Anti-Spoofing (v1.8.4+) — opsiyonel

/context/customer-info çağrısına timestamp (Unix sec) ve signature alanları eklenirse kimlik sunucu tarafında doğrulanır. Formül: HMAC-SHA256(api_secret, ziyaretci_id|email|timestamp). Tolerans ±300 sn. Geçerli imza dönen yanıtta identity_dogrulandi: true bayrağını set eder; geçersizse 401 döner. API Secret yalnızca sunucu tarafında imzalanmak için kullanılır, tarayıcıya basılmaz.

Auth

POST /auth/login
POST /auth/logout

Widget API

POST /widget/init
POST /widget/chat/start
POST /widget/chat/message
GET /widget/chat/messages
POST /widget/chat/end
POST /widget/chat/rate
POST /widget/ticket/create
GET /widget/ticket/list
GET /widget/ticket/{id}
POST /widget/ticket/{id}/reply
POST /widget/upload
GET /widget/kb/search
GET /widget/kb/categories
GET /widget/kb/article/{slug}
GET /widget/campaigns

Operator API

GET /operator/dashboard
GET /operator/chats
GET /operator/chat/{id}/messages
POST /operator/chat/{id}/message
POST /operator/chat/{id}/transfer
POST /operator/chat/{id}/close
POST /operator/chat/{id}/accept
GET /operator/tickets
POST /operator/ticket/{id}/reply
PUT /operator/ticket/{id}/status
POST /operator/status
GET /operator/canned-responses

Multi-Tenant API (v1.7.0+)

GET /operator/tenants
PUT /operator/tenants/sira
PUT /operator/tenants/{musteriId}/sessize

Context API

POST /context/customer-info
POST /context/page-info
POST /context/error-log
POST /context/screenshot
GET /operator/context/{ziyaretci_id}

Portal Multi-Tenant (v1.8.4+)

GET /portal/projeler
POST /portal/projeler/sec/{musteriId}
GET /portal/projelerim
GET /portal/projelerim/yeni
POST /portal/projelerim

Webhook Events

EVENT yeni_chat
EVENT yeni_ticket
EVENT chat_kapandi
EVENT ticket_cozuldu
EVENT memnuniyet_puan
EVENT operator_cevrimdisi

Ornek Kullanim

// Widget baslat (Origin whitelist aktifse mutlaka site domain'inden cagir)
curl -X POST https://cozummerkezi.net/api/v1/widget/init \
  -H "X-API-Key: CM_DEMO_2026" \
  -H "Origin: https://siteniz.com" \
  -H "Content-Type: application/json" \
  -d '{"ziyaretci_id": "abc123"}'

// Customer info — HMAC anti-spoofing ile (v1.8.4+, opsiyonel)
// SUNUCU TARAFINDA hesaplayin: api_secret tarayiciya gitmemeli
// PHP: $sig = hash_hmac('sha256', "$ziyaretci_id|$email|$ts", $api_secret);
curl -X POST https://cozummerkezi.net/api/v1/context/customer-info \
  -H "X-API-Key: CM_DEMO_2026" \
  -H "Content-Type: application/json" \
  -d '{
    "ziyaretci_id": "abc123",
    "email": "[email protected]",
    "ad": "Ahmet",
    "soyad": "Yilmaz",
    "paket": "Kurumsal",
    "kontor": 4500,
    "timestamp": 1747320000,
    "signature": "9a8b7c...e5f6"
  }'

// Response — dogrulanmis kimlik flagi
{ "basarili": true, "identity_dogrulandi": true, "data": { ... } }

// Operator: ziyaretci full context — banner array dahil (Bearer token)
curl -H "Authorization: Bearer $TOKEN" \
  https://cozummerkezi.net/api/v1/operator/context/abc123

// Response banner ornegi (operator paneli ust seridi)
{
  "basarili": true,
  "data": {
    "musteri": { "ad": "Ahmet", "email": "[email protected]", "paket": "Kurumsal", "kontor": 4500 },
    "banner": [
      { "tip": "paket",    "icon": "📦", "label": "Paket",          "deger": "Kurumsal" },
      { "tip": "kontor",   "icon": "💰", "label": "Kalan kontör",   "deger": "4.500" },
      { "tip": "trial",    "icon": "⚠️", "label": "Deneme bitiyor", "deger": "2 gün", "kritik": true },
      { "tip": "depolama", "icon": "💾", "label": "Depolama",       "deger": "3,0 / 5,0 GB (%60)", "kritik": false }
    ]
  }
}

// Depolama banner — storage tabanli servisler icin (PratikYedek vb.)
// customerInfo POST'unda ekstra alaninda gonder:
{
  "ziyaretci_id": "user_42",
  "email": "[email protected]",
  "paket": "Pro 5GB",
  "ekstra": {
    "depolama_kullanilan_gb": 3.0,    // numeric
    "depolama_toplam_gb":     5.0,    // numeric — yuzde otomatik
    "son_yedek":              "2 saat önce"
  }
}
// Alternatif: hazir string + manuel yuzde/kritik flag
{ "ekstra": { "depolama_kullanim": "3 GB / 5 GB", "depolama_dolu_yuzde": 60, "depolama_kritik": false } }
// Yuzde >= 90 ise kritik=true otomatik (icon "⚠️", operator panel kirmizi banner)

// Operator giris (sifre alani: "sifre")
curl -X POST https://cozummerkezi.net/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"email": "[email protected]", "sifre": "sifre123"}'

// Response (v1.7.0+ — multi-tenant: musteriler[] array)
{
  "basarili": true,
  "data": {
    "token": "13|ABC...",
    "token_tipi": "Bearer",
    "operator": {
      "id": 7,
      "email": "[email protected]",
      "musteri_id": 2,              // backward-compat birincil proje
      "musteriler": [                // operatorun uye oldugu tum projeler
        {
          "id": 2,
          "firma_adi": "PratikEsnaf.Com",
          "logo_url": "/storage/tenants/2/logo.png",
          "renk_primary": "#FF6B35",
          "sira": 0,
          "sessize_alindi": false,
          "rol": "senior",
          "max_chat_per_tenant": null
        },
        { "id": 1, "firma_adi": "CozumMerkezi Demo", "sira": 1, ... }
      ]
    }
  }
}

// Tenant listesi (oturum boyunca refresh)
curl -H "Authorization: Bearer $TOKEN" \
  https://cozummerkezi.net/api/v1/operator/tenants

// Sekme sirasi guncelle (surukle-birak)
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"order":[2,1]}' \
  https://cozummerkezi.net/api/v1/operator/tenants/sira

// Proje sekmesini sessize al
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"sessize":true}' \
  https://cozummerkezi.net/api/v1/operator/tenants/2/sessize

// Webhook payload ornegi
{
  "olay": "yeni_chat",
  "zaman": "2026-04-12T14:30:00+03:00",
  "veri": {
    "oturum_id": 42,
    "musteri_id": 2,                 // v1.7.0+ multi-tenant
    "ziyaretci_adi": "Ahmet Yilmaz",
    "kanal": "web"
  }
}
v1.7.0 Multi-Tenant: Bir operatorun birden cok musteriye (proje) bagli olmasi desteklenir. Login response'unda data.operator.musteriler[] array'i oturumun tum projelerini listeler. Eski v1.6.x clientlar musteri_id tekil alanini okumaya devam eder (backward-compat). /operator/chats artik operatorun tum projelerinden birlesik kuyruk dondurur; her oturum kaydinda musteri_id alani vardir.
v1.8.4 Portal Multi-Tenant + Güvenlik:
  • Portal hesabı → N proje: Tek e-posta birden çok tenant'a sahip olabilir. 2+ tenant'lı kullanıcı login sonrası /portal/projeler'den seçim yapar; header'daki dropdown ile geçiş yapılır (session portal_active_tenant_id + user.musteri_id sync).
  • Self-service yeni proje: /portal/projelerim/yeni ile 14 gün ücretsiz deneme açılır, pivot otomatik oluşur (rate limit: 24 saat / 3 proje).
  • Origin whitelist: Widget API anahtarı her tenant'ta izinli_originler JSON listesine bağlanabilir; eşleşmeyen Origin 403 alır. Portal: /portal/widget.
  • HMAC anti-spoofing: /context/customer-info opsiyonel timestamp + signature alır; sunucu HMAC-SHA256(api_secret, ziyaretci_id|email|timestamp) doğrular, ±5dk tolerans, yanıtta identity_dogrulandi.
  • Banner data: /operator/context/{ziyaretci_id} yanıtında banner[] array'i (paket / kontör / trial / depolama) operatöre canlı görünür; trial ≤3 gün veya depolama ≥%90 ise kritik:true (kırmızı şerit).
  • Depolama banner (v1.8.5+): Storage tabanlı servisler (yedekleme, hosting, dosya saklama) için ekstra.depolama_kullanilan_gb + ekstra.depolama_toplam_gb gönderir; yüzde + kritik flag otomatik hesaplanır. Hazır string için ekstra.depolama_kullanim + depolama_dolu_yuzde.

© 2026 CozumMerkezi.net — Tum haklari saklidir.