Marketplace uygulaması geliştirme rehberi

Blesyum uygulamaları, panele ve ürünlere (CRM, ERP, E-Ticaret, Mail…) yeni yetenek ekleyen eklentilerdir — Shopify App Store ya da Slack uygulamaları gibi. Telefona kurulan mobil uygulamalar değildir.

Çalışma modeli

Uygulamanız "uzak HTTP" modeliyle çalışır: kod Blesyum'un içine yüklenmez, ağ sınırının ötesinde sizin sunucunuzda çalışır ve imzalı, SSRF korumalı, hız sınırlı REST çağrılarıyla haberleşir. Veritabanına doğrudan erişim yoktur.

• Blesyum'da duran → Uygulamanın kimliği, kategorisi, hedef ürünleri, istediği izinler, fiyatlandırması ve sürüm geçmişi
• Sizde duran → Uygulamanın kendisi: iş mantığı, arayüz, veri işleme
• Veri erişimi → Yalnız API üzerinden, yalnız kiracının onayladığı izinlerin sınırında

1. Uygulamanızı tanımlayın

Konsoldan yeni uygulama oluştururken doldurduğunuz alanlar:

• Ad → Mağazada görünen isim
• Slug → Adres eki; yalnız küçük harf, rakam ve tire
• Kategori → Aşağıdaki kanonik listeden biri
• Açıklama → Uygulamanın ne yaptığı
• Hedef ürünler → crm · erp · b2b · mail · callcenter · shop · musavir
• İstenen izinler → Uygulamanızın çalışmak için ihtiyaç duyduğu kapsamlar
• Fiyatlandırma → Ücretsiz · Tek seferlik · Abonelik

Kategori kanonik listeden gelmek zorundadır; liste dışı bir anahtar gönderimi reddettirir.

• integration → Blesyum'u dış bir sisteme bağlar
• report → Panele rapor/gösterge ekler
• theme → Görsel tema
• automation → İş akışı otomasyonu
• sales_channel → Satış kanalı
• messaging_channel → Mesajlaşma kanalı
• shipping → Kargo/sevkiyat
• widget → Panele widget
• sector_pack → Sektör paketi
• language_pack → Dil paketi
• other → Diğer

2. İzinler

Uygulamanız yalnızca istediği ve kiracının kurulum sırasında onayladığı izinlerle çalışır. Az izin isteyin: gereksiz geniş izin, kurulum onayında güven kaybettirir.

3. Kimlik doğrulama

Blesyum API'sine her istek bir API anahtarıyla imzalanır. Anahtar formatı blsk_{ortam}_{kimlik}_{gizli} şeklindedir ve gizli kısmı yalnız oluşturma anında bir kez gösterilir.

curl https://firmaniz.blescript.com/api/v1/me \
  -H "Authorization: Bearer blsk_live_ab12cd34_gizli-anahtariniz"

4. Olayları webhook ile dinleyin

Sürekli sorgulamak yerine olay geldiğinde haber alın. Her teslimat üç başlıkla gelir:

• x-blesyum-event → Olayın adı (ör. invoice.paid)
• x-blesyum-delivery → Teslimat kimliği; tekrarları elemek için kullanın
• x-blesyum-signature → Ham gövdenin HMAC-SHA256 imzası (hex)

Abone olabileceğiniz olaylar ve ne zaman tetiklendikleri:

• invoice.created → Yeni fatura oluşturuldu
• invoice.paid → Fatura ödendi
• invoice.refunded → Fatura iade edildi
• subscription.renewed → Abonelik yenilendi
• subscription.plan_changed → Abonelik planı değişti
• subscription.canceled → Abonelik iptal edildi
• user.invited → Kullanıcı ekibe davet edildi
• user.joined → Davet edilen kullanıcı katıldı
• ticket.created → Destek talebi açıldı
• ticket.answered → Destek talebi yanıtlandı

İmzayı ham gövde üzerinden, sabit zamanlı karşılaştırmayla doğrulayın (JSON'a çevrilmiş hâli değil — boşluk farkı imzayı bozar):

import crypto from "node:crypto";

export function imzaDogrula(rawBody, header, secret) {
  const beklenen = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(beklenen);
  const b = Buffer.from(header ?? "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

5. Sürüm yayınlama

Bir sürümü yayınlarken girdiğiniz alanlar:

• Kanal → stable (kararlı) veya beta
• Yayılma → %0–100 arası kademeli açılış
• Durum → Yayında veya geri alındı

Yayınlama akışı:

1. Sürümü gönderin — Sürüm numarası, kanal ve değişiklik notunu girin.
2. Kademeli açın — Yayılma yüzdesiyle sürümü önce küçük bir kesime verin.
3. İncelemeyi bekleyin — Uygulama incelemeden geçtiğinde mağazada yayına girer.
4. Gerekirse geri alın — Sorunlu sürümü geri alın; kayıt silinmez, önceki sürüm devreye döner.

Uygulamanızın durumu konsolda görünür:

6. Yayın öncesi kontrol listesi

• İstenen izinleri en aza indirdiniz.
• Webhook imzasını doğruluyor, tekrarlanan teslimatı tekrar işlemiyorsunuz.
• API anahtarı yalnız sunucu tarafında; sızıntıda döndürme akışınız hazır.
• Hata durumunda uygulamanız kiracının işini durdurmuyor (zarif düşüş).
• Açıklama ve ekran görüntüleri uygulamanın gerçekte yaptığını anlatıyor.