Başlangıç
Kavramlar
Çalışma alanı, modül, slug, kiracı adresi ve lisans — API'yi anlamadan önce bilinmesi gereken beş kavram.
Blesyum çok kiracılı bir platformdur. Bu, API'nin şeklini doğrudan belirler: her isteğin bir çalışma alanına ait olması gerekir ve bu aidiyet tahmin edilmez, kanıtlanır.
Çalışma alanı (workspace)
Faturalamanın, ekibin, modül aboneliklerinin ve tüm verinin bağlı olduğu birim. Bir kişi birden çok çalışma alanının üyesi olabilir; her birinde farklı rolü olur.
Çalışma alanının iki kimliği vardır:
| Ne | Nerede görünür | |
|---|---|---|
| Slug | Kısa, URL-güvenli ad (acme-ltd-1e7e11) | Adreslerde |
| Ad | Görünen ünvan (Acme Ltd. Şti.) | Panelde, faturada |
Slug bir adrestir ve Türkçe harfler ASCII'ye indirilerek üretilir (Ölçüm Şirketi → olcum-sirketi). Kod yazarken slug'ı elle kurma; panelden ya da /api/v1/me yanıtından oku.
Modül
ERP, CRM, E-Ticaret, B2B, Çağrı Merkezi, Mail, Müşavir ve Reklam birer modüldür. Her modül ayrı bir servistir, kendi uç ailesini ve kendi veritabanı şemasını taşır — ama kimlik, hata ve sayfalama sözleşmesini paylaşır.
Bir modülün API'sini çağırabilmen için çalışma alanının o modüle lisanslı olması gerekir. Lisans yoksa uç 403 döner ve gövdede neden yazar:
{ "error": { "code": "CRM-LIC-0001", "message": "Bu modül aboneliğinde yok.",
"hint": "module_not_licensed" } }hint alanı makine okunurdur ve çevrilmez — dallanmayı messagea değil ona yap.
Kiracı adresi
Her modülün her çalışma alanı için kendi adresi vardır ve bu adres kendiliğinden doğar; kimseden istemen gerekmez:
<slug>.<modul>.blesyum.appKendi alan adını bağlarsan (erp.firmam.com) o modülün adresi o olur. Platform adresi çalışmaya devam eder ama tarayıcı isteklerinde seninkine yönlendirilir.
Panelde ya da kodunda adres sabit yazma. Doğru kaynak GET /api/v1/modules yanıtındaki url alanıdır: müşteri kendi alan adını bağladığında o alan kendiliğinden değişir.
Kimlik: kim çağırıyor
Üç tür çağıran vardır ve API'nin her ucu bunlardan birini bekler:
| Tür | Başlık | Ne zaman |
|---|---|---|
| API anahtarı | Authorization: Bearer blsk_… | Sunucudan sunucuya otomasyon |
| Oturum | Authorization: Bearer <oturum-token> | Panelin kendi uçları |
| Herkese açık | — | Webhook girişleri, widget, sağlık uçları |
Ayrıntı: Kimlik doğrulama.
Lisans ve erişim
Lisansın durumu erişimi doğrudan belirler:
| Durum | Erişim | Anlamı |
|---|---|---|
trial | var | Deneme sürüyor |
active | var | Abonelik açık |
pending_payment · pending_review | yok (402) | Hesap açılışı tamamlanmadı |
expired · suspended · canceled | yok (403) | Abonelik kapandı |
Kapalı bir abonelikte her modül aynı 403'ü ve aynı hinti döner — hangi modüle çağırdığın fark etmez. Bu bilinçlidir: entegrasyonun tek bir dalda karar verebilmesi için.