İş ortağı API'si

İş ortakları için sunucudan sunucuya API: anahtar üretin, vitrin yapılandırmanızı ve konumları okuyun, müşteri oluşturun, paket verin ve abonelik bağlantılarını kendi sitenizden ya da Telegram botunuzdan yönetin.

İş ortağı API'si, CreateYourVPN üzerinde kendi sitenizi, kendi panelinizi ya da bir Telegram botunu oluşturmanızı sağlar.

API müşterileri, abonelikleri, paketleri ve vitrin yapılandırmasını kapsar. Sunucular, düğümler, paneller ve SSH kimlik bilgileri gibi altyapı herkese açık sözleşmenin dışındadır.

Yalnızca sunucudan sunucuya. API anahtarlarını kendi sunucunuzda saklayın ve frontend koduna eklemeyin. Tarayıcı başlıkları taşıyan istekler 403 browser_forbidden ile reddedilir.

Anahtar alma

Paneli açın → Hesap menüsü → "API", "Anahtarlar" sekmesi.

Anahtara bir ad verin (Telegram botu, açılış sayfası) ve yalnızca ihtiyaç duyduğu yetkileri seçin.

"Anahtar üret" düğmesine basın ve değerin tamamını kopyalayın. Gizli kısım yalnızca bir kez gösterilir, çünkü yalnızca hash değeri saklanır.

Her iş ortağının en fazla 5 etkin anahtarı olabilir. Bir anahtarı yenilemek için yeni bir anahtar üretin, entegrasyonu güncelleyin ve ardından eskisini iptal edin.

Kimlik doğrulama

Anahtarı bearer token olarak gönderin:

curl https://api.createyourvpn.com/api/v1/partner-api/me \
  -H "Authorization: Bearer cyv_live_<key_id>_<secret>"

X-API-Key: cyv_live_… de çalışır; Authorization başlığını bir proxy kullandığında işe yarar.

Bir anahtar cyv_live_<key_id>_<secret> biçimindedir. İlk yarısı (key_id) herkese açıktır: panelde gördüğünüz ve desteğe güvenle söyleyebileceğiniz kısım budur. İkinci yarısı gizli kısımdır.

Yetkiler (scopes)

Yetki	Neye izin verir
`config:read`	Vitrin yapılandırmanızı, paketleri, konumları ve `/me` uç noktasını okumak.
`users:read`	Müşterileri, aboneliklerini ve trafiklerini okumak.
`users:write`	Müşteri oluşturmak, paket vermek, abonelik bağlantılarını sıfırlamak, müşteri silmek.

config:read, yalnızca vitrin verilerini okuyan entegrasyonlar için yeterlidir. users:read ya da users:write yetkisini yalnızca entegrasyon ilgili müşteri işlemlerine ihtiyaç duyduğunda ekleyin.

API sözleşmesi ve örnekler

Eksiksiz ve çalıştırılabilir sözleşme herkese açık Postman koleksiyonundadır. Koleksiyon her uç noktayı, yetkiyi, parametreyi, istek gövdesini, yanıt örneğini ve kalıcı hata kodunu içerir. Backend sözleşmesinden üretilir ve istek ile yanıt şemalarının güncel kaynağıdır.

Herkese açık Postman koleksiyonunu aç

Tüm uç noktaları inceleyin ve koleksiyonu workspace'inize kopyalayın.

Hız limitleri

Limitler, isteğin IP adresinden bağımsız olarak her anahtar için ayrı sayılır.

Anahtar başına toplamda dakikada 120 istek.
Özel olarak GET /users için dakikada 10 istek.

GET /users için ayrı bir limit vardır, çünkü her istek müşteri listesinin tamamını yükler. Düzenli sorgular için GET /users/{id} kullanın ya da externalId ile arayın.

Önerilen erişim düzeni. Oluşturma sırasında dönen CreateYourVPN müşteri kimliğini saklayın ve sonraki sorgularda GET /users/{id} kullanın. Bu kimliği externalId aracılığıyla kendi tanımlayıcınızla ilişkilendirebilirsiniz.

İdempotans

Üç işlem Idempotency-Key başlığı gerektirir: paket verme, abonelik bağlantısını sıfırlama ve müşteri silme.

curl -X POST .../users/u_9f3a…/grant \
  -H "Authorization: Bearer $CYV_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"tariffId":"monthly"}'

Aynı anahtarla 24 saat içinde tekrarlanan bir istek, işlemi yeniden çalıştırmak yerine saklanan yanıtı döndürür. Bu, bir entegrasyon zaman aşımından sonra yeniden denediğinde yinelenen değişiklikleri önler.

Her iş olayı için (örneğin bir ödeme ya da bir eylem) bir anahtar oluşturun ve o olayın her yeniden denemesinde aynı anahtarı kullanın.

İlk deneme hâlâ sürüyorsa ya da sonucu geçici olarak bilinmiyorsa, API işlemi yeniden yapmadan 409 conflict döndürür. Yeniden denemeye karar vermeden önce müşterinin güncel durumunu kontrol edin.

İstek ve yanıt şemaları için yukarıdaki herkese açık Postman koleksiyonunu doğruluk kaynağı olarak kullanın.