Geliştiriciler İçin

4 makaleler Fatih ÇELEBİ

Tarafından Fatih ÇELEBİ, Fikret ÇİN, and Fuat POYRAZ

4 makaleler Fatih ÇELEBİ

Tarafından Fatih ÇELEBİ, Fikret ÇİN, and Fuat POYRAZ

Geliştiriciler için geliştirme notları

Oluşturulan Barkodların 3. Parti Yazılımlar ile Paylaşılması (WooCommerce)

Üçüncü parti servislerin barkod verilerine erişebilmesini sağlamak amacıyla sistemimize yeni bir hook eklenmiştir. do_action( $this->prefix . '_shippment_status_update_' . $shipment_data['status'], $shipment_data, $order ); Bu hook, gönderi (shipment) durumu güncellendiğinde çalışır ve güncellenen gönderi verilerini ($shipment_data) ve ilgili sipariş nesnesini ($order) üçüncü parti entegrasyonlara aktarır. Kullanım Örneği Örneğin, bir barkod oluşturduğunuzda ve bu barkodu siparişe belirli bir veri formatında kaydetmek istediğinizde, aşağıdaki gibi bir işlem gerçekleştirebilirsiniz: add_action('gcargo_shippment_status_update_non_processed', function($shipment_data, $order) { add_post_meta($order->get_id(), 'gl_shipment_package_barcodes', $shipment_data['barcode']); }, 10, 2); Bu örnekte: - gcargo_shippment_status_update_non_processed hook’una abone olunmaktadır. - Gönderi verisinden ($shipment_data['barcode']) barkod alınmakta ve siparişe ($order) 'gl_shipment_package_barcodes' alanı olarak kaydedilmektedir. Faydaları - Üçüncü parti servisler kolayca barkod verisine erişebilir. - Barkod bilgisi, siparişle ilişkilendirilerek süreçler daha verimli yönetilebilir. - Esnek yapı sayesinde farklı gönderi durumlarına özel işlemler yapılabilir. Bizim Hesap için Barkod Paylaşımı BİZİM Hesap gibi 3. parti yazılımlar, oluşturulan barkodlara gl_shipment_package_barcodes alanı üzerinden erişebilir. Gönderi durumu güncellendiğinde çalışan do_action hook’u sayesinde bu barkod bilgisi siparişe kaydedilir. add_action('gcargo_shippment_status_update_non_processed', function($shipment_data, $order) { add_post_meta($order->get_id(), 'gl_shipment_package_barcodes', $shipment_data['barcode']); add_post_meta($order->get_id(), 'gl_tracking_link', $shipment_data['tracking_link']); add_post_meta($order->get_id(), 'gl_tracking_number', $shipment_data['tracking_number']); }, 10, 2); Bu sayede BİZİM Hesap, siparişten gl_shipment_package_barcodes alanını okuyarak barkoda erişebilir.

WordPress Eklentisi Kanca (Hook) Listesi

Otomatik Gönderi Mekanizmasını Özelleştirme Kargo Entegratör modülünün otomatik gönderi oluşturma davranışını aşağıdaki filtreler yardımıyla projenize özel hale getirebilirsiniz. 1. Otomatik Gönderi Tetikleyici Durumları Genişletme Varsayılan olarak modül belirli sipariş durumlarında (örneğin: processing) tetiklenir. Eğer özel bir sipariş durumu (Custom Order Status) kullanıyorsanız veya "Beklemede" (on-hold) olan siparişlerin de otomatik kargoya iletilmesini istiyorsanız bu filtreyi kullanabilirsiniz. add_filter('gcargo_auto_shipment_statuses', function($statuses) { $statuses[] = array( 'text' => 'Beklemede', 'value' => 'on-hold', ); return $statuses; }); 2. Otomatik Gönderi Zaman aşımı (Timeout) Listesini Genişletme Sipariş durumu değiştikten ne kadar süre sonra Kargo Entegratör API'sine veri gönderileceğini seçtiğiniz listeyi bu filtre ile özelleştirebilirsiniz. Bu, özellikle sipariş üzerinde son kontrolleri yapmak için zaman kazanmak isteyen mağazalar için idealdir. add_filter('gcargo_auto_shipment_timeouts', function($timeouts) { $timeouts[] = array( 'text' => '1 Saat', 'value' => 3600, ); return $timeouts; }); Kargo Entegratör Verilerini Manipüle Etme gcargo_shipment_map_wc_order_request ve gcargo_returned_map_wc_order_request filtreleri, sipariş verilerini Woo'dan alıp Kargo Entegratör API'sine iletilmeden hemen önce tetiklenir. Bu filtreler sayesinde, gönderi etiketi oluşturulmadan önce ürün adlarını, desi bilgilerini veya alıcı detaylarını programatik olarak değiştirebilirsiniz. Aşağıdaki kod bloğu; ürün adını düzenleme, özel desi hesaplama ve kargo verisine müdahale etme gibi senaryoları kapsar: add_filter('gcargo_shipment_map_wc_order_request', function($gcargo_request, $order) { // Ürün satırlarını döngüye alarak başlıkları güncelle $gcargo_request['lines'] = array_map(function($line) { // Sipariş öğesi meta verisini al $sample_meta_value = wc_get_order_item_meta($line['platform_id'], '_my_sample_meta_key', true); // Ürün adına meta değerini ekle if (!empty($sample_meta_value)) { $line['title'] = $line['title'] . ' - ' . $sample_meta_value; } return $line; }, $gcargo_request['lines']); // Kapıda ödeme (COD) ise tahsil edilecek tutara 100 TL ekle if ($order->get_payment_method() === 'cod') { $gcargo_request['total'] = $order->get_total() + 100; } return $gcargo_request; }, 10, 2);

