VibeFox iMile for OpenCart — Yardım

Gereksinimler

OpenCart: 3.0.x (3.0.5.0 sürümünde test edilmiştir) veya 4.0.2 ve üzeri (4.1.0.3 sürümünde test edilmiştir).

PHP: 8.0 veya üzeri.

iMile tarifesi: iMile satış ekibiyle kararlaştırdığınız fiyatlar. Bunları fiyat tablosuna mağazanızın varsayılan para biriminde girersiniz.

iMile API hesabı (yalnızca canlı tahmin için): canlı tahmin, iMile OpenAPI'nin "Estimated order delivery costs" servisini kullanır. Bir Customer ID ve bir Secret key gerekir (iMile'ın Customer ID'nizle birlikte verdiği API anahtarı). Test istemcisi için iMile geliştirici portalına (developer.imile.com) kaydolun. Canlı anahtarlar iMile hesap yöneticinizden alınır. Yalnızca fiyat tablosunu kullanıyorsanız API anahtarlarına ihtiyacınız yoktur.

VibeFox lisans anahtarı: vibefox.net üzerinden satın alınır. Bir anahtar tek bir alan adında çalışır.

Kurulum

Bu indirme, her iki OpenCart sürümü için paketleri içeren tek bir zip dosyasıdır. Bilgisayarınızda açın. İçinde README.txt, OpenCart 3 paketi vfd_imile-oc3-(version).ocmod.zip ve OpenCart 4 paketi vfd_imile.ocmod.zip bulunur. Yalnızca OpenCart sürümünüze uygun paketi kurun. Lisans anahtarı iki sürüm için de aynıdır.

OpenCart 3

1. Yönetici panelinde Extensions > Installer bölümüne gidin, Upload düğmesine tıklayın ve vfd_imile-oc3-(version).ocmod.zip dosyasını seçin. Uzantı OCMOD değişikliği eklemez, bu nedenle Extensions > Modifications bölümünü yenilemeniz gerekmez. Installer yerine bu paketin upload klasörünün içeriğini mağazanızın kök klasörüne de kopyalayabilirsiniz.

2. Extensions > Extensions bölümüne gidin ve uzantı türü olarak Shipping seçin. VibeFox iMile uzantısını bulun ve Install düğmesine (yeşil + düğmesi) tıklayın.

3. Ayarlar sayfasını açmak için Edit düğmesine (kalem düğmesi) tıklayın.

4. VibeFox lisans anahtarınızı Edit sayfasının üst kısmındaki lisans bloğunda, License key alanına girin ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

5. iMile fiyatlarınızı Price table bölümüne girin. İsterseniz Live rates (API) bölümünü doldurup Live estimate seçeneğini açın (bkz. Yapılandırma). Enable iMile seçeneğini açın ve Save düğmesine tıklayın.

OpenCart 4

1. Yönetici panelinde Extensions > Installer bölümüne gidin, Upload düğmesine tıklayın ve vfd_imile.ocmod.zip dosyasını seçin. Dosyanın adını değiştirmeyin: OpenCart 4 uzantı kodunu dosya adından alır, adı değiştirilmiş paket çalışmaz.

2. Paket, aynı sayfadaki kurulu uzantılar listesinde görünür. Yanındaki Install düğmesine (yeşil + düğmesi) tıklayın.

3. Extensions > Extensions bölümüne gidin ve uzantı türü olarak Shipping seçin. VibeFox iMile uzantısını bulun, Install düğmesine (yeşil + düğmesi) ve ardından Edit düğmesine (kalem düğmesi) tıklayın.

4. Lisans anahtarını ve ayarları OpenCart 3 için 4. ve 5. adımlardaki gibi girin. Ayarlar sayfası ve alanları iki sürümde de aynıdır.

Kurulumdan sonra, Enable iMile seçeneğini açıp kaydedene kadar yöntem kapalı kalır. Uzantıyı kaldırdıktan sonra yeniden kurarsanız, sakladığınız iMile ayarları yeniden kullanılır.

Yapılandırma

