VibeFox Mercado Envios for OpenCart — Yardım

Gereksinimler

OpenCart: 3.0.x (3.0.5.0 ile test edildi) veya 4.0.2 ve üzeri (4.1.0.3 ile test edildi).

PHP: 8.0 veya üzeri.

Mercado Pago hesabı (yalnızca anlık tarifeler için): anlık tarifeler, Arjantin, Brezilya veya Meksika'daki Mercado Pago hesabınızın Mercado Envios hesaplayıcısından gelir. Mercado Envios bu hesap için etkin olmalıdır. Paketler, bu hesapta tanımlı gönderim adresinden fiyatlandırılır. Üretim erişim jetonuna (APP_USR- ile başlar) ihtiyacınız var: Mercado Pago Developers'ta uygulamanızı ve üretim kimlik bilgilerini açın. Giriş düğmesi yoktur: jetonu uzantı ayarlarına yapıştırırsınız. Yalnızca ülkeye göre fiyatları kullanıyorsanız Mercado Pago hesabı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

İndirme dosyası, 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_mercado_envios-oc3-(version).ocmod.zip ve OpenCart 4 paketi vfd_mercado_envios.ocmod.zip bulunur. Yalnızca kullandığınız OpenCart sürümünün paketini kurun. Lisans anahtarı iki sürüm için de aynıdır.

OpenCart 3

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

2. Extensions > Extensions sayfasına gidin ve uzantı türü olarak Shipping seçin. VibeFox Mercado Envios 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ündeki lisans bloğundaki License key alanına girin ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

5. Anlık tarifeler için erişim jetonunu yapıştırın, Mercado Envios ülkesini seçin ve mağazanızın varsayılan para birimi ARS, BRL veya MXN değilse döviz kurunu girin. İsteğe bağlı olarak Country prices ve Fallback cost alanlarını doldurun (anlık tarife olmadan kullanılır). Enable Mercado Envios shipping seçeneğini açın ve Save düğmesine tıklayın.

OpenCart 4

1. Yönetici panelinde Extensions > Installer sayfasına gidin, Upload düğmesine tıklayın ve vfd_mercado_envios.ocmod.zip dosyasını seçin. Dosya adını değiştirmeyin: OpenCart 4 eklenti kodunu dosya adından alır, adı değiştirilmiş paket çalışmaz.

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

3. Extensions > Extensions sayfasına gidin ve eklenti türü olarak Shipping seçin. VibeFox Mercado Envios eklentisini bulun, Install düğmesine (yeşil +) ve sonra Edit düğmesine (kalem düğmesi) tıklayın.

4. Lisans anahtarını ve ayarları OpenCart 3'teki 4. ve 5. adımlarda olduğu gibi girin. Ayar sayfası ve alanları iki sürümde de aynıdır.

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

Yapılandırma

Tüm ayarlar uzantı sayfasındadır: Extensions > Extensions > Shipping > VibeFox Mercado Envios > Edit. Bölümler solda listelenir. Tek bir Save düğmesi tüm sayfayı yeniden yüklemeden kaydeder. Her kayıt ayrıca önbelleğe alınmış Mercado Envios tarifelerini ve son API hatasını temizler. Ayarları yalnızca bu uzantı için değiştirme yetkisine sahip yönetici kullanıcılar kaydedebilir.

General bölümündeki uyarılar (ve her kayıttan sonra) yapılandırma sorunlarını gösterir: eksik döviz kuru, erişim jetonu ve fiyat yoksa (bu durumda yöntem hiç gösterilmez), tarihiyle birlikte son Mercado Envios API hatası ve uzantının tanımadığı bir mağaza ağırlık veya uzunluk birimi (bu durumda kg veya cm olarak okunur). Name boşsa veya 64 karakterden uzunsa, Exchange rate pozitif bir sayı değilse, başka bir sayısal alan 0 veya daha büyük bir sayı değilse ya da Min weight, Max weight değerinden büyükse, sayfa bir hata gösterir ve hiçbir şey kaydedilmez.

Genel

