WP Manifestindependent plugin directory
manifest / ecommerce / ptt-woo

PTT Kargo for WooCommerce

WooCommerce mağazanız ile PTT Kargo Web Servisleri arasında tam otomatik, çift yönlü ve kurumsal düzeyde entegrasyon sağlayan resmi standartlarda WordPress eklentisi.

by kaanrmk · github.com/kaanirmak/ptt-woo · website

★ 0stars
0forks

Install

No release zip yet. The repository archive installs, but the folder name will carry the branch suffix and updates will not flow:

wp plugin install https://github.com/kaanirmak/ptt-woo/archive/refs/heads/main.zip
Readme github.com/kaanirmak/ptt-woo ↗

PTT Kargo – WooCommerce Entegrasyonu

WooCommerce mağazanız ile PTT Kargo Web Servisleri arasında tam otomatik, çift yönlü ve kurumsal düzeyde entegrasyon sağlayan resmi standartlarda WordPress eklentisi.

Bu eklenti; siparişlerin PTT sistemine tek tıkla veya otomatik aktarılmasını (kabulEkle2), 13 haneli barkod üretilmesini, canlı kargo hareketlerinin (safahatlar) sorgulanmasını (GonderiTakipV2) ve kargo teslim edildiğinde sipariş durumunun otomatik güncellenmesini sağlar.

📋 İçindekiler

✨ Öne Çıkan Özellikler

  • 🚀 Otomatik & Manuel Kargo Kabulü: Sipariş durumu değiştiğinde (örn. "İşleniyor") otomatik veya sipariş detayından tek tıkla PTT'ye bildirim.
  • 🏷️ 13 Haneli Barkod & Check-Digit Doğrulama: 12 haneli barkod kökünden resmi PTT 1-3-1-3 Modulo 10 algoritmasıyla 13. kontrol hanesi (check-digit) otomatik hesaplanır.
  • 📦 Esnek Anlaşma Desteği:
    • Desi Bazlı: PTT'nin sisteme otomatik barkod ataması modu.
    • Sabit Barkod Havuzu: Firmanıza tahsis edilen barkod aralığını (örn: 280000000000 - 280000010000) sayarak tüketme ve kalan barkod uyarısı verme modu.
  • 🗺️ Akıllı İl / İlçe Eşleştirme (Fuzzy Match): WooCommerce müşteri adreslerini PTT il/ilçe kodlarıyla Türkçe karakter ve yazım toleranslı olarak otomatik eşleştirir.
  • 💰 Ek Hizmet Yönetimi (ekhizmet):
    • Kapıda Ödeme (OS): Kapıda nakit/kredi kartı siparişlerinde tahsilat tutarını PTT'ye otomatik iletme.
    • Değer Konulmuş / Sigortalı Gönderi (DK): Sipariş bedeline göre sigorta değeri tanımlama.
    • Alıcıdan Tahsil (UA): Kargo ücretini alıcının ödeyeceği senaryolar için ek hizmet desteği.
  • 🔄 Canlı Kargo Takibi & Safahat Akışı: PTT GonderiTakipV2 servisiyle kargonun kabul, transfer, dağıtım ve teslimat aşamalarını anlık gösterme.
  • ⏰ Otomatik Sipariş Durum Güncellemesi: WP-Cron ile periyodik kargo sorgulaması yapılır; kargo teslim edildiğinde WooCommerce siparişi otomatik "Tamamlandı" durumuna geçer.
  • 🖨️ Termal & Standart Etiket Çıktısı: 100x150 mm kargo termal etiketleri veya standart A4 formatında yazdırılabilir barkodlu teslimat formu.
  • 🛡️ Kurumsal Güvenlik & Şifreleme: Web servis şifreleri WordPress veritabanında AES-256-CBC algoritmasıyla şifrelenir; sistem loglarında hassas veriler otomatik maskelenir.
  • ⚡ WooCommerce HPOS Uyumlu: High-Performance Order Storage (Özel Sipariş Tabloları) mimarisiyle %100 uyumludur.
  • 🌐 Çift Yönlü SOAP / cURL Desteği: Sunucunuzda PHP SoapClient bulunmasa dahi Raw XML cURL motoruyla kesintisiz çalışır.

🔌 Entegre PTT Web Servisleri