Ek Eklenti ve Ürün Seçeneklerini Barkod Çıktısına Yansıtma (WooCommerce)

Ek Eklenti ve Ürün Seçeneklerini Barkod Çıktısına Yansıtma Mağazanızda ürün ek seçenekleri (Product Add-Ons, Extra Product Options), kişiselleştirme, hediye paketi, işleme/gravür gibi alanlar sunan bir eklenti kullanıyorsanız; müşterinin seçtiği bu değerler WooCommerce tarafında sipariş satırı meta verisinde saklanır ve varsayılan olarak Kargo Entegratör'e iletilmez. Bu değerleri paketleme sırasında görebilmek için, ürün satırındaki custom_attributes alanına aktarabilirsiniz. Bu alana eklediğiniz anahtar / değer çiftleri, gönderiye ait barkod ve fiş PDF çıktılarında ilgili ürün satırının altında listelenir. Barkod Çıktısına İletilen Veri Yapısı Her ürün satırı (lines) aşağıdaki gibi serbest bir custom_attributes nesnesi kabul eder: "lines": [ { "title": "Deri Çanta", "quantity": 3, "platform_id": 1235, "img": "https://dericanta.com/assets/ornek.png", "sku": "DRCNT123", "custom_attributes": { "Renk": "Kırmızı", "Boyut": "160 cm" } } ] Anahtar isimleri sabit değildir; çıktıda görünmesini istediğiniz etiketi doğrudan siz belirlersiniz. Değerlerin kısa metinler olmasına dikkat edin, uzun metinler barkod çıktısında kırpılabilir. Ek Seçenek Eklentilerinin Verisini Toplu Aktarma Ek seçenek eklentilerinin büyük bölümü, müşterinin seçimlerini sipariş satırı meta verisi olarak kaydeder ve bu veriler sipariş detay ekranında ürün adının altında görüntülenir. Aşağıdaki örnek, sipariş ekranında görünen tüm bu satırları olduğu gibi barkod çıktısına taşır: add_filter('gcargo_shipment_map_wc_order_request', function ($gcargo_request, $order) { $gcargo_request['lines'] = array_map(function ($line) use ($order) { // platform_id -> WooCommerce sipariş satırı (order item) ID'si $item = $order->get_item($line['platform_id']); if (!$item) { return $line; } // Sipariş ekranında görünen tüm seçenek satırları (varyasyon + ek seçenekler) foreach ($item->get_formatted_meta_data('_') as $meta) { $baslik = wp_strip_all_tags($meta->display_key); $deger = wp_strip_all_tags($meta->display_value); if (!empty($baslik) && !empty($deger)) { $line['custom_attributes'][$baslik] = $deger; } } return $line; }, $gcargo_request['lines']); return $gcargo_request; }, 10, 2); Notlar - Yalnızca belirli bir alanı aktarmak isterseniz, meta anahtarını wc_get_order_item_meta($line['platform_id'], '_meta_anahtari', true) ile doğrudan okuyup custom_attributes içine ekleyebilirsiniz. - İade gönderilerinde aynı yapıyı gcargo_returned_map_wc_order_request filtresi ile kullanabilirsiniz. - custom_attributes zorunlu bir alan değildir; gönderilmediğinde barkod çıktısında ek satır oluşmaz.

