WISECP API Kullanımı: Yönetim, Müşteri ve Modül Adresleri

Üç adres: admin, client ve modül yolları

Belgeye göre /api/v1 altındaki üç adres, sürümden sonraki segmentle ayrılır. Kimlik isteyen iki adres aynı ürünün süzülmüş iki hali değil, ayrı iki üründür: biri için üretilen anahtar diğerinde reddedilir.

Yönetim adresi kaynakları ailelere ayırır: system ve reference (sağlık, anahtar kimliği, para birimi, ülke gibi listeler), clients, orders, invoices, services, products, tickets, settings, automation ve diğerleri. Belge bu API'nin bir veritabanı aynası olmadığını özellikle vurgular: bir müşteri oluşturmak panelin kullandığı işleyiciden geçer, birden çok tabloya yazar, kancaları çalıştırır ve bildirim gönderebilir.

Panelde API anahtarı oluşturma

Yönetim anahtarı panelden üretilir. Ekran Ayarlar > Genel Ayarlar içindeki API sekmesidir; doğrudan adresi {admin}/settings?general=api. Sekmede Admin API, Client API ve Kayıtlar alt sekmeleri bulunur.

• API Kimlik Bilgisi Oluştur butonuna tıklayın ve bir Ad girin (zorunlu). Adı, anahtarın hangi entegrasyona ait olduğunu anlatacak şekilde seçin.
• İsteğe bağlı olarak İzin verilen IP adresleri alanına her satıra bir adres yazın. Boş bırakılırsa her adrese izin verilir; entegrasyon sabit bir sunucudan çalışıyorsa o sunucunun IP'sini yazmanız iyi olur.
• İsteğe bağlı İstek Limiti (dakikada) değerini girin. Boş bırakmak veya 0 yazmak sistem varsayılanını kullanır.
• İzin listesinden yalnızca entegrasyonun ihtiyaç duyduğu uçları işaretleyin. Tam erişim ver seçeneği de vardır, ama en az bir izin seçmek zorunludur.
• Kaydedince anahtar yalnızca bir kez gösterilir. Kopyalayıp hemen güvenli bir yere (ortam değişkeni, gizli anahtar kasası) koyun.

Panel belgesi birkaç önemli ayrıntı daha veriyor. Bir anahtar, onu oluşturan yöneticinin kendi yetkilerini asla aşamaz; Tam erişim ver bile hesabınızın izin verdiğiyle sınırlıdır. API sekmesini görüntülemek SETTINGS_INFORMATIONS_CONFIGURE ve ayrıca SETTINGS_API_CREDENTIALS yetkisi ister. Lisans paketiniz API'yi kapsamıyorsa sekme görünür kalır ama kontrolleri devre dışı olur. Kayıtlar sekmesi API'nin aldığı her isteği çağıran, yöntem, uç nokta, tarih ve IP ile listeler; bir satıra tıklayınca isteğin başlığı, gövdesi ve yanıtı açılır. Hata ayıklarken ilk bakacağınız yer burasıdır.

Müşteri API anahtarları (wck_)

Client API varsayılan olarak kapalı gelir. Açmak için aynı ekrandaki API Kimlik Bilgisi Oluştur butonunun yanındaki dişli simgesine tıklayın, Client API seçeneğini açın ve erişimi Tüm Müşteriler ya da Seçili Müşteriler için verin. Erişilebilir Uçlar bölümüyle müşterilerin anahtarlarına hangi uçları verebileceğini daraltabilirsiniz. Müşteri anahtarını müşteri kendi hesabındaki API Kimlik Bilgileri sayfasından (/api-credentials) üretir; bu anahtar onu oluşturan hesaba bağlıdır ve komşu bir hesabı asla okuyamaz.

Kimlik doğrulama ve izinler

Anahtarı Authorization: Bearer başlığına koyun. İstemciniz bu başlığı kuramıyorsa belge yedek olarak X-Api-Key başlığını kabul eder. Her istekte üç şey bu sırayla kontrol edilir: anahtarın ait olduğu adres, izin listesi ve dakikalık istek bütçesi. Hayır diyen ilk kontrol çağrıyı bitirir.

İzinler Grup/Eylem çiftleridir ve ucun dokümanındaki adla birebir aynıdır. Aynı ad hem rotanın kimliği, hem panelde işaretlediğiniz kutu, hem de 403 mesajındaki metindir.

Dakikalık istek bütçesi ve kilitlenme