Servis Adı WSDL Endpoint Kullanılan Metotlar / Amaç
PttVeriYukleme https://pttws.ptt.gov.tr/PttVeriYukleme/services/Sorgu?wsdl kabulEkle2 (Kargo kabulü), referansVeriSil / barkodVeriSil (Kayıt iptali)
GonderiTakipV2 https://pttws.ptt.gov.tr/GonderiTakipV2/services/Sorgu?wsdl gonderiSorgu2 (Barkod ile takip), gonderiSorgu_referansno, getDropPointInfo (Şube bilgisi)
PttBilgi https://pttws.ptt.gov.tr/PttBilgi/services/Sorgu?wsdl ilceSorgula (İl/ilçe veritabanı senkronizasyonu), ekHizmetSorgula

💻 Sistem Gereksinimleri

  • WordPress: 5.8 veya üzeri
  • WooCommerce: 5.0 veya üzeri (WooCommerce 9.x ve HPOS desteklenir)
  • PHP: 7.4, 8.0, 8.1, 8.2 veya 8.3
  • PHP Eklentileri: curl, openssl, simplexml, soap (isteğe bağlı, cURL fallback mevcuttur)

🚀 Kurulum Kılavuzu

1. Manuel Yükleme (ZIP veya FTP)

  1. Bu depoyu indirin veya ZIP formatında paketleyin.
  2. Klasör adının ptt-woo veya ptt-kargo-woocommerce olduğundan emin olun.
  3. Klasörü WordPress sitenizin /wp-content/plugins/ dizinine yükleyin.
  4. WordPress Yönetim Paneli > Eklentiler bölümünden PTT Kargo – WooCommerce Entegrasyonu eklentisini etkinleştirin.

2. Git ile Klonlama

cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/kaanirmak/ptt-woo.git

⚙️ Yapılandırma ve Ayarlar

Eklenti etkinleştirildikten sonra WooCommerce > Ayarlar > PTT Kargo sekmesine gidin.

┌─────────────────────────────────────────────────────────────┐
│ WooCommerce > Ayarlar > PTT Kargo                           │
├─────────────────────────────────────────────────────────────┤
│  [x] Entegrasyonu Etkinleştir                               │
│  Ortam: ( ) Canlı (Prod)   (o) Test Ortamı                  │
│                                                             │
│  Müşteri ID (musteriId): [ 904XXXXXX                      ] │
│  Kullanıcı Adı:          [ PttWs                          ] │
│  Şifre:                  [ ••••••••••••••                 ] │
│  [ Bağlantıyı Test Et ] -> "Bağlantı Başarılı (200 OK)"     │
│                                                             │
│  Anlaşma Tipi:           [ Sabit Barkod Havuzu Bazlı    v ] │
│  Başlangıç Barkodu:      [ 280000000000                   ] │
│  Bitiş Barkodu:          [ 280000010000                   ] │
│  Sonraki Barkod Sırası:  [ 280000000142                   ] │
│                                                             │
│  İl / İlçe Eşleştirme:   [ İl/İlçe Verilerini Senkronize Et]│
└─────────────────────────────────────────────────────────────┘

Temel Ayar Parametreleri:

  1. Çalışma Ortamı: Geliştirme/test aşamasında Test Ortamı, canlı siparişlerde Canlı (Prod) seçiniz.
  2. Kimlik Bilgileri: PTT Başmüdürlüğü veya kargo yetkiliniz tarafından size iletilen musteriId, kullanici ve sifre bilgilerini giriniz.
  3. Anlaşma Türü:
    • Desi Bazlı: PTT her sipariş için kendi barkodunu üretir.
    • Sabit Barkod Havuzu: Size tahsis edilen 12 haneli numara aralığını girin; eklenti check-digit hesaplayarak 13 haneli barkod oluşturur.
  4. Ek Hizmet Ayarları: Kapıda ödeme siparişlerinde OS ek hizmetini ve tutarını otomatik aktarabilirsiniz.
  5. Özel Depo / Gönderici Bilgileri: Farklı bir depo veya şube adresi üzerinden gönderim yapıyorsanız gönderici bilgilerini tanımlayabilirsiniz.

📖 Kullanım Senaryoları

1. Tekil Sipariş Kargo Kabulü

  • Sipariş Düzenleme ekranına girin.
  • Sağ taraftaki PTT Kargo İşlemleri meta kutusundan kargo desisini, ağırlığını ve ek hizmetleri kontrol edin.
  • "PTT'ye Gönder (Kargo Kabulü)" butonuna tıklayın.
  • PTT sistemi kargo kabulünü onaylar, 13 haneli barkod üretilir ve takip bağlantısı siparişe işlenir.
