Entegrasyon Rehberi

Bu rehber, Kilavuz’un dış hizmetlerle nasıl konuştuğunu ve bir entegrasyon geliştiricisinin bilmesi gereken sözleşmeleri özetler.

Stripe ile ödeme

Kilavuz, kredi satın alma işlemleri için Stripe kullanır. Kredi paketleri tek seferlik satın alınır; tekrarlanan yenileme, proje açma ücreti veya plan geçişi yoktur.

• Kredi paketleri tek seferlik satın alma olarak sunulur: Standart paket Vergiler dahil €100 karşılığında 1.000 kredi, lansman paketi ise Vergiler dahil €500 karşılığında 10.000 kredi verir (lansman paketi yalnızca yapılandırılmış 30 günlük kampanya döneminde uygun hesaplara gösterilir). Sunucu, Stripe fiyat kimliğini müşteri adına seçer; istemciden gelen fiyat bilgisi yalnızca sunum amaçlıdır ve Stripe tarafındaki tutar yetki kaynağıdır.
• Ödeme akışı Stripe tarafından barındırılan Checkout sayfasında, mode=payment ve quantity=1 ile tek bir paket için tamamlanır. Kart numarası veya CVV Kilavuz tarafından saklanmaz; ödeme dönüş ekranı (app/src/payment/CheckoutResultPage.tsx) bakiyeyi kendisi artırmaz ve ödeme onayı sunucuda doğrulanana kadar işlemi beklemede gösterir.
• Webhook’lar Stripe’tan api.kilavuz.app üzerindeki /stripe-webhook uç noktasına gelir; uç nokta, imzalı ham gövdeyi doğrulamadan önce isteği reddeder. Her başarılı ödeme için bir defalık kredi lotu tahsis edilir, kullanılmayan krediler satın alma tarihinden altı takvim ayı sonra sona erer ve lot tutarı faturalama geçmişine işlenir. Yetkili kullanıcılar ödeme makbuzlarına buradan ulaşabilir. Aynı uç nokta, iade ve uyuşmazlık düzeltmelerini de doğrulanmış ödeme kayıtlarına göre hesaba işler; tekrarlanan yenileme olayı yoktur.

E-posta sağlayıcısı (Resend)

Wasp 0.25, e-posta katmanı için yerel bir Resend sağlayıcısı sunar (emailSender.provider: "Resend", app/main.wasp). Kilavuz üretim ortamında Resend’in HTTPS API’sini kullanır ve sunucu tarafında tek bir ortam değişkeni okur:

• RESEND_API_KEY=<platform secret store üzerinden enjekte edilir>

Tüm gönderici kimlikleri noreply@kilavuz.app adresini paylaşır. Hem auth.methods.email.fromField hem de emailSender.defaultFrom aynı değere ayarlıdır; bu sayede kimlik doğrulama ve operasyonel e-postalar tek bir doğrulanmış gönderici üzerinden çıkar.

RESEND_API_KEY gerçek bir API anahtarı değerine komut edilmez; değer, platformun gizli anahtar deposundan çalışma zamanında enjekte edilir. Bu sınırlamanın gerekçesi docs/deploy/ kilavuz-readiness.md içinde ayrıntılı olarak belgelenmiştir.

Yönetim paneli (admin)

admin.kilavuz.app adresinde çalışan yönetim paneli, aynı istemci kodu tabanını paylaşır ancak farklı bir derleme çıktısı olarak dağıtılır.

• Kullanıcı yönetimi: Kayıt olan tüm kullanıcıları listeler; isAdmin rolünü verir veya kaldırır.
• Faturalama görünümü: Kuruluşun kredi bakiyesini, lotlarını ve kullanım geçmişini yansıtır.
• Denetim kayıtları: Hassas işlemler için sunucu tarafında oluşturulan olay günlükleri, yönetici panelinin salt okunur tablolarında görüntülenir.

Yönetim paneli tarafı yalnızca isAdmin === true olan kullanıcılara açıktır; dil seçimi yetkilendirme kararlarını etkilemez.

Statik blog ve doküman servisi

blog.kilavuz.app adresinde çalışan Starlight sitesi, bir API’ye bağımlı değildir. Derleme zamanında üretilen düz HTML, nginx üzerinden servis edilir. İçerik güncellemeleri, yeni bir imaja gerek kalmadan bir sonraki dağıtımda yansır.

Üçüncü taraf istemci kütüphaneleri

Kütüphane	Kullanım amacı	Nerede
Stripe.js	Ödeme formu, SCA akışı	app/src/payment/
React Query	Sunucu durumunu istemci tarafında önbelleğe alma	app/src/client/
Wasp SDK	Kimlik doğrulama, eylemler ve sorgular	app/src/client/

Üçüncü taraf kütüphanelerinin sürümleri app/package.json ve blog/package.json altında kilitlenmiştir; herhangi bir yükseltme, üç bağımsız görüntü (api, web, admin) için ayrı ayrı test edilmelidir.