LLCBullet API Entegrasyonu: Harici Sistemlere Bağlanma Rehberi

LLCBullet dış API'si, kendi sunucundaki betiklerin ve servislerin hesabına ait bilgileri okumasına ve otomasyon görevlerini tetiklemesine olanak tanır. Örneğin paket bitiş tarihlerini kendi iç panelinde göstermek, bir dağıtımdan sonra site kontrolü görevini zamanlamasını beklemeden çalıştırmak ya da görev listesini kendi raporlarına eklemek için API'yi kullanabilirsin. Bu rehberde bağlantının tamamını, Python ile çalışan bir örnekle adım adım anlatıyoruz.

Nasıl çalışır: iki adımlı erişim

API'ye doğrudan kalıcı bir anahtarla istek atmazsın. Önce kişisel API anahtarınla imzalı bir istek göndererek 15 dakika geçerli bir erişim jetonu alırsın, ardından diğer uçları bu jetonla çağırırsın. Bu tasarım, gizli anahtarın ağ üzerinde hiç dolaşmamasını ve ele geçirilen bir jetonun yalnızca kısa bir süre işe yaramasını sağlar.

1. Anahtarı oluştur

1. Panelde API sayfasını aç ve yeni anahtar oluştur.
2. Anahtara ne için kullanıldığını anlatan bir ad ver, örneğin 'Raporlama sunucusu'.
3. Yalnızca gereken kapsamları seç. Kapsam sonradan genişletilemez; daha fazla yetki gerekirse yeni anahtar oluşturman gerekir.
4. Sabit IP'li bir sunucudan çağıracaksan IP izin listesi ekle; tek adres ya da aralık yazabilirsin.
5. İstersen 1 ile 365 gün arasında bir geçerlilik süresi belirle.
6. Telegram'a gelen onay isteğinde Onayla'ya dokun, ardından lbs_ ile başlayan gizli anahtarı panelde görüntüle ve hemen kaydet. Gizli anahtar yalnızca bir kez gösterilir.

Kapsamlar

• read:account – hesap bilgileri: kullanıcı adı, görünen ad, dil ve saat dilimi.
• read:subscriptions – paketler, durumları ve bitiş tarihleri.
• read:automation – otomasyon görevleri ve son çalışma sonuçları.
• run:automation – otomasyon görevlerini elle tetikleme. Yalnızca gerçekten gerekiyorsa ver.

2. İmzalı istekle jeton al

Jeton isteği POST yöntemiyle /token ucuna gönderilir ve dört başlık taşır: X-LB-Key (lbk_ ile başlayan anahtar kimliği), X-LB-Timestamp (Unix saniye), X-LB-Nonce (her istekte yeni, 16–64 karakter) ve X-LB-Signature. İmza, gizli anahtarla HMAC-SHA256 kullanılarak şu beş değerin satır satır birleşimi üzerinden hesaplanır: zaman damgası, nonce, POST, /api/ext/v1/token ve istek gövdesinin SHA-256 özeti. Aşağıdaki örnek jetonu alır, paketleri okur ve bir görevi tetikler:

import hashlib
import hmac
import os
import secrets
import time

import requests

KEY_ID = os.environ["LB_KEY_ID"]      # lbk_...
SECRET = os.environ["LB_KEY_SECRET"]  # lbs_...
BASE = os.environ["LB_API_BASE"]      # Panel > API sayfasındaki adres (.../api/ext/v1)


def get_token() -> str:
    body = b""
    timestamp = str(int(time.time()))
    nonce = secrets.token_hex(16)
    body_hash = hashlib.sha256(body).hexdigest()
    payload = f"{timestamp}\n{nonce}\nPOST\n/api/ext/v1/token\n{body_hash}"
    signature = hmac.new(SECRET.encode(), payload.encode(), hashlib.sha256).hexdigest()
    res = requests.post(
        f"{BASE}/token",
        headers={
            "X-LB-Key": KEY_ID,
            "X-LB-Timestamp": timestamp,
            "X-LB-Nonce": nonce,
            "X-LB-Signature": signature,
        },
        data=body,
        timeout=10,
    )
    res.raise_for_status()
    return res.json()["accessToken"]


token = get_token()
auth = {"Authorization": f"Bearer {token}"}

subs = requests.get(f"{BASE}/subscriptions", headers=auth, timeout=10)
subs.raise_for_status()
print(subs.json())

# run:automation kapsamı gerekir
task_id = os.environ["LB_TASK_ID"]
run = requests.post(f"{BASE}/automation/tasks/{task_id}/run", headers=auth, timeout=10)
run.raise_for_status()