Bütçe sabit bir dakikalık penceredir. Kurulum aksini söylemedikçe yönetim anahtarı için dakikada 120, müşteri anahtarı için 60 istektir; anahtar bazında panelden değiştirilebilir. Kimlik isteyen her yanıt bütçenin durumunu başlıklarla bildirir:

İstek ve yanıt biçimi

Gövdeyi JSON olarak Content-Type: application/json başlığıyla gönderin; bu başlığı vermezseniz gövde form alanı olarak okunur. Süzgeç, sıralama ve sayfalama her metotta sorgu dizesinde taşınır. Yalnızca GET ve POST'a izin veren bir vekil sunucunun arkasındaysanız X-Http-Method-Override başlığı metodun yerine geçer.

Yanıt zarfı her uçta aynıdır. Başarı içeriği data altına koyar, listelerde yanına meta gelir. Başarısızlık error altında sabit bir code, insanın okuyacağı bir message ve doğrulama hatalarında alanları adıyla veren details taşır. Kodunuzu mesaja göre değil code değerine göre dallandırın; mesaj yeniden ifade edilebilir, kod sözleşmenin parçasıdır.

{ "data": { "id": 42, "email": "ada@example.com" } }

{ "data": [ ], "meta": { "total": 318, "page": 2, "limit": 25, "next_page": 3 } }

{ "error": { "code": "validation_failed", "message": "Email is not valid.",
             "details": { "email": "invalid_format" } } }

• Sayfalama: liste uçları page ve limit alır. limit varsayılan 25, tavanı 100; fazlası sessizce 100'e çekilir. Sayfaları meta.next_page ile gezin, son sayfada değeri 0 olur. Toplam kayıt sayısı kökte değil meta.total içindedir.
• Tekrar güvenliği: POST isteklerinde isteğe bağlı Idempotency-Key başlığı (8 ile 191 karakter) gönderebilirsiniz. Aynı anahtarla tekrarlanan istek işi ikinci kez yapmaz, saklanan yanıtı Idempotency-Replayed: true başlığıyla döndürür. Aynı anahtarla bir istek hâlâ sürüyorsa 409 alırsınız.
• Demo kipi: kurulum demo kipindeyken POST, PUT, PATCH ve DELETE 403 demo_mode ile döner; okumalar çalışır.

Durum ve hata kodları

Sürüm politikası: v1 donduruldu

WISECP belgesi v1 için açık bir söz veriyor: yeni uçlar, yeni yanıt alanları ve yeni isteğe bağlı girdiler v1'e gelmeye devam eder. Alan silmek, ad değiştirmek, tip değiştirmek ya da bir girdiyi zorunlu yapmak v1'e gelmez; o tür değişiklikler v2'yi bekler. Kaldırılacak bir uç Deprecation başlığıyla ve en az altı aylık geçiş süresiyle duyurulur. Pratikte bunun anlamı şu: istemciniz yanıtlarda bilmediği yeni alanları sorunsuz yok saymalı ve yanıt başlıklarında Deprecation görürseniz bunu kayda geçirip takip etmelisiniz.

İlk iki çağrı: ping ve whoami

GET /api/v1/admin/ping (System/Ping) kimlik istemez ve pong, version ve sunucu saatini (time) döndürür. Adresin doğru ve API'nin ayakta olduğunu kanıtlar ama anahtarınızı doğrulamaz: iptal edilmiş bir anahtarla bile başarılı döner. GET /api/v1/admin/whoami (System/Whoami) ise kimlik ister ama kapsam istemez; anahtarın id, name, permissions ve last_access değerlerini verir. Ping geçip whoami düşüyorsa sorun sunucuda değil kimlik bilgisindedir.

curl 'https://panel.ornek.com/api/v1/admin/ping'
# {"data":{"pong":true,"version":"v1","time":"2026-08-06 10:12:41"}}

curl 'https://panel.ornek.com/api/v1/admin/whoami' \
  -H "Authorization: Bearer $WISECP_API_KEY"

PHP ile

<?php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/whoami');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('WISECP_API_KEY')],
]);
$body   = json_decode((string) curl_exec($ch), true) ?? [];
$status = (int) curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if (isset($body['error'])) {
    // Mesaja değil koda göre dallanın
    throw new RuntimeException($status . ' ' . $body['error']['code']);
}
$izinler = $body['data']['permissions'] ?? [];

Node.js ile (sayfalı liste)

Aşağıdaki örnek Node.js 18 ve üzerindeki yerleşik fetch ile müşteri listesini sayfa sayfa okur, 429 gelirse Retry-After kadar bekler. Bir ES modülü dosyasında (.mjs) çalıştırın. Anahtarın Clients/GetClients izni olmalıdır.

