Loomix
BelgelerGeliştirici KılavuzuYerel Özellikler ve Ödeme Ağ Geçitleri

🇮🇷 Bölgesel ve Yerel Özellikler Kapsamlı Rehberi (Iran Features)

Next-Strapi-Medusa projesi, yerel e-ticaret altyapıları için kurumsal düzeyde entegre destek sunar. ENABLE_IRAN_FEATURES=true bayrağı etkinleştirildiğinde; cep telefonu numarası ile giriş ve SMS OTP, yerel banka ağları ve ödeme geçitleri (Zarinpal), canlı kargo ücreti hesaplama ve yerel para birimi dönüşümleri Medusa çekirdeğine dokunulmadan aktif hale gelir.

Medusa Çekirdeği Değiştirilmeden Yerel Destek
Tüm yerel modüller (ödeme geçidi, SMS OTP ve kargo gönderimi), Medusa v2 standartlarına uygun bağımsız modüller olarak tasarlanmıştır; bu sayede güncellemelerde kod bozulması yaşanmaz.

1. Genel ENABLE_IRAN_FEATURES Bayrağı

Tüm sistemde (Medusa arka uç, Strapi CMS ve Next.js Mağaza Arayüzü) yerel özellikleri etkinleştirmek için .env ve docker-compose.yml dosyalarınızda aşağıdaki değişkenleri tanımlayın:

.env
env
ENABLE_IRAN_FEATURES=true
NEXT_PUBLIC_ENABLE_IRAN_FEATURES=true
DEFAULT_REGION=IR
DEFAULT_LOCALE=fa-IR

2. Cep Telefonu Numarası ve SMS OTP ile Giriş (Phone Auth & OTP)

Özel telefon kimlik doğrulama modülü store-admin/src/modules/auth/providers/otp altında geliştirilmiştir. Yerel telefon numaralarını standart hale getirir, güvenli 4-6 haneli geçici doğrulama kodları üretir ve hız sınırlaması (rate limiting) uygular.

  • Çoklu format desteği: 0912xxxxxxx ve +98912xxxxxxx formatlarını otomatik olarak kabul eder.
  • Geri sayım sayacı ve hız sınırlaması: 120 saniyelik bekleme süresi (cooldown) ile mükerrer SMS isteklerini engeller.
  • Otomatik Kayıt: Yeni doğrulanan telefon numaraları için otomatik olarak müşteri hesabı oluşturur.
store-admin/medusa-config.ts (phone-auth bölümü)
typescript
{
  resolve: "./src/modules/auth/providers/otp",
  id: "phone-auth",
  options: {
    jwtSecret: process.env.JWT_SECRET,
  },
}

3. SMS Servis Entegrasyonları (Kavenegar & SMS.ir)

SMS gönderim servisi, doğrulama kodlarının reklam engelli numaralara bile 5 saniyenin altında ulaşması için hızlı şablon (Fast Pattern / servis hattı) web kancalarını destekler:

.env (SMS Ağ Geçidi Yapılandırması)
env
# Sağlayıcı: sms-ir veya kavenegar
SMS_PROVIDER=sms-ir
SMS_API_KEY=sms_ir_api_anahtariniz
SMS_OTP_TEMPLATE_ID=100000 # Doğrulama şablon ID'si
SMS_ORDER_PLACED_TEMPLATE_ID=200000 # Sipariş onay şablon ID'si

4. Çevrimiçi Ödeme Ağ Geçidi Entegrasyonu

Ödeme modülü, Medusa'nın Payment Sessions sistemine doğrudan entegre olarak yerel banka kartlarıyla işlemleri mümkün kılar ve geliştirme ortamı için test modunu (Sandbox) destekler:

.env (Ödeme Ağ Geçidi Ayarları)
env
ZARINPAL_MERCHANT_ID=magaza-id-xxxx-xxxx
ZARINPAL_SANDBOX=false # Geliştirme ortamında true yapın

5. Canlı Kargo Ücreti Hesaplama

medusa-fulfillment-iran-post eklentisi, ödeme (Checkout) aşamasında çıkış yeri, varış ili ve paket ağırlığına göre hızlı ve standart kargo ücretlerini dinamik olarak hesaplar ve sipariş yönetim panelinde 24 haneli takip kodlarını destekler.

store-admin/medusa-config.ts (kargo modülü bölümü)
typescript
{
  resolve: "./src/modules/fulfillment/providers/iran-post",
  id: "iran-post",
  options: {
    originProvince: "تهران",
    originCity: "تهران",
    defaultPackagingWeight: 150, // گرم
  },
}

6. Otomatik Para Birimi Dönüşümü (convertToToman)

Fiyatlar veritabanında en küçük birimde saklanır. Strapi'deki Storefront Settings bölümünde convertToToman seçeneği etkinleştirildiğinde, ön yüz bir sıfır silerek sayıları binlik basamak ayracıyla formatlar.

Ön yüzde para birimi dönüşümü (store/src/lib/util/prices.ts)
typescript
export function formatPrice(amount: number, currencyCode: string, convertToToman = false) {
  if (currencyCode.toLowerCase() === 'irr' && convertToToman) {
    const tomanAmount = Math.round(amount / 10);
    return `${new Intl.NumberFormat('fa-IR').format(tomanAmount)} تومان`;
  }
  return new Intl.NumberFormat('fa-IR', { style: 'currency', currency: currencyCode }).format(amount);
}