Başlangıç
Kavramlar
Çalışma alanı, yazılım, 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, yazılım 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.
Yazılım
ERP, CRM, E-Ticaret, B2B, Çağrı Merkezi, Mail, Müşavir ve Reklam birer yazılımdır. Her yazılım ayrı bir servistir, kendi uç ailesini ve kendi veritabanı şemasını taşır — ama kimlik, hata ve sayfalama sözleşmesini paylaşır.
Bir yazılımın API'sini çağırabilmen için çalışma alanının o yazılıma lisanslı olması gerekir. Lisans yoksa uç 403 döner ve gövdede neden yazar:
{ "error": { "code": "CRM-LIC-0001", "message": "Bu yazılım aboneliğinde yok.",
"hint": "module_not_licensed" } }hint alanı makine okunurdur ve çevrilmez — dallanmayı messagea değil ona yap.
Kiracı adresi
Her yazılımı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 yazılımı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 yazılım aynı 403'ü ve aynı hinti döner — hangi yazılıma çağırdığın fark etmez. Bu bilinçlidir: entegrasyonun tek bir dalda karar verebilmesi için.