Bulutegra API ve webhook: kendi yazılımınızı bağlama

Bu ekran ne işe yarar?

Ayarlar → Bulutegra API ve webhook ekranında iki şey yaparsınız:

• Kendi yazılımınızın (ERP, depo, raporlama) Bulutegra'daki siparişleri, ürünleri ve stokları okuyabilmesi için API anahtarı oluşturursunuz.
• Yeni sipariş ve durum değişikliklerini anında almak için webhook eklersiniz.

API yalnız okur; hiçbir şeyi değiştiremez. Kanallara ve ERP'nize yazma işini Bulutegra yapar. Uçların ve alanların teknik ayrıntısı developers.bulutegra.com adresindedir.

Kim kullanabilir?

Ayarlar menüsü Yönetici rolünde görünür. Anahtar ve webhook yönetimini ise yalnız hesap sahibi yapabilir; diğer yönetici kullanıcılar bu sekmede yetki hatası görür.

API anahtarı oluşturmak

1. Ad kutusuna anahtarı kullanacak yazılımın adını yazın (örn. Depo yazılımı).
2. Kapsam'ı seçin. Temel (kişisel veri yok) seçilirse siparişlerde müşteri adı dönmez. Kişisel veri dahil (müşteri adı) seçilirse müşteri adı da döner; bunu yalnız gerçekten gerekiyorsa seçin.
3. Anahtar oluştur'a basın.
4. Çıkan Yeni API anahtarı kutusundaki değeri Kopyala ile alıp güvenli bir yere kaydedin.

Anahtar yalnız bu anda gösterilir; sayfadan ayrıldığınızda bir daha gösterilemez. Kaybederseniz eskisini iptal edip yeni anahtar oluşturun. Hesapta en çok 10 etkin anahtar olabilir.

Listede her anahtar için ad, anahtarın kısaltılmış hali, kapsam rozeti (temel ya da kişisel veri dahil), oluşturan kişi ve tarih, Son kullanım zamanı ve istek sayısı görünür.

Anahtarı iptal etmek

Satırdaki İptal et'e basıp onaylayın. Anahtarı kullanan yazılım erişimini hemen kaybeder. İptal edilen anahtar listede soluk görünür ve iptal tarihi yazar. İptal geri alınamaz; gerekirse yeni anahtar oluşturun.

API'yi kullanmak

Kullanım kutusunu açınca adres, örnek istek ve uçların listesi görünür. Kısaca:

• Her istekte anahtarı "Authorization: Bearer" başlığıyla gönderin.
• Yalnız okuma (GET) istekleri kabul edilir.
• Uçlar: ping, siparisler (başlangıç tarihi, kanal ve durum süzgeçleriyle), kanal ve sipariş numarasıyla tek sipariş, urunler, stok (SKU listesiyle) ve kanallar.
• Uzun listeler sayfalanır: yanıttaki "sonraki_imlec" değerini bir sonraki isteğe "imlec" olarak verin.
• Anahtar başına dakikalık bir istek sınırı vardır; sınır Kullanım kutusunda yazar. Aşılırsa istek 429 koduyla reddedilir; kısa bir süre bekleyip yeniden deneyin.

Webhook eklemek

Webhook, bir olay olduğunda Bulutegra'nın sizin adresinize bildirim göndermesidir.

1. Adres kutusuna bildirimleri alacak adresi yazın. Adres https:// ile başlamalı ve genel internetten erişilebilir olmalıdır.
2. Olaylar'dan almak istediklerinizi işaretleyin: Yeni sipariş, Sipariş durumu değişti, Sipariş ERP'ye aktarıldı. En az bir olay seçilmelidir.
3. Webhook ekle'ye basın.
4. Çıkan Webhook imza sırrı kutusundaki değeri kopyalayıp kaydedin. Bu değer de yalnız bir kez gösterilir.

En çok 5 webhook tanımlanabilir; kapalı webhook'lar da bu sayıya dahildir. Webhook eklendiğinde geçmiş siparişler için toplu bildirim gönderilmez; bildirimler eklemeden sonraki değişikliklerle başlar.

İmzayı doğrulamak

Her istek "X-Bulutegra-Imza" başlığıyla gelir. Başlığın değeri "sha256=" önekiyle yazılmış bir özettir: isteğin ham gövdesinin webhook imza sırrıyla HMAC-SHA256 özeti. Sunucunuzda aynı özeti hesaplayıp başlıkla karşılaştırın ve eşleşmeyen isteği reddedin. Ekrandaki İmza doğrulama kutusunda örnek doğrulama satırı bulunur.

Teslim ve yeniden deneme

• Adresiniz 2xx dışında bir yanıt verirse teslim artan aralıklarla birkaç kez yeniden denenir. Aralıklar İmza doğrulama kutusunda yazar.
• Art arda çok sayıda teslim başarısız olursa webhook kapatılır ve size "Webhook kapatıldı" bildirimi düşer. Adresi düzelttikten sonra kartta Aç'a basın.
• Webhook kartında adres, açık ya da kapalı rozeti, seçili olaylar, son teslim sonucu ve art arda hata sayısı görünür.
• Son teslimler bölümü her teslimin zamanını, olayını, durumunu (teslim, yeniden denenecek, başarısız), deneme sayısını ve aldığı yanıtı gösterir.
• Test gönder adresinize deneme isteği yollar ve sonucu gösterir. Kapat webhook'u durdurur. Sil webhook'u teslim kayıtlarıyla birlikte siler.

Bir sorun varsa

• "Yalnız https:// adresleri kabul edilir": adresi https ile yazın.
• "Adres genel internette değil" ya da "İç ağ adresleri kabul edilmez": webhook adresi internetten erişilebilir bir alan adı olmalıdır.
• "En çok 5 webhook tanımlanabilir": kullanmadığınız webhook'u Sil ile kaldırın.
• "En çok 10 etkin anahtar olabilir": kullanmadığınız anahtarı iptal edin.
• Yazılımınız 401 alıyorsa başlığı ve anahtarın iptal edilmediğini kontrol edin.
• Yazılımınız 429 alıyorsa istek sınırını aşmıştır; isteklerini seyreltin.
• Demo hesabında yapılan değişiklikler kaydedilmez.

İlgili yazılar: Roller, iki adımlı doğrulama ve parola sıfırlama ve Veri güvenliği özeti.