VibeFox Correios for OpenCart — Yardım

Gereksinimler

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

PHP: 8.0 veya üzeri.

Correios sözleşmesi (yalnızca canlı fiyatlar için): canlı fiyatlar Correios Web Services (CWS) fiyat API'sini kullanır ve posta kartı olan bir Correios sözleşmesinin kimlik bilgilerini gerektirir. Üç değere ihtiyacınız vardır: Meu Correios kullanıcınız (genellikle sözleşmenin CNPJ veya CPF numarası), API erişim kodu ve posta kartı numarası. Erişim kodunu Correios Web Services portalında oluşturun (cws.correios.com.br; test ortamı için cwshom.correios.com.br). Ayrıca gönderim yaptığınız CEP kodunu da bilmeniz gerekir. Kimlik bilgileri olmadan eklenti yalnızca sabit fiyatlarla çalışır.

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

Kurulum

İndirme, OpenCart'ın iki 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_correios-oc3-(version).ocmod.zip ve OpenCart 4 paketi vfd_correios.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_correios-oc3-(version).ocmod.zip dosyasını seçin. Eklenti OCMOD değişikliği eklemez, bu nedenle Extensions > Modifications sayfası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 sayfasına gidin, eklenti türü olarak Shipping seçin. VibeFox Correios eklentisini bulun ve Install düğmesine (yeşil + düğmesi) tıklayın.

3. Ayar 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ğunda License key alanına girin ve Activate düğmesine tıklayın (bkz. Lisans anahtarı).

5. Correios API kullanıcısını, erişim kodunu, posta kartı numarasını, gönderici CEP kodunu ve hizmeti girin. Mağazanızın varsayılan para birimi BRL değilse BRL kurunu girin. Diğer ülkeler ve yedek seçenek için sabit fiyatları doldurun (bkz. Configuration), Enable Correios 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_correios.ocmod.zip dosyasını seçin. Dosyanın adını değiştirmeyin: OpenCart 4 eklenti kodunu dosya adından alır ve yeniden adlandırılmış bir paket çalışmaz.

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

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

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

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

Configuration

Tüm ayarlar eklenti sayfasındadır: Extensions > Extensions > Shipping > VibeFox Correios > Edit. Bölümler solda listelenir. Sayfanın altındaki tek bir Save düğmesi tüm sayfayı yeniden yüklemeden kaydeder. Her kayıt, önbelleğe alınmış Correios fiyatlarını ve API jetonlarını da temizler. Sayılar nokta veya virgülle yazılabilir. Yalnızca bu eklenti için değiştirme izni olan yönetici kullanıcılar ayarları kaydedebilir.

Canlı fiyatlar veya yöntem çalışamadığında sayfa uyarılar gösterir: üç kimlik bilgisinin yalnızca bir kısmı doldurulmuşsa, gönderici CEP kodu eksikse, başka para birimi kullanan bir mağaza için BRL kuru eksikse ya da ne kimlik bilgileri ne de sabit fiyatlar varsa. Her uyarı, bu sırada sabit fiyatların kullanılıp kullanılmadığını veya yöntemin gizlenip gizlenmediğini belirtir. Mağazada kg birimli bir ağırlık sınıfı ya da cm birimli bir uzunluk sınıfı yoksa da uyarı görünür; bu durumda ürün birimleri sınıflarının birim adına göre dönüştürülür (bilinmeyen birimler kg veya cm olarak okunur). System > Localisation > Weight Classes ve Length Classes sayfalarını kontrol edin.