const BASE = 'https://panel.ornek.com/api/v1/admin';
const headers = { Authorization: `Bearer ${process.env.WISECP_API_KEY}` };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

let page = 1;
while (page) {
  const res = await fetch(`${BASE}/clients?limit=100&page=${page}`, { headers });
  if (res.status === 429) {
    await sleep(Number(res.headers.get('Retry-After') || 60) * 1000);
    continue;
  }
  const body = await res.json();
  if (body.error) throw new Error(`${res.status} ${body.error.code}`);

  for (const c of body.data) console.log(c.id, c.email);
  page = body.meta.next_page; // son sayfada 0
}

Webhook yok: yoklama ya da kanca

WISECP API dışarıya webhook göndermez; belge bunu bilinçli bir sınır olarak anlatır. Bir olayın ne zaman olduğunu bilmeniz gerekiyorsa iki yol vardır:

• Yoklama (polling): belirli aralıklarla bir liste ucunu çağırıp değişene göre davranırsınız. Anahtardan başka bir şey gerekmez, her yerden çalışır; gecikme aralığınız kadardır. Saniyede bir yoklamanın bir anahtarın bütün dakikalık bütçesini harcayacağını unutmayın; sunucu tarafında süzün ve 429 aldığınızda durun.
• Kanca (hook): kurulumun içine kod koyabiliyorsanız, örneğin kendi modülünüzün hooks.php dosyasında, olaya bir dinleyici kaydedersiniz. Kodunuz olaya sebep olan isteğin içinde, anında çalışır. Ayrıntılar için WISECP kanca (hook) kullanımı yazısına bakın.

Kurulumun içinde çalışan kod HTTP'ye çıkmak zorunda değildir: \WISECP\Api\Kernel::internal('Grup/Eylem', $input, $query) aynı ucu süreç içinde çalıştırır ve aynı zarfı döndürür. Belgenin uyarısı önemli: bu yolda izin, istek limiti ve istek kaydı çalışmaz, yani yetki kontrolünü kendiniz yapmalısınız.

<?php
// Kendi modülünüzün hooks.php dosyası: çekirdek dosyası düzenlenmez
\Hook::add('action:order.created', 10, function (array $order) {
    $id = (int) ($order['id'] ?? 0);
    if (!$id) return;

    $full = \WISECP\Api\Kernel::internal('Orders/GetOrder', ['id' => $id]);
    if (isset($full['error'])) return;

    // Dışarıya yavaş çağrı yapmayın; işi kendi kuyruğunuza bırakın
    \Acme\Sync::enqueue('order.created', $full['data']);
});

Örnekteki \Acme\Sync sizin yazacağınız kuyruk sınıfıdır; WISECP'nin bir parçası değildir. Modül yapısı için WISECP modül geliştirme rehberi yazısına bakabilirsiniz.

Sık Sorulan Sorular

WISECP API anahtarını nereden alırım?

Yönetim anahtarı panelde Ayarlar > Genel Ayarlar > API sekmesinden API Kimlik Bilgisi Oluştur ile üretilir. Müşteri anahtarını ise müşteri, Client API açıksa kendi hesabındaki /api-credentials sayfasından üretir.

Aynı anahtarı hem /admin hem /client adresinde kullanabilir miyim?

Hayır. wak_ anahtarı yalnızca /api/v1/admin, wck_ anahtarı yalnızca /api/v1/client adresinde çalışır. Yanlış adreste 403 audience_mismatch alırsınız.

Dakikada kaç istek atabilirim?

Belgeye göre varsayılan, yönetim anahtarı için dakikada 120, müşteri anahtarı için 60 istektir. Operatör anahtar bazında farklı bir değer girebilir; gerçek değeri X-RateLimit-Limit başlığından okuyun.

Sipariş geldiğinde WISECP benim adresime bildirim gönderir mi?

Hayır, webhook teslimi yoktur. Ya liste uçlarını belirli aralıklarla yoklarsınız ya da kurulumun içinde bir kanca dinleyicisi çalıştırırsınız.

API anahtarı tarayıcıdaki JavaScript içinde kullanılabilir mi?

Teknik olarak istek her yerden atılabilir, ama yönetim anahtarı kurulumun tamamına erişebildiği için onu tarayıcıya koymak anahtarı herkese vermek demektir. Anahtarı sunucu tarafında tutun; genel ilkeler için REST API güvenlik rehberi yazısına bakın.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: WISECP nedir · WISECP API ile destek talebi · WISECP hook kullanımı · WISECP modül geliştirme · REST API güvenliği · API rate limiting · Node.js REST API geliştirme