Müşteri tek bir Mercado Envios tarifesi görür. Availability altında yöntemi bir coğrafi bölge ya da ülkelerle sınırlayabilirsiniz. Bu ayarlar tüm bölgeler için geçerlidir.

Enable Mercado Envios shipping: Mercado Envios'i ödeme sayfasında gösterir veya gizler. Varsayılan: kapalı.

Name: sepette ve ödeme sayfasında müşterilere gösterilen kargo yöntemi adı. Varsayılan: Mercado Envios. Zorunlu, en fazla 64 karakter.

Tax class: kargo ücretinin vergi sınıfı veya No tax (varsayılan). Mercado Envios nihai fiyatları verir. No tax bunları verildiği gibi gösterir; bir vergi sınıfı ise kargo vergisinizi üzerine ekler.

Sort order: Mercado Envios'in ödeme sayfasındaki kargo yöntemleri arasındaki konumu. Tam sayı.

Mercado Envios API (anlık tarifeler) (jeton olmadan yalnızca aşağıdaki fiyatlar kullanılır)

Access token: Mercado Pago üretim erişim jetonunuz (APP_USR-...). Yalnızca api.mercadopago.com adresine gönderilir ve asla günlüğe yazılmaz. Kaydettikten sonra alan boş kalır ve Saved — leave empty to keep it. ifadesini gösterir. Yalnızca değiştirmek için yeni bir değer girin.

Remove the saved access token: kayıtlı jetonu silmek için açın ve kaydedin. Bundan sonra yalnızca aşağıdaki fiyatlar kullanılır. Yukarıya yazılan bir jeton ise kayıtlı jetonun yerine geçer.

Mercado Envios country: Mercado Pago hesabınızın ülkesi: Argentina (ARS) (varsayılan), Brazil (BRL) veya Mexico (MXN). Anlık tarifeler yalnızca bu ülkedeki hedefler için istenir ve o ülkenin para biriminde verilir.

Exchange rate: yalnızca mağazanızın varsayılan para birimi Mercado Envios para biriminden farklıysa gerekir: 1 ARS, BRL veya MXN'nin mağazanızın varsayılan para birimindeki fiyatı, örneğin 0.001. Bu olmadan anlık tarifeler kullanılmaz. Pozitif bir sayı olmalıdır. Ondalık ayırıcı olarak hem nokta hem virgül kabul edilir.

Anlık tarife olmadan fiyatlar

Bu fiyatlar, erişim jetonu yoksa, hedef Mercado Envios ülkesinin dışındaysa ve API bir tarife vermezse kullanılır (başarısız bir istek 5 dakika sonra yeniden denenir). Mağazanızın varsayılan para biriminde ve vergi hariç verilir.

Country prices: hedef ülkelerin ve fiyatların bir tablosu. Satır eklemek için Add country düğmesine, bir satırı silmek için silme düğmesine tıklayın. Kendi satırı olmayan tüm ülkeler için * All other countries seçin. Price ülkenin fiyatıdır. XS (1 kg'a kadar), S (1-2 kg), M (2-3 kg), L (3-5 kg) ve XL (5 kg'dan fazla) sütunları, sepetin o ağırlığı için bunun yerine geçer. Boş veya 0 olan bir sütun Price değerini kullanır. Price değeri 0 ise o ülkeye ücretsiz kargo anlamına gelir. Hem 9.99 hem de 9,99 kabul edilir. Sayı olmayan değerler kayıttan sonra bildirilir ve temizlenir. Hiçbir fiyatı olmayan satırlar kaydederken silinir.

Fallback cost: ne API ne de Country prices bir fiyat verdiğinde kullanılır. Bu durumda yöntemi gizlemek için boş bırakın.

Calculation type: Per order (varsayılan) fiyatı bir kez alır. Per item (each item priced by its own weight x quantity) her ürünün ağırlığı için Country prices (veya Fallback cost) değerine bakar ve miktarıyla çarpar. Bir ürün fiyat alamazsa yöntem gizlenir. Mercado Envios anlık tarifeleri her zaman tüm paket içindir.

Uygunluk