Bilgilendirme Mesaj Metinlerini Koşullu Biçilendirme Nasıl Yapılır?

Kargo Entegratör, gönderileriniz için alıcılarınıza otomatik SMS ve e-posta bildirimleri gönderebilir. Bildirim şablonlarınızı panelinizde Ayarlar → Bilgilendirme Ayarları bölümünden düzenleyebilirsiniz. Bu ekranda SMS Şablonları ve Email Şablonları sekmeleri altında, her gönderi durumu için (Gönderime Hazır, Yola Çıktı, Taşıma Sürecinde vb.) ayrı bir mesaj metni tanımlanır ve bildirimler yalnızca ilgili şablon açık olduğunda gönderilir. Bazı durumlarda tüm gönderilere aynı mesajı göndermek yeterli olmaz: örneğin kapıda ödemeli bir siparişte alıcıya ödeme tutarını hatırlatmak, normal siparişlerde ise standart bir mesaj göndermek istersiniz. Bu ihtiyaç için şablon metinlerinizde koşullu ifadeler kullanabilirsiniz; mesaj, gönderinin ödeme bilgisine göre otomatik olarak farklı biçimde oluşturulur. Koşul yazımı Koşullar {% if %} ... {% else %} ... {% endif %} biçiminde yazılır: {% if is_pay_at_door %}Kapıda ödemeli siparişiniz{% else %}Siparişiniz{% endif %} kargoya verildi. Kapıda ödemeli bir gönderide alıcıya "Kapıda ödemeli siparişiniz kargoya verildi.", diğer gönderilerde "Siparişiniz kargoya verildi." mesajı gönderilir. Tahsilat tipine göre ayrım yapıp tutarı da gösterebilirsiniz: {% if payment_type == 'cash_money' %}Teslimatta {{total}} {{currency}} nakit ödemeniz gerekmektedir.{% endif %} Koşullarda kullanılabilen değişkenler - is_pay_at_door — Gönderi kapıda ödemeli ise doğru (true) olur. - payment_type — Tahsilat tipi: 'cash_money' (Nakit) veya 'credit_card' (Kredi kartı). - payor_type — Kargo ücretini ödeyen: 'sender' (Gönderici) veya 'receiver' (Alıcı). Mesaja eklenebilen ödeme değişkenleri Bilgilendirme Ayarları'ndaki şablon düzenleme ekranında, "Kullanabileceğiniz Değişkenler" listesinden sürükle-bırak ile de ekleyebilirsiniz: - {{payment_type_text}} — Ödeme tipi (Nakit / Kredi kartı) - {{payor_type_text}} — Kargo ücretini ödeyen (Gönderici / Alıcı) - {{total}} — Tahsilat tutarı - {{currency}} — Para birimi Örnek şablonlar Kapıda ödeme bilgisiyle "Yola Çıktı" mesajı: Sayın {{full_name}}, {% if is_pay_at_door %}kapıda ödemeli siparişiniz ({{payment_type_text}}, {{total}} {{currency}}){% else %}siparişiniz{% endif %} {{cargo_company}} firmasına teslim edilmiştir. Takip: {{tracking_link}} Yalnızca nakit tahsilatlı gönderilere ek uyarı: {% if payment_type == 'cash_money' %}Lütfen teslimatta {{total}} {{currency}} tutarını nakit olarak hazır bulundurunuz.{% endif %} Bilinmesi gerekenler - Koşullu mesajların gönderilebilmesi için ilgili bildirimin Bilgilendirme Ayarları'ndan açık olması gerekir; bildirim kapalıysa mesaj gönderilmez. - Yalnızca {% if %}, {% elseif %}, {% else %} ve {% endif %} etiketleri desteklenir. - Kapıda ödemeli olmayan gönderilerde ödeme değişkenleri boş metin olarak gelir; koşul kullanmadan da şablona ekleyebilirsiniz. - Şablonunuzu kaydederken sistem otomatik olarak kontrol eder; yazım hatası varsa hata mesajı şablonun altında gösterilir ve düzeltmeden kayıt yapılmaz. - Koşullu mesajlar WhatsApp şablonlarında desteklenmez (WhatsApp şablonları Meta onayından geçtiği için sabit metinlidir).