Tüm ayarlar uzantı sayfasındadır: Extensions > Extensions > Shipping > VibeFox iMile > Edit. Bölümler solda listelenir. Save düğmesi tüm sayfayı yeniden yüklemeden kaydeder. Her kayıt ayrıca önbelleğe alınmış iMile tahminlerini ve erişim belirteçlerini temizler. Ayarları yalnızca bu uzantı için değiştirme yetkisine sahip yönetici kullanıcılar kaydedebilir.

Kaydederken uzantı şunları kontrol eder: Method title geçerli mi (en fazla 64 karakter, < > ; = # { } karakterleri olmadan), fiyat, tutar ve ağırlık alanları 0 veya daha büyük sayılar mı, Minimum weight (kg) Maximum weight (kg) değerinden büyük değil mi, Sort order bir tam sayı mı, vergi sınıfı ve coğrafi bölge var mı. Aksi halde bir hata gösterir ve hiçbir şey kaydetmez.

Live estimate açık olup çalışamadığında ayarların üstünde (ve kayıttan sonra yeniden) uyarılar görünür: Customer ID veya Secret key boş, gönderim şehri veya ülkesi eksik (ya da ülke bir iMile pazarı değil), döviz kuru yok ya da fiyat tablosu boş ve diğer ülkeler için fiyat yok. Mağazada kg birimli bir ağırlık sınıfı yoksa ve varsayılan ağırlık sınıfının birimi uzantı tarafından bilinmiyorsa da uyarı görünür: ürün ağırlıkları bu durumda kilogram kabul edilir, bu nedenle System > Localisation > Weight Classes bölümünden bir kg ağırlık sınıfı ekleyin.

Genel

Ayarlar tüm coğrafi bölgeler için geçerlidir. Yöntemi Conditions bölümünde bir coğrafi bölgeyle sınırlayabilir ya da Countries bölümünde Ignore shipping zones seçeneğini açarak bir ülke listesiyle sınırlayabilirsiniz.

Enable iMile: iMile'ın ödeme sırasında gösterilip gösterilmeyeceğini belirler. Varsayılan: kapalı.

Method title: sepette ve ödeme sırasında müşteriye gösterilen kargo yöntemi adı. Varsayılan: iMile. Zorunludur.

Sort order: iMile'ın ödeme sırasında kargo yöntemleri arasındaki konumu. Bir tam sayıdır.

Canlı tarifeler (API) (isteğe bağlı)

iMile hiçbir tahmin döndürmezse (anahtar yok, şehir henüz girilmedi, hata, zaman aşımı, döviz kuru yok), fiyat tablosu kullanılır.

Live estimate: iMile'dan kargo maliyetini almak için açın. Varsayılan: kapalı. Canlı tahmin kapalıyken ödeme sırasında iMile'a hiçbir şey gönderilmez.

Environment: Production (openapi.imile.com) (varsayılan) veya Test (test-openapi.52imile.cn). Test anahtarları yalnızca test sunucusunda çalışır ve test fiyatları verir.

Customer ID: iMile'ın verdiği müşteri kodu (customerId), örneğin C2102192601. Silindiğinde kaydedilmiş Secret key de silinir.

Secret key: iMile'ın Customer ID ile birlikte verdiği gizli anahtar (API anahtarı). İstekleri imzalar. Kaydettikten sonra alan boş kalır ve Saved — leave empty to keep it. ifadesini gösterir. Yalnızca değiştirmek istediğinizde yeni bir değer girin.

Signature: isteklerin nasıl imzalandığı.

Ship-from country: gönderim yaptığınız ülke. İlk seçenek olan Store country, mağazanızın ülkesini kullanır. Liste yalnızca uzantının iMile ülke kodlarını bildiği ülkeleri içerir.

Ship-from city: paketlerinizin gönderildiği şehir; iMile şehir listesindeki gibi yazılır (örneğin Dubai, Riyadh). Canlı tahminler için zorunludur: OpenCart'ta mağaza şehri yoktur, bu nedenle bu alan olmadan yalnızca fiyat tablosu kullanılır.

Ship-from province: isteğe bağlı, örneğin Dubai veya Riyadh Province.

iMile service: iMile'a gönderilen sipariş türü: Delivery order (100) (varsayılan) veya Express order (1100). Express, hesabınız ve ülkeniz için etkin olmalıdır.

Goods category: iMile'a bildirilen mal türü: Normal goods (varsayılan), Sensitive (cosmetics, liquids...), With battery, Batteries / power banks, Documents veya Parcel.

Exchange rates: iMile, hedef ülkenin para biriminde tahmin verir. Her para birimi için bir satır girin; bu satırda 1 birimin mağazanızın varsayılan para birimindeki fiyatı yer alır, örneğin "AED = 0.25" veya "SAR = 0.24". Mağazanın kendi para birimi için kur gerekmez. Kur olmadan o para birimindeki tahminler kullanılmaz ve bunun yerine fiyat tablosu uygulanır. Aynı kur, iMile'a bildirilen sepet değerini de dönüştürür.

Fiyatlar (canlı tahmin kapalıyken kullanılır ve iMile tahmin döndürmediğinde yedek olarak kullanılır)

iMile tarifenizi mağazanızın varsayılan para biriminde, vergi hariç girin. AED, SAR veya başka bir para birimindeyse önce çevirin.

Price table: hedef ülke başına bir satır. Satır eklemek için Add country düğmesine, satır silmek için × düğmesine tıklayın. Kendi satırı olmayan tüm ülkeleri kapsayan bir satır için * All other countries seçin. Her satırda bir Base price ve isteğe bağlı ağırlık sütunları bulunur: XS ≤1 kg, S ≤2 kg, M ≤3 kg, L ≤5 kg ve XL >5 kg. Boş (veya 0) bir ağırlık sütunu temel fiyatı kullanır. Temel fiyatın 0 olması o ülkeye ücretsiz teslimat anlamına gelir. Hem "9.99" hem de "9,99" kabul edilir.

Price for countries not in the table: mağazanın varsayılan para biriminde bir fiyat. Tabloda hedef ülke için satır yoksa (ve * satırı yoksa) ya da satırda bu ağırlık için fiyat yoksa kullanılır. Bu durumda yöntemi gizlemek için boş bırakın.

Price applies: fiyatın nasıl uygulanacağı.

Aynı seçim canlı tahmin için de geçerlidir: sipariş başına, tüm sepeti tek bir koliyle gönderir; ürün başına, her farklı koli için tahmin ister ve birim sayısıyla çarpar. Sepette 5'ten fazla farklı koli varsa fiyat tablosu kullanılır.

Ürün ağırlıkları OpenCart ağırlık sınıfından kilograma, boyutları uzunluk sınıfından santimetreye dönüştürülür.

Koşullar

Minimum weight (kg): sepet ağırlığı bunun altındaysa yöntemi gizler. 0 sınır olmadığı anlamına gelir (varsayılan).

Maximum weight (kg): sepet ağırlığı bunun üstündeyse yöntemi gizler. Varsayılan: 30. 0 sınır olmadığı anlamına gelir. Alanı boş bırakırsanız 30 kg kullanılır.

Minimum order amount: yöntemi yalnızca kargolanması gereken ürünlerin ara toplamı (kupondan sonra, vergi öncesi) bu tutara ulaştığında gösterir. Her zaman göstermek için boş bırakın.

Free shipping from: kargolanması gereken ürünlerin ara toplamı (kupondan sonra, vergi öncesi) bu tutara ulaştığında iMile teslimatı ücretsizdir. Hiçbir zaman ücretsiz kargo sunmamak için boş bırakın.

Tax class: kargo maliyetinin vergi sınıfı veya No tax (varsayılan). Tablodaki fiyatlar ve iMile tahminleri KDV'yi zaten içeriyorsa No tax seçin.

Geo zone: iMile'ı yalnızca bu coğrafi bölgedeki adresler için sunar. All zones (varsayılan) sınır olmadığı anlamına gelir. Ignore shipping zones açıkken coğrafi bölge kontrol edilmez. Coğrafi bölgeler System > Localisation > Geo Zones bölümünde yönetilir.

Ülkeler

Ignore shipping zones: açıkken Geo zone kontrol edilmez ve iMile aşağıdaki ülkeler için sunulur. Kapalıyken (varsayılan) yalnızca Geo zone geçerlidir.

Countries: izin verilen hedef ülkeler. Mağazada etkin olan tüm ülkelere izin vermek için boş bırakın. Bu alan yalnızca Ignore shipping zones açıkken kullanılır.

Gelişmiş

Debug log: tarife hesaplamalarını storage/logs/vfd_imile_debug.log.php dosyasına yazar (OpenCart 4'te system/storage/logs/vfd_imile_debug.log.php). Dosya web üzerinden okunamaz. Anahtarlar ve müşteri adresleri kaydedilmez. Başarısız iMile istekleri, hata ayıklama günlüğü kapalı olsa bile her zaman kaydedilir. İşiniz bittiğinde günlüğü kapatın. Dosya 5 MB'a ulaştığında vfd_imile_debug.old.log.php dosyasına taşınır ve yeni bir günlük başlatılır.

Log: hata ayıklama günlüğünün boyutunu ve en son kayıtlarını gösterir. Temizlemek için Clear log düğmesine tıklayın.

Remove data on uninstall: açıkken uzantıyı kaldırmak iMile ayarlarını ve günlüğü siler. Kapalıyken (varsayılan) ayarlar yeniden kurulum için saklanır. Önbelleğe alınmış tahminler ve erişim belirteçleri her zaman silinir.

İçe / Dışa Aktarma

Export: ayarları bir JSON dosyası olarak kaydetmek için Download JSON düğmesine tıklayın. Secret key dışa aktarılmaz.

Import: daha önce dışa aktarılmış JSON'u yapıştırın ve ayarları geri yüklemek için Import düğmesine tıklayın; örneğin başka bir mağazada. Değerler normal bir kayıttaki gibi kontrol edilir. Kaydedilmiş Secret key korunur.

Ödeme sırasında nasıl çalışır

OpenCart kargo yöntemlerini gösterirken uzantıdan iMile fiyatını ister. Bir Geo zone ayarlıysa, Ignore shipping zones kapalıysa ve adres coğrafi bölgenin dışındaysa iMile sunulmaz. Yalnızca Requires Shipping değeri Yes olan ürünler sayılır: diğer ürünler ağırlığa eklenmez ve sipariş tutarına dahil edilmez. Ardından uzantı koşulları kontrol eder: izin verilen ülkeler (Ignore shipping zones açıksa), sepet ağırlığı ve minimum sipariş tutarı. Sipariş tutarı, kargolanması gereken ürünlerin kupon indiriminden sonra ve vergi öncesi fiyatıdır. Hediye çekleri, puanlar ve mağaza kredisi dikkate alınmaz. Ücretsiz kargo uygulanıyorsa fiyat 0 olur ve iMile'a istek gönderilmez.

Canlı tahmin açıkken uzantı, iMile'a gönderim ülkesini, ilini ve şehrini, hedef ülkeyi, bölgeyi, şehri ve posta kodunu, kg cinsinden sepet ağırlığını, cm³ cinsinden boyutu (ürün boyutlarından), sepet değerini, iMile hizmetini ve mal kategorisini gönderir. Tahmin her zaman ön ödemeli olarak istenir, bu nedenle kapıda ödeme ücretleri dahil edilmez. Canlı tahmin yalnızca müşteri şehirli bir teslimat adresi girdikten sonra ve yalnızca sepetteki her ürünün ağırlığı olduğunda istenir.

Her yanıt 1 saat önbelleğe alınır. Başarısız bir istek 5 dakika önbelleğe alınır. Zaman aşımı veya sunucu hatasından sonra iMile 2 dakika boyunca sorgulanmaz; reddedilen anahtarlardan sonra 5 dakika boyunca sorgulanmaz. Böylece ödeme sayfası her yenilemede iMile'ı beklemez. API zaman aşımı 12 saniyedir. Süresi dolmuş bir erişim belirteci otomatik olarak yenilenir.

Tahmin, kurlarınızla mağazanın varsayılan para birimine çevrilir. iMile kullanılabilir bir tahmin vermezse (anahtarlar ayarlanmamış, şehir henüz girilmemiş, bilinmeyen şehir, hata, zaman aşımı, döviz kuru yok), müşteri bir hata görmez ve tablodaki fiyat kullanılır. Tabloda da fiyat yoksa yöntem gizlenir. Neden günlüğe yazılır. Fiyat, varsayılan para biriminizde hesaplanır, ondalık basamaklarına yuvarlanır ve müşteriye kendi para biriminde, seçilen Tax class vergisiyle gösterilir.

OpenCart 4'te müşteri, ödeme sayfasındaki kargo yöntemi bloğunda Choose düğmesine tıklar ve Shipping method options penceresinde iMile'ı seçer. Yöntem OpenCart 3'tekiyle aynı şekilde çalışır.

Uzantı yalnızca tarifeleri hesaplar. iMile gönderileri oluşturmaz, AWB etiketleri yazdırmaz, kurye talep etmez, kargoları takip etmez, kapıda ödeme tutarlarını uzlaştırmaz ve teslim alma noktaları ya da dolapları sunmaz. Siparişlere hiçbir şey eklemez: sipariş, diğer tüm OpenCart kargo yöntemleri gibi yöntem adını ve kargo maliyetini gösterir. Gönderiler için iMile portalını kullanın.

Lisans anahtarı

Uzantı, vibefox.net üzerinden alınmış bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu License — VibeFox iMile, Extensions > Extensions > Shipping > VibeFox iMile > Edit sayfasında ayarların üstündeki ilk bloktur. Anahtarı License key alanına girin ve Activate düğmesine tıklayın. Bundan sonra blok anahtarı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu tarih ve alan adınız) ve Check now (durumu yeniden kontrol eder), Change key (başka bir anahtar girer) ve Remove key (anahtarı bu mağazadan kaldırır) düğmelerini gösterir. Bunların altında Product: opencart-shipping-imile satırı ve Manage licenses and domains in your account bağlantısı bulunur; bağlantı vibefox.net hesabınızı açar. Anahtarı yalnızca bu uzantı için değiştirme yetkisine sahip yönetici kullanıcılar değiştirebilir. Bloktaki metinler yönetici paneli dilini izler (İngilizce ve Rusça dahildir).

Anahtar kabul edilmezse blok nedenini gösterir; örneğin Key not found, This key belongs to another product, Domain limit reached veya tarihiyle birlikte License expired on. Mağaza adresi değiştikten sonra ya da hesabınızda bir alan adı yuvasını serbest bıraktıktan sonra Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamazsa uzantı son bilinen durumla çalışmaya devam eder.

Bir anahtar tek bir alan adında çalışır: OpenCart yapılandırmasındaki mağaza adresi. Anahtarı mağazadan kaldırmak alan adı yuvasını serbest bırakmaz. Yuvayı vibefox.net hesabınızdan serbest bırakın.

Etkin bir anahtar olmadan iMile kargo yöntemi ödeme sırasında müşterilere gösterilmez ve tarife hesaplanmaz. Yönetici paneline aynı tarayıcıda giriş yapmış bir yönetici kullanıcı, yöntemi yine de mağazada (unlicensed — visible to admins only) işaretiyle görür; böylece anahtarı satın almadan önce uzantıyı kurup test edebilirsiniz. OpenCart 4'te bu ön izleme kullanılamaz: mağaza yönetici girişini görmez, bu nedenle etkin bir anahtar olmadan kargo yöntemi herkesten gizlenir. Edit sayfasını bir kez açtıktan sonra yönetici Dashboard ekranında bir hatırlatma görünür. Bunu × ile kapatırsanız 7 gün boyunca gizlenir. Mevcut siparişler etkilenmez.

Lisans süresi dolduğunda uzantı çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Yönetici Dashboard ekranını veya Edit sayfasını açtığınızda durum otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün her gün, sonra haftada bir. Cron işi gerekmez. Uzantı kaldırıldığında lisans anahtarı ve lisans durumu her zaman silinir.

Sorun giderme

iMile ödeme sayfasında görünmüyor: lisansın etkin olduğunu ve Enable iMile seçeneğinin açık olduğunu kontrol edin. Geo zone, Ignore shipping zones ve Countries ayarlarını, ağırlık sınırlarını ve Minimum order amount değerini kontrol edin. Ülkenin veya * All other countries satırının Price table içinde bir satırı olduğunu ya da Price for countries not in the table değerinin girildiğini kontrol edin. Ürünlerin Requires Shipping değerinin Yes olduğunu doğrulayın.

iMile tahmini yerine tablodaki fiyat gösteriliyor: Debug log seçeneğini açın, ödeme sayfasını yenileyin ve uzantı sayfasındaki Log alanına bakın. Yaygın nedenler: Live estimate kapalı, anahtarlar eksik, Ship-from city boş, müşteri henüz şehir girmemiş, iMile şehir yazımını tanımıyor, ürünlerin ağırlığı yok, hedef para birimi için kur yok ya da bir API hatası. Ayarların üstündeki uyarıları da kontrol edin.

Günlükte "sign is invalid": Secret key değerini kontrol edin, ardından Signature = SimpleKey seçeneğini deneyin.

Anahtarlar reddediliyor: Customer ID, Secret key ve Environment değerlerini kontrol edin. Test anahtarları yalnızca test sunucusuyla çalışır.

Şehir adları eşleşmiyor: şehir adları iMile şehir listesiyle eşleşmelidir. Geliştiriciler isteği vfd_imile/live_request OpenCart olayıyla, ülke kodlarını ise vfd_imile/live_country_code olayıyla değiştirebilir.

Fiyatlar yanlış para biriminde: fiyat tablosu mağazanın varsayılan para biriminde girilir. AED, SAR veya MXN cinsinden bir tarifeyi girerken çevirin. Canlı tahminler Exchange rates ile çevrilir.

Kargoda vergi iki kez alınıyor: fiyatlarınız KDV'yi zaten içeriyorsa Tax class değerini No tax yapın.

Bir değişiklikten sonra tahminler eski görünüyor: uzantı sayfasında Save düğmesine tıklayın. Bu, önbelleğe alınmış iMile tahminlerini temizler.

Sayfada "Warning: You do not have permission to modify VibeFox iMile!" yazıyor: yönetici kullanıcı grubunuz ayarları yalnızca görüntüleyebiliyor. Gruba System > Users > User Groups bölümünde extension/shipping/vfd_imile (OpenCart 3) veya extension/vfd_imile/shipping/vfd_imile (OpenCart 4) için değiştirme yetkisi verin.

Kaldırma

Extensions > Extensions bölümüne gidin, Shipping türünü seçin ve VibeFox iMile satırının yanındaki Uninstall düğmesine (kırmızı − düğmesi) tıklayın. Bu uzantının lisans anahtarı ve lisans durumu her zaman kaldırılır. OpenCart her zaman Enable iMile, Sort order, Tax class ve Geo zone ayarlarını sıfırlar. Önbelleğe alınmış tahminler ve erişim belirteçleri her zaman kaldırılır. Remove data on uninstall açıksa iMile ayarları ve hata ayıklama günlüğü de silinir. Kapalıysa diğer ayarlar korunur ve uzantıyı yeniden kurduğunuzda tekrar kullanılır. Mevcut siparişler kargo yöntemini ve maliyetini korur.

OpenCart 4'te, uzantının dosyalarını da kaldırmak için kaldırma işleminden sonra Extensions > Installer bölümüne gidin, kurulu uzantılar listesinde VibeFox iMile yanındaki Uninstall düğmesine (turuncu − düğmesi) tıklayın, ardından yüklenen paketi silmek için Delete düğmesine (kırmızı çöp kutusu düğmesi) tıklayın.

iMile, sahibinin ticari markasıdır. Bu uzantı iMile ile bağlantılı değildir ve iMile tarafından onaylanmamıştır.