Min weight (kg): bu yöntemin görünmesi için gereken en düşük sepet ağırlığı. 0, sınır olmadığı anlamına gelir (varsayılan).

Max weight (kg): sepet daha ağır olduğunda yöntemi gizler. Varsayılan: 25. Boş, 25 kg anlamına gelir; 0 sınır olmadığı anlamına gelir.

Minimum subtotal: yöntemi yalnızca kargo gerektiren ürünlerin ara toplamı (kupondan sonra, vergiden önce) en az bu tutara ulaştığında gösterir. Her zaman göstermek için boş bırakın.

Geo zone: Mercado Envios'i 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.

Ignore shipping zones: seçili coğrafi bölgeye bakılmaksızın yöntemi aşağıdaki ülkeler için sunar.

Countries: bu mod için hedef ülkeler. Mağazanın etkin tüm ülkeleri için boş bırakın. Bu alan yalnızca Ignore shipping zones açıkken kullanılır.

Ücretsiz kargo

Free shipping from: kargo gerektiren ürünlerin ara toplamı (kupondan sonra, vergiden önce); bu tutardan itibaren yöntem ücretsizdir. Bu durumda API isteği yapılmaz. Devre dışı bırakmak için boş bırakın.

Gelişmiş

Debug log: API isteklerini ve tarife hesaplamasını storage/logs/vfd_mrcv_debug.log.php dosyasına yazar (OpenCart 4'te system/storage/logs/vfd_mrcv_debug.log.php). Dosya web üzerinden okunamaz. Bu seçenek kapalı olsa bile hatalar her zaman günlüğe yazılır. Erişim jetonu ve müşteri adresleri asla günlüğe yazılmaz. Dosya 5 MB'a ulaştığında vfd_mrcv_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 son girişlerini gösterir. Boşaltmak için Clear log düğmesine tıklayın.

Remove data on uninstall: açıkken uzantıyı kaldırmak ayarları ve günlüğü siler. Kapalıyken (varsayılan) yeniden kurulum için korunur. Önbellekteki tarifeler her zaman silinir. Verilen siparişlerin Mercado Envios verileri her zaman sipariş geçmişi olarak saklanır.

İçe / Dışa Aktarma

Export: ayarları JSON dosyası olarak kaydetmek için Download JSON düğmesine tıklayın. Erişim jetonu 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ıtta olduğu gibi kontrol edilir. Kayıtlı erişim jetonu korunur.

Ödeme sayfasında nasıl çalışır

OpenCart kargo yöntemlerini gösterdiğinde, uzantıdan Mercado Envios fiyatını ister. Geo zone ayarlıysa ve adres bölgenin dışındaysa Mercado Envios sunulmaz (Ignore shipping zones açık değilse; açıksa Countries belirler). Yalnızca Requires Shipping değeri Yes olarak ayarlanmış ürünler sayılır: diğer ürünler ağırlık eklemez ve ara toplama dahil edilmez. Uzantı ardından sepet ağırlığını ve en düşük ara toplamı kontrol eder. Ara toplam, kupon indiriminden sonra ve vergiden önce, kargo gerektiren ürünlerin fiyatıdır. Hediye sertifikaları, bonus puanlar ve mağaza kredisi dikkate alınmaz. Ücretsiz kargo uygulanırsa fiyat 0 olur ve Mercado Envios'e istek gönderilmez.

Geçerli bir posta koduna sahip Mercado Envios ülkesindeki bir hedef için (Arjantin'de 4 hane, C1425ABC gibi bir CPA'dan da; Brezilya'da 8 hane; Meksika'da 5 hane), uzantı sepeti tek bir paket olarak tanımlar: ürünlerin en büyük genişliği ve uzunluğu, tüm ürünlerin yüksekliklerinin toplamı ve gram cinsinden toplam ağırlık. Ürün ağırlıkları ve boyutları OpenCart ağırlık ve uzunluk sınıflarından dönüştürülür. Her kenar ve ağırlık, ülkenin Mercado Envios minimumlarına yükseltilir; bu sayede boyutu veya ağırlığı olmayan ürünler de bir tarife alır. Sepet değeri, Mercado Envios para biriminde ürün fiyatı olarak gönderilir. Mercado Envios'in döndürdüğü en ucuz seçenek, mağazanızın varsayılan para birimine çevrilir, ondalık basamaklarına yuvarlanır ve seçili Tax class vergisiyle müşterinin para biriminde gösterilir.

Her teklif en fazla 1 saat önbelleğe alınır (OpenCart önbellek süresinden uzun değil), böylece aynı sepet yeni bir istek tetiklemez. Başarısız bir teklif 5 dakika tekrarlanmaz. Mercado Pago'ya ulaşılamazsa, jetonu reddederse, istekleri sınırlarsa veya başka bir para biriminde yanıt verirse, tüm anlık teklifler 5 dakika duraklatılır; böylece ödeme sayfası her yenilemede API'yi beklemez. API zaman aşımı 10 saniyedir.

Anlık tarife olmadan fiyatlar; jeton yoksa, hedef Mercado Envios ülkesinin dışındaysa, posta kodu eksik veya geçersizse, döviz kuru eksikse, paket ülkenin Mercado Envios sınırından ağırsa (Arjantin'de 25 kg, Brezilya'da 15 kg, Meksika'da 30 kg) veya Mercado Envios adres için hata ya da hiç seçenek döndürmezse kullanılır. Ülkenin satırı (veya * satırı) kullanılır, aksi halde yedek ücret. Hiç fiyat yoksa yöntem gizlenir. Müşteri asla bir API hatası görmez.

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

Uzantı yalnızca tarifeleri hesaplar. Gönderi oluşturmaz, etiket basmaz ve paketleri takip etmez. Gönderiyi Mercado Libre veya Mercado Pago hesabınızda oluşturun. Tüm seçenekler arasında seçim değil, tek bir fiyat gösterir: en ucuz Mercado Envios seçeneği. Teslim alma noktası (acente) seçici içermez.

Siparişler

Bir sipariş anlık Mercado Envios tarifesiyle verildiğinde uzantı, hizmet adını, gün cinsinden tahmini teslimat süresini ve anlık tarifeyi saklar. Sales > Orders bölümünde sipariş sayfası, Mercado Envios service, Estimated delivery ve Live rate (excl. tax) içeren bir Mercado Envios bloğu gösterir. Blok, yöntem sonradan kapatılsa bile gösterilir. Kayıtlı bir müşteri, hesabındaki sipariş sayfasında kargo yönteminin altında Mercado Envios service ve Estimated delivery satırlarını görür; aynı satırlar yeni sipariş e-postasına da eklenir. Tablo fiyatıyla veya yedek ücretle verilen siparişlerin bir hizmeti yoktur. Mevcut siparişler, sonraki tarife değişikliklerinden etkilenmez.

OpenCart 4'te Mercado Envios bloğu History bölümünün üzerinde gösterilir. OpenCart 4 ödeme için tek bir sipariş tutar ve müşteri her onaylamada onu günceller: kaydedilen hizmet onunla birlikte güncellenir, müşteri başka bir kargo yöntemine geçtiğinde ya da sipariş tablo fiyatı veya yedek ücret aldığında ise kaldırılır.

Lisans anahtarı

Uzantı, vibefox.net'ten alınan bir VibeFox lisans anahtarıyla çalışır. Lisans bloğu License — VibeFox Mercado Envios, Extensions > Extensions > Shipping > VibeFox Mercado Envios > 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 hangi tarihe kadar geçerli olduğu ve alan adınız) gösterir; ayrıca durumu yeniden denetlemek için Check now, başka bir anahtar girmek için Change key ve anahtarı bu mağazadan kaldırmak için Remove key düğmeleri bulunur. Bunların altında Product: opencart-shipping-mercado-envios satırı ve Manage licenses and domains in your account bağlantısı vardır; bağlantı vibefox.net hesabınızı açar. Anahtarı yalnızca uzantı için değiştirme yetkisine sahip yönetici kullanıcılar değiştirebilir. Bloğun metinleri yönetici 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ı boşalttıktan sonra Check now düğmesine tıklayın. Lisans sunucusuna ulaşılamazsa eklenti son bilinen durumla çalışmaya devam eder.

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

Etkin bir anahtar olmadan Mercado Envios ödeme sayfası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 görür; yöntem (unlicensed — visible to admins only) ile işaretlenir. Böylece anahtarı satın almadan önce eklentiyi kurup test edebilirsiniz. OpenCart 4'te bu önizleme yoktur: mağaza yönetici girişini görmez, bu nedenle etkin bir anahtar yoksa yöntem 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 gizlenir. Mevcut siparişler etkilenmez.

Bir lisansın süresi dolduğunda eklenti çalışmaya devam eder, ancak güncellemeler ve destek için yenileme gerekir. Durum, yönetici Dashboard ekranını veya Edit sayfasını açtığınızda otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün her gün, sonrasında haftada bir. Cron işi gerekmez. Eklentiyi kaldırmak lisans anahtarını ve lisans durumunu her zaman siler.

Sorun giderme

Mercado Envios ödeme sayfasında görünmüyor: lisansın etkin olduğunu ve Enable Mercado Envios shipping seçeneğinin açık olduğunu kontrol edin. Geo zone ayarını kontrol edin veya Ignore shipping zones seçeneğini açıp Countries ayarını kontrol edin. Uzantı sayfasındaki uyarıları, ağırlık sınırlarını ve Minimum subtotal değerini kontrol edin. Yöntemin bir fiyata ihtiyacı var: Mercado Envios ülkesindeki adresler için çalışan bir erişim jetonu ya da Country prices veya Fallback cost. Ürünlerin Requires Shipping değerinin Yes olduğunu kontrol edin.

Anlık tarifeler görünmüyor: Debug log seçeneğini açın, ödeme sayfasını yenileyin ve uzantı sayfasındaki Log alanına bakın. Yaygın nedenler: jeton yok, Mercado Envios ülkesinin dışında bir hedef, eksik veya geçersiz posta kodu, eksik Exchange rate, ağırlık sınırını aşan bir paket veya adres için Mercado Envios seçeneği olmaması.

Uyarılarda HTTP 401 veya 403: erişim jetonu geçersiz veya süresi dolmuş. Mercado Pago Developers'tan üretim Access Token'ını yeniden kopyalayın.

Mercado Envios başka bir para biriminde yanıt verdi: hesabın ülkesi Mercado Envios country ile eşleşmiyor. Mercado Pago hesabınızın ülkesini seçin.

Fiyatlar hangi para biriminde: Country prices, Fallback cost ve eşikler mağazanızın varsayılan para birimindedir. Anlık tarifeler Mercado Pago hesabınızın para biriminde gelir ve mağaza başka bir varsayılan para birimi kullanıyorsa Exchange rate ile çevrilir.

Bir değişiklikten sonra tarifeler güncel görünmüyor: uzantı sayfasında Save düğmesine tıklayın. Bu, önbellekteki tarifeleri temizler.

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

Geliştiriciler için: Mercado Envios API adresi vfd_mrcv_api_url ayarıyla değiştirilebilir (testler için); ayarlar sayfasında bunun bir alanı yoktur.

Kaldırma

Extensions > Extensions sayfasına gidin, Shipping türünü seçin ve VibeFox Mercado Envios 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 Mercado Envios shipping, Sort order, Tax class ve Geo zone ayarlarını sıfırlar. Önbellekteki tarifeler ve son API hatası her zaman silinir. Remove data on uninstall açıksa diğer ayarlar ve hata ayıklama günlüğü de silinir. Kapalıysa, korunur ve uzantıyı yeniden kurduğunuzda tekrar kullanılır. Verilen siparişlerin Mercado Envios verileri her zaman korunur; mevcut siparişler kargo yöntemlerini ve maliyetlerini korur.

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

Mercado Envios ve Mercado Pago, ilgili sahiplerinin ticari markalarıdır. Bu uzantı Mercado Envios veya Mercado Pago ile bağlantılı değildir ve onlar tarafından onaylanmamıştır.