sequenceDiagram
    autonumber
    actor Admin as Mağaza Yöneticisi
    participant WC as WooCommerce (PTT Eklentisi)
    participant PTT as PTT Kargo Web Servisi (kabulEkle2)

    Admin->>WC: "PTT'ye Gönder" Butonuna Basar
    WC->>WC: 13 Haneli Barkod & Check-Digit Üretir
    WC->>PTT: SOAP / XML kabulEkle2 Payload İletilir
    PTT-->>WC: Başarılı Yanıt (SonucKodu: 1, Barkod_quid)
    WC->>WC: Sipariş Durumu & Meta Verileri Güncellenir
    WC-->>Admin: Barkod ve Takip Linki Gösterilir

2. Toplu Kargo İşlemleri

  • WooCommerce > Siparişler listesine gidin.
  • Göndermek istediğiniz siparişleri seçin.
  • Toplu İşlemler menüsünden "PTT Kargo'ya Gönder (Toplu Kabul)" seçeneğini seçip Uygula butonuna basın.
  • Sistem seçilen tüm siparişleri sırayla PTT sistemine aktarır ve sonuçları özet bildirim olarak sunar.

3. Termal ve A4 Barkod Etiketi Yazdırma

  • Kargo kabulü tamamlanan siparişin detay sayfasında veya sipariş listesindeki kargo sütununda "Barkod Etiketi Yazdır" butonuna tıklayın.
  • Açılan yazdırma penceresi standart termal kargo etiketleri (100x150 mm) ve A4 kargo teslimat formu ile uyumludur.

4. Kargo İptali ve Hatalı Kayıt Temizleme

  • Kargoya henüz fiziksel olarak teslim edilmemiş bir siparişin PTT kaydını iptal etmek için sipariş detayından "PTT Kargo Kaydını İptal Et / Sil" butonunu kullanın.
  • Eklenti PTT referansVeriSil veya barkodVeriSil metodunu çağırarak PTT tarafındaki bekleyen kaydı siler.

5. Canlı Kargo Takip ve WP-Cron

  • Eklenti arka planda (ptt_cron_tracking_sync) 2 saatte bir çalışarak kargodaki siparişlerin durumunu PTT GonderiTakipV2 üzerinden sorgular.
  • Tüm kargo safahatları (Kabul Edildi, Torbaya Eklendi, Dağıtıma Çıktı, Teslim Edildi) sipariş geçmişine kaydedilir.
  • Kargo teslim edildiğinde sipariş otomatik olarak "Tamamlandı" durumuna alınır.

6. Müşteri Arayüzü ve Takip Kısa Kodu

  • Hesabım > Siparişler: Müşteriler kendi hesap panellerinden siparişlerinin anlık PTT kargo durumunu ve safahat geçmişini görüntüleyebilir.
  • E-Posta Bildirimleri: Müşteriye giden "Siparişiniz Kargoya Verildi" e-postalarına takip numarası ve canlı PTT takip linki otomatik eklenir.
  • Kısa Kod (Shortcode): Sitenizin dilediğiniz sayfasına genel kargo takip formu ekleyebilirsiniz:
    [ptt_kargo_takip]

🏛️ Mimari ve Veritabanı Yapısı