Yöntem başlığı boşsa veya geçersizse (en fazla 64 karakter, < > ; = # { } karakterleri olmadan), Country prices içindeki bir sayısal alan veya fiyat 0 veya daha büyük bir sayı değilse, BRL kuru 0 ise, Min cart weight değeri Max cart weight değerinden büyükse, gönderici CEP kodu 8 haneli değilse, diğer hizmet kodu 5 haneden fazlaysa ya da Sort order tam sayı değilse kaydetme bir mesajla reddedilir. Değeri düzeltene kadar hiçbir şey kaydedilmez.

Genel

Ayarlar tüm coğrafi bölgeler için geçerlidir. Yöntemi Conditions içinde bir coğrafi bölgeyle veya Ignore shipping zones ile bir ülke listesiyle sınırlayabilirsiniz.

Enable Correios: Correios seçeneğini ödeme sayfasında gösterir veya gizler. Varsayılan: kapalı.

Method title: sepette ve ödeme sayfasında müşteriye gösterilen kargo yöntemi adı. Varsayılan: Correios. Zorunlu.

Sort order: Correios'un ödeme sayfasındaki kargo yöntemleri arasındaki konumu. Tam sayı.

Correios API (Brezilya'da canlı fiyatlar)

Brezilya'daki adresler için fiyat Correios fiyat API'sinden gelir. API fiyat vermezse (API kullanılamıyor, CEP hizmet kapsamında değil, paket çok büyük), Country prices içindeki sabit fiyat kullanılır; sabit fiyat yoksa yöntem gizlenir. Hata ayrıntıları günlüğe yazılır, müşteriye asla gösterilmez.

API user: Meu Correios portalındaki giriş bilginiz, genellikle sözleşmenin CNPJ veya CPF numarası. Bunu temizlemek kayıtlı erişim kodunu da temizler.

Access code: Correios Web Services portalında oluşturulan API erişim kodu (código de acesso). Portal şifresi değildir. Kaydettikten sonra alan boş kalır ve Saved — leave empty to keep it (empty the API user as well to remove it). ifadesini gösterir. Yalnızca değiştirmek istediğinizde yeni bir değer girin. Kayıtlı kodu kaldırmak için API user alanını boşaltın ve kaydedin.

Posting card: sözleşmenizin posta kartı (cartão de postagem) numarası: 10 haneli, genellikle iki sıfırla başlar, örneğin 0012345678. Daha kısa numaralar başına sıfır eklenerek tamamlanır. Numarayı Correios web sitesindeki Correios Fácil sayfasından kontrol edebilirsiniz.

Homologation: Correios test (homologation) ortamını kullanır: istekler bir test erişim kodu ile apihom.correios.com.br adresine gönderilir. Canlı bir mağazada kapatın.

Origin CEP: paketlerin gönderildiği CEP kodu (8 haneli), örneğin 01001-000.

Service: ödeme sayfasında fiyatlandırılan Correios hizmeti. Perakende kodları: PAC (04510, varsayılan), SEDEX (04014), SEDEX 12 (04782), SEDEX 10 (04790), SEDEX Hoje (04804). Sözleşme kodları: PAC (03298), SEDEX (03220), SEDEX 12 (03140), SEDEX 10 (03158), SEDEX Hoje (03204), Correios Mini Envios (04227). Sözleşme kodları, hizmeti içeren bir sözleşmenin posta kartını gerektirir.

Other service code: isteğe bağlı, listede bulunmayan, sözleşmenizdeki 5 haneli bir hizmet kodu, örneğin 03085. Daha kısa kodlar başına sıfır eklenerek tamamlanır. Doldurulduğunda Service yerine bu kod kullanılır.

Package format: Correios'a gönderilen nesne türü.

Default product weight (kg): ağırlığı olmayan her ürün için Correios'a gönderilir. Varsayılan: 0.3. Ürün ağırlıkları ve boyutları ağırlık ve uzunluk sınıflarından dönüştürülür ve sepet tek bir paket olarak fiyatlandırılır.

BRL → store currency rate: alan adı mağazanızın varsayılan para birimini gösterir, örneğin BRL → EUR rate. Correios fiyatları BRL cinsindendir. Varsayılan para biriminiz BRL değilse, bir BRL'nin kaç birim para biriminize denk geldiğini girin, örneğin 0.17. Bu değer girilmezse canlı fiyatlar kullanılmaz. Kur 0'dan büyük olmalıdır. Varsayılan para biriminiz BRL ise alanı boş bırakın.

Sabit fiyatlar (Brezilya dışındaki ülkeler için, API kimlik bilgileri olmadan ve API fiyat vermediğinde yedek olarak kullanılır)

Country prices: mağazanızın varsayılan para biriminde, vergi hariç, sepet ağırlığına göre fiyatlar ve bir Base fiyatı içeren ülke tablosu: XS 1 kg'a kadar, S 1–2 kg, M 2–3 kg, L 3–5 kg, XL 5 kg üzeri. Boş veya sıfır bir boyut fiyatı Base fiyatını kullanır. Satır eklemek için Add country düğmesine, satır silmek için × düğmesine tıklayın. * All other countries satırı, kendi satırı olmayan tüm ülkeler için fiyatları belirler. Satırı olmayan (ve * kapsamında olmayan) bir ülke sabit fiyat almaz. Bir satırda en az bir fiyat olmalıdır. 0 olan bir temel fiyat, o ülke için ücretsiz kargo anlamına gelir.

Fixed price per: Order (varsayılan) fiyatı bir kez alır. Item (price × quantity) ise fiyatı sepetteki ürün adedine göre çarpar. Bu yalnızca sabit fiyatlar için geçerlidir. Canlı fiyatlar her zaman tüm paket için hesaplanır.

Conditions

Min cart weight (kg): sepet bu ağırlığın altındaysa yöntemi gizler. 0 sınır olmadığı anlamına gelir. Max cart weight değerinden büyük olamaz.

Max cart weight (kg): sepet bu ağırlığın üstündeyse yöntemi gizler. Varsayılan: 30. 0 sınır olmadığı anlamına gelir, boş alan 30 kg anlamına gelir. Correios PAC ve SEDEX paketleri 30 kg'a kadar olabilir.

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

Free shipping: aşağıdaki tutardan itibaren ücretsiz teslimatı açar.

Free shipping from: kargo gerektiren ürünlerin ara toplamı (kupon sonrası, vergi öncesi); bu tutardan itibaren teslimat ücretsizdir. Bu durumda API'ye istek gönderilmez.

Tax class: kargo ücretine eklenen vergi sınıfı veya No tax (varsayılan).

Geo zone: Correios'u yalnızca bu coğrafi bölgedeki adreslere sunar. All zones (varsayılan) sınır olmadığı anlamına gelir. Coğrafi bölgeler System > Localisation > Geo Zones bölümünden yönetilir. Ignore shipping zones ile birlikte kullanılmaz.

Kargo bölgeleri olmadan kullanılabilirlik

Normalde yöntem, Conditions içinde seçilen coğrafi bölgede sunulur (hiçbiri seçilmediyse tüm bölgelerde).

Ignore shipping zones: yöntemi, eşleşen coğrafi bölge ne olursa olsun, aşağıdaki ülkeler için sunar. Bu durumda Conditions içindeki Geo zone kontrol edilmez.

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

Gelişmiş

Debug log: fiyat hesaplamalarını storage/logs/vfd_crr_debug.log.php dosyasına yazar (OpenCart 4'te system/storage/logs/vfd_crr_debug.log.php). Dosya web üzerinden okunamaz. API hataları bu seçenek kapalı olsa bile her zaman kaydedilir. API kullanıcısı, erişim kodu, posta kartı, jeton ve müşteri CEP kodları kaydedilmez. Dosya 5 MB'a ulaştığında vfd_crr_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 kayıtlarını gösterir. Temizlemek için Clear log düğmesine tıklayın.

Remove data on uninstall: açıkken eklentiyi kaldırmak Correios ayarlarını ve günlüğü siler. Kapalıyken (varsayılan) yeniden kurulum için saklanırlar. Siparişlerle kaydedilen Correios hizmetleri her zaman korunur.

İçe / dışa aktarma

Export: ayarları JSON dosyası olarak kaydetmek için Download JSON düğmesine tıklayın. Erişim kodu 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 kodu korunur.

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

OpenCart kargo yöntemlerini gösterirken eklentiden Correios fiyatını ister. Bir Geo zone ayarlıysa (ve Ignore shipping zones kapalıysa) ve adres bu bölgenin dışındaysa Correios sunulmaz. Yalnızca Requires Shipping değeri Yes olan ürünler dikkate alınır: diğer ürünler ağırlığa eklenmez ve sipariş tutarına dahil edilmez. Ardından eklenti koşulları kontrol eder: izin verilen ülkeler (Ignore shipping zones ile), sepet ağırlığı ve minimum sipariş tutarı. Sipariş tutarı, kargo gerektiren ürünlerin kupon indirimi sonrası ve vergi öncesi fiyatıdır. Ücretsiz kargo uygulanırsa fiyat 0 olur ve Correios'a istek gönderilmez.

Kimlik bilgileri ayarlanmış bir Brezilya adresi için eklenti önce posta kartınız için bir API jetonu alır. Jeton ayrıca sözleşme ve bölge ofisi numaralarını da verir, bu nedenle fiyat sözleşmenizin fiyatıdır. Ardından seçilen hizmetin fiyatını gönderici ve alıcı CEP kodlarına, paket ağırlığına (gram cinsinden) ve paket boyutuna (cm cinsinden) göre ister. Fiyat yalnızca alıcı CEP kodu 8 haneliyse istenir. Tüm ürünlerin boyutları varsa paket boyutu bunlardan tahmin edilir; aksi halde Correios minimum boyutu gönderilir. 30 kg'ı aşan paketler API'ye gönderilmez. BRL fiyatı kurunuzla dönüştürülür. Fiyat, mağazanızın varsayılan para biriminde hesaplanır, o para biriminin ondalık basamaklarına yuvarlanır ve seçilen Tax class vergisiyle birlikte müşteriye kendi para biriminde gösterilir.

Her fiyat 1 saat önbelleğe alınır. Başarısız bir istek 10 dakika önbelleğe alınır; böylece bir API kesintisi her ödeme sayfası güncellemesini yavaşlatmaz. Jeton, sona ermesine kısa bir süre kalana kadar önbelleğe alınır (en fazla OpenCart önbellek süresi kadar, varsayılan olarak 1 saat) ve otomatik olarak yenilenir; Correios reddederse yeni bir jeton istenir ve fiyat isteği bir kez yinelenir. API zaman aşımı 12 saniyedir.

API fiyat vermezse sabit fiyat kullanılır; sabit fiyat yoksa yöntem gizlenir. Müşteri API hata ayrıntılarını asla görmez; bunlar hata ayıklama günlüğüne gider.

Eklenti yalnızca tarifeleri hesaplar. Uluslararası Correios fiyatlarını (Exporta Fácil, Packet), teslimat süresi tahminlerini, etiketleri, ön kayıtları, beyanları veya takibi almaz. Müşteriler bir Correios şubesi veya dolabı seçemez. Ek hizmetler (beyan edilen değer, eline teslim, teslim alındı bildirimi) eklenmez. Mağaza başına tek bir Correios hizmeti gösterir ve para birimi kurları otomatik olarak güncellenmez.

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

Siparişler

Correios ile bir sipariş verildiğinde eklenti, kargo fiyatının nasıl hesaplandığını kaydeder. Sales > Orders altındaki sipariş sayfası, Correios service (örneğin PAC — contract (03298)) ve Price alanlarıyla birlikte bir Correios bloğu gösterir: Live price (Correios API), Fixed price veya Free shipping. Blok yalnızca yönetici panelinde gösterilir, müşteri e-postalarında gösterilmez ve eklenti kapalı olsa bile görünür kalır.

OpenCart 4'te ödeme sayfası bir siparişi tutar ve müşteri yeniden onayladığında onu günceller. Siparişin Correios verileri onunla birlikte güncellenir; müşteri başka bir kargo yöntemine geçerse, Correios bloğu o sipariş için artık gösterilmez.

Lisans anahtarı

Eklenti, vibefox.net üzerinden alınan bir VibeFox lisans anahtarıyla çalışır. License — VibeFox Correios lisans bloğu, Extensions > Extensions > Shipping > VibeFox Correios > Edit sayfasında ayarların üstündeki ilk bloktur. Anahtarı License key alanına yapıştırın ve Activate düğmesine tıklayın. Bundan sonra blok, anahtarı maskelenmiş olarak, durumu (örneğin lisansın geçerli olduğu tarihi ve alan adınızı) ve Check now (durumu yeniden kontrol etmek için), Change key (başka bir anahtar girmek için) ve Remove key (anahtarı bu mağazadan kaldırmak için) düğmelerini gösterir. Bunların altında Product: opencart-shipping-correios 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 eklenti için Modify izni olan 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 veya hesabınızda bir alan adı yuvasını serbest bıraktı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: 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 Correios müşterilere ödeme sayfasında gösterilmez ve hiçbir fiyat hesaplanmaz. Yönetici paneline aynı tarayıcıda giriş yapmış bir yönetici kullanıcı, yöntemi mağazada hâlâ (unlicensed — visible to admins only) işaretiyle görür; 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, dolayısıyla etkin bir anahtar olmadan yöntem herkes için gizlidir. Edit sayfasını bir kez açtıktan sonra yönetici Dashboard sayfasında bir hatırlatma belirir. 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 yenileme gerektirir. Durum, yönetici Dashboard sayfasını veya Edit sayfasını açtığınızda otomatik olarak yeniden kontrol edilir: anahtar girildikten sonraki ilk 14 gün boyunca günde bir kez, sonrasında haftada bir kez. Cron işi gerekmez. Eklentiyi kaldırmak her zaman lisans anahtarını ve lisans durumunu siler.

Sorun giderme

Correios ödeme sayfasında görünmüyor: lisansın etkin olduğunu ve Enable Correios seçeneğinin açık olduğunu kontrol edin. Geo zone ayarını kontrol edin (veya Ignore shipping zones ve Countries), ağırlık sınırlarını ve Minimum order amount değerini kontrol edin. Canlı fiyat yoksa ülke veya * için bir sabit fiyat bulunmalıdır. Ürünlerin Requires Shipping değerinin Yes olduğunu kontrol edin.

Yöntem Correios fiyatı yerine sabit fiyat gösteriyor: eklenti sayfasındaki Log alanına bakın. Correios hataları orada kaydedilir: yanlış erişim kodu, sözleşmenizde olmayan hizmet, hizmet kapsamında olmayan CEP, 30 kg'ı aşan paket veya boyut sınırlarını aşan paket. Ayrıca gönderici CEP kodunun ayarlı olduğunu, müşterinin CEP kodunun 8 haneli olduğunu ve varsayılan para birimi BRL değilse BRL kurunu kontrol edin. Her hesaplamayı görmek için Debug log seçeneğini açın.

Jeton isteği başarısız oluyor: API kullanıcısını, erişim kodunu, posta kartını ve ortamı kontrol edin. Test erişim kodu yalnızca Homologation açıkken, canlı kod ise yalnızca kapalıyken çalışır.

Bir değişiklikten sonra fiyatlar eski görünüyor: eklenti sayfasında Save düğmesine tıklayın. Bu, önbelleğe alınmış fiyatları ve API jetonunu temizler.

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

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

Kaldırma

Extensions > Extensions sayfasına gidin, Shipping türünü seçin ve VibeFox Correios yanındaki Uninstall düğmesine (kırmızı − düğmesi) tıklayın. Bu eklentinin lisans anahtarı ve lisans durumu her zaman silinir. OpenCart her zaman Enable Correios, Sort order, Tax class ve Geo zone ayarlarını sıfırlar. Önbelleğe alınmış fiyatlar ve jetonlar her zaman silinir. Remove data on uninstall açıksa Correios ayarları ve hata ayıklama günlüğü de silinir. Kapalıysa diğer ayarlar korunur ve eklentiyi yeniden kurduğunuzda tekrar kullanılır. Siparişlerle kaydedilen Correios hizmetleri her zaman korunur ve mevcut siparişler kargo yöntemini ve maliyetini korur.

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

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