Panelde gösterilen API adresini LB_API_BASE ortam değişkenine koy. Node.js ile aynı akışın örneğini kişisel API anahtarları rehberinde bulabilirsin. Başarılı jeton yanıtı erişim jetonunu, geçerlilik süresini ve anahtarın kapsamlarını içerir.

3. Uçları çağır

• GET /me – hesap bilgileri (read:account).
• GET /subscriptions – paketler ve bitiş tarihleri (read:subscriptions).
• GET /automation/tasks – otomasyon görevleri (read:automation).
• POST /automation/tasks/{id}/run – görevi hemen çalıştırır (run:automation).

Tüm uçlar Authorization başlığında Bearer jetonu bekler. Jetonun süresi dolduğunda aynı imzalı yöntemle yenisini alırsın; her istekte yeni jeton almak yerine jetonu süresi dolana kadar yeniden kullanmak hem daha verimli hem de hız sınırına takılma riskini azaltır.

Örnek kullanım senaryoları

• Dağıtım sonrası kontrol: CI/CD hattının son adımında ilgili site kontrolü görevini /automation/tasks/{id}/run ile tetikle; sonucu paneldeki çalışma geçmişinden ya da read:automation kapsamıyla GET /automation/tasks yanıtındaki son çalışma durumundan izle.
• İç panelde bitiş tarihleri: /subscriptions yanıtındaki bitiş tarihlerini kendi yönetim ekranında göster ve yaklaşan bitişleri kendi takviminde işaretle.
• Görev envanteri: /automation/tasks ile tüm görevlerini listeleyip hangi altyapı için görev tanımlı olmadığını raporla.

Bu senaryoların her biri farklı bir kapsam gerektirir; her biri için ayrı ve yalnızca gereken kapsama sahip bir anahtar oluşturmak, en az yetki ilkesinin pratik uygulamasıdır.

Sık karşılaşılan hatalar

• İmza tutmuyor: İmzalanan metindeki satır sırasını, yolun tam olarak /api/ext/v1/token olduğunu ve gövde özetinin gönderilen gövdeyle aynı olduğunu kontrol et.
• Zaman damgası reddedildi: Sunucu saatin 5 dakikadan fazla sapmışsa istek reddedilir. Saati NTP ile eşitle.
• Nonce reddedildi: Her nonce yalnızca bir kez kabul edilir. Yeniden denemede yeni nonce üret.
• IP reddedildi: Çağrı yaptığın sunucunun çıkış IP'si izin listesinde değil. Bulut ortamlarında çıkış IP'si değişebilir.
• Yetki hatası: Çağırdığın uç, anahtarın kapsamlarında olmayan bir izin gerektiriyor.
• Çok fazla istek: Dış API hız sınırıyla korunur. Bu yanıtı alırsan bekleyip artan aralıklarla yeniden dene.

Webhook mu, API mi?

API, senin sistemin LLCBullet'e soru sorduğunda işe yarar. Görev sonuçlarının kendiliğinden senin sistemine gelmesini istiyorsan webhook görevleri daha uygun bir yoldur: LLCBullet, belirlediğin zamanlamayla HTTPS adresine imzalı bir JSON gönderir. Pek çok entegrasyonda ikisi birlikte kullanılır: webhook ile sonuçları al, API ile gerektiğinde görevi tetikle.

Güvenlik kontrol listesi

• Gizli anahtarı tarayıcıda çalışan koda koyma; sunucuda ortam değişkeninde ya da gizli değer yöneticisinde sakla. Ayrıntılar için API anahtar saklama pratiklerine bak.
• Her entegrasyon için ayrı anahtar oluştur; biri sızarsa yalnızca onu iptal edersin. Hesap başına en fazla 10 etkin anahtar olabilir.
• Anahtarları düzenli yenile: yeni anahtar oluştur, betiğini güncelle, eskisini iptal et. İptal anında geçerlidir ve açık jetonlar da hemen geçersiz olur.
• API anahtarı oluşturulduğunda Telegram'a güvenlik bildirimi gelir; senin oluşturmadığın bir anahtar görürsen hemen iptal et.

Sonuç

LLCBullet API'si; kapsamlı anahtarlar, imzalı jeton isteği ve kısa ömürlü jetonlarla güvenli bir entegrasyon yolu sunar. En az yetkiyle başla, IP listesi ekle ve jetonları yeniden kullanarak hız sınırlarına saygı göster.

API anahtarı oluştur