ptt-woo/
├── assets/
│   ├── css/
│   │   ├── admin.css              # Yönetim paneli stilleri
│   │   └── frontend.css           # Müşteri paneli & safahat takip stilleri
│   ├── data/
│   │   └── turkey_cities_districts.json # İl / İlçe yerel veri tabanı
│   └── js/
│       └── admin.js               # AJAX bağlantı testi ve admin aksiyonları
├── Docs/                          # Resmi PTT WSDL, XML ve Teknik Dokümantasyon
├── includes/
│   ├── admin/                     # Yönetim paneli ayarları, sipariş meta kutuları
│   │   ├── class-ptt-admin-order.php
│   │   ├── class-ptt-admin-orders-list.php
│   │   └── class-ptt-admin-settings.php
│   ├── client/                    # Web Servis SOAP & cURL İstemcileri
│   │   ├── class-ptt-soap-client.php
│   │   ├── class-ptt-kabul-client.php
│   │   ├── class-ptt-takip-client.php
│   │   └── class-ptt-bilgi-client.php
│   ├── public/                    # Frontend müşteri alanı, e-postalar & shortcode
│   │   ├── class-ptt-frontend.php
│   │   └── class-ptt-emails.php
│   ├── services/                  # Çekirdek iş mantığı servisleri
│   │   ├── class-ptt-barcode-pool.php
│   │   ├── class-ptt-city-manager.php
│   │   ├── class-ptt-order-sync.php
│   │   └── class-ptt-tracking-cron.php
│   ├── class-ptt-activator.php    # DB tabloları & kurulum rutinleri
│   ├── class-ptt-deactivator.php  # Cron temizliği & devre dışı bırakma
│   ├── class-ptt-encryption.php   # AES-256 kimlik şifreleme
│   ├── class-ptt-helper.php       # Check digit, veri temizleme & formatlayıcılar
│   └── class-ptt-logger.php       # Hassas veri maskelemeli loglama
├── tests/
│   └── test-check-digit.php       # Check-digit algoritması birim testleri
├── ptt-kargo-woocommerce.php      # Eklenti ana giriş dosyası
├── readme.txt                     # WordPress Plugin Directory formatında dokümantasyon
├── tasks.md                       # Teknik geliştirme ve faz takip dokümanı
└── LICENSE                        # GPLv2 Lisans Belgesi

Özel Veritabanı Tabloları

Eklenti etkinleştirildiğinde WordPress veritabanında 2 adet optimize edilmiş tablo oluşturulur:

  1. {$wpdb->prefix}ptt_cities_districts: PTT il ve ilçe kodlarının hızlı fuzzy match eşleşmesi için indeksli önbellek tablosu.
  2. {$wpdb->prefix}ptt_tracking_history: Sipariş bazlı kargo safahat hareketlerinin saklandığı log tablosu.

🛠️ Geliştirici Rehberi (Hooks & API)

Eklenti, üçüncü taraf temalar ve eklentilerle genişletilebilir kancalar (filters & actions) sunar:

1. Kargo Kabul Payload'ını Özelleştirme

add_filter( 'ptt_woo_kabul_ekle_input', function( $input, $order ) {
    // Özel bir açıklama veya referans alanı ekleyin
    $input['aciklama'] = 'Sipariş No: ' . $order->get_order_number() . ' - Kırılabilir Eşya';
    return $input;
}, 10, 2 );

2. Kargo Teslim Edildiğinde Özel Aksiyon Tetikleme

add_action( 'ptt_woo_order_delivered', function( $order_id, $tracking_number ) {
    // Müşteriye özel SMS gönderimi veya faturalama tetikleyicisi
}, 10, 2 );

❓ Hata Kodları ve Sorun Giderme

Durum / Hata Mesajı Olası Neden Çözüm
SonucKodu: -1 / Yetkisiz Erişim musteriId, kullanici veya sifre hatalı. Ayarlar sayfasındaki kimlik bilgilerini ve ortam modunu (Test/Canlı) kontrol ediniz.
İlçe Kodu Bulunamadı Müşterinin girdiği ilçe adı PTT veri tabanıyla uyuşmuyor. Ayarlar sayfasından "İl/İlçe Verilerini Senkronize Et" butonuna basarak yerel eşleme tablosunu güncelleyiniz.
Barkod Havuzu Tükendi Sabit barkod aralığınızdaki tüm numaralar kullanıldı. PTT yetkilinizden yeni barkod aralığı talep edip ayarlar sayfasından başlangıç/bitiş değerlerini güncelleyiniz.
Fiziksel Kabulü Yapılmış Kargo Silinemez Kargo PTT şubesi veya kuryesi tarafından teslim alınmış. PTT şubesi tarafından kabulü yapılmış kargolar web servis üzerinden iptal edilemez; şube ile irtibata geçilmelidir.

🤝 Katkıda Bulunma

  1. Bu depoyu Fork edin (fork).
  2. Yeni özelliğiniz için bir dal oluşturun (git checkout -b feature/yeni-ozellik).
  3. Değişikliklerinizi commit edin (git commit -am 'Yeni özellik eklendi').
  4. Dalınıza push yapın (git push origin feature/yeni-ozellik).
  5. Bir Pull Request (PR) açın.

📄 Lisans

Bu proje GNU General Public License v2.0 (GPLv2) ile lisanslanmıştır. Detaylar için LICENSE dosyasına göz atabilirsiniz.