Nevuto için Geliver entegrasyonu

Geliver nedir?

Geliver, çevrimiçi mağazalar için hızlı ve takip edilebilir kargoya odaklanan, Türkiye merkezli çok-firmalı bir kargo agregatörüdür. Tek bir API üzerinden Aras Kargo, Yurtiçi Kargo, MNG, PTT, Sürat Kargo, HepsiJet, Kolay Gelsin ve Paket Taksi'ye gönderim yapabilirsin. Türkiye'de satış yapan Nevuto satıcıları için Geliver; her kargo şirketiyle ayrı ayrı pazarlık yapmadan güvenilir yurt içi gönderim eklemenin en hızlı yollarından biridir.

Nevuto, Geliver'ı nasıl yönetir?

• Nevuto, Geliver'a resmi kargo API'si üzerinden, Geliver panelinden ürettiğin bir API anahtarıyla bağlanır.
• Sipariş fulfill edilirken Geliver, seçili kargo firmaların arasından en uygun fiyatlı offer'ı seçer.
• Her Nevuto siparişi için sipariş ekranından tek tıkla bir Geliver etiketi oluşturulur — etiket PDF olarak yazıcıya hazırdır.
• Takip numaraları otomatik olarak siparişe yazılır, müşteri sevkiyat onayı e-postasında takip bağlantısını alır.
• Kargo durum güncellemeleri (yola çıktı / teslim edildi) Geliver webhook'u üzerinden otomatik düşer; manuel müdahale gerekmez.

1. Ön gereksinimler

• Aktif bir Geliver hesabı. Yoksa geliver.io üzerinden açın.
• En az bir gönderici adresi Geliver hesabınızda kayıtlı olmalı. Geliver panelinden Adresler bölümünden ekleyebilirsiniz.
• En az bir kargo firması sözleşmesi Geliver hesabınızda aktif olmalı. Geliver Pazar Yeri'nde kullanmak istediğiniz kargo firmalarını seçin.
• Mağaza para biriminiz TRY olmalı. Geliver TL bazlı fiyat döndürür; başka para birimindeki bir mağaza ile fiyat referansı import edemezsiniz (sistem engelleyecektir).

2. Geliver API token'ı

1. Geliver paneline giriş yapın.
2. Hesap → API & Entegrasyon bölümüne gidin.
3. Yeni bir API token oluşturun (varsa mevcut token'ı kullanın).
4. Token'ı kopyalayın — bir sonraki adımda Nevuto'ya yapıştıracaksınız.

⚠️ Token gizli bir bilgidir, kimseyle paylaşmayın. Sızdığını fark ederseniz Geliver panelinden iptal edip yenisini üretin.

3. Nevuto'da Geliver'ı bağlama

1. Nevuto admin panelinden Settings → Shipping → Shipping providers menüsüne gidin.
2. Listeden Geliver'ı seçin.
3. API key alanına Geliver'dan kopyaladığınız token'ı yapıştırın.
4. Enable shipping method toggle'ını açın.
5. (Opsiyonel) Test mode toggle'ını açarsanız Geliver'a gerçek etiket satın almadan test gönderimi yapabilirsiniz. Üretim öncesi denemek için önerilir.
6. Submit'e tıklayın.

API key kaydedildikten sonra altta Settings kartı açılır. Buradan Geliver'a özel ayarları yapılandırırsınız.

4. Sender address (gönderici adresi)

• Auto-resolve (varsayılan): Geliver hesabınızdaki "default sender" adresini otomatik kullanır.
• Belirli bir adres seçmek istiyorsanız: dropdown'dan Geliver'da kayıtlı adreslerinizden birini seçin.

Bir Geliver hesabınızda birden fazla gönderici adresi varsa (örn. ana depo + ikinci şube) ve siparişlerinizi belirli bir adresten göndermek istiyorsanız bu seçimi yapın.

5. Preferred carriers (tercih edilen kargo firmaları)

Bu adımda hangi kargo firmaları arasından seçim yapılacağını belirlersiniz.

1. Dropdown'dan bir veya birden çok kargo firması seçin (Aras, Yurtiçi, MNG, PTT, Sürat, HepsiJet, Kolay Gelsin, Paket Taksi).
2. Submit edin.

Davranış:

• Sipariş fulfill edilirken Geliver, seçili kargo firmalarınızdan en uygun fiyatlı offer'ı seçer.
• Hiçbir firma seçmezseniz Geliver kendi varsayılan "cheapest" önerisini kullanır.
• Seçili firmalardan hiçbiri o güzergaha hizmet vermiyorsa, otomatik olarak cheapest'e fallback yapılır (siparişiniz aksamaz).

💡 İpucu: Yalnızca sözleşmeniz olan ve hesabınızda aktif olan kargo firmalarını seçin. Geliver hesabınızda aktif olmayan firmalar fiyat referansı tablosunda görünmez.

6. Carrier price reference (fiyat referans tablosu)

Preferred carriers seçtikten ve kaydettikten sonra altta fiyat referans tablosu açılır.

Ne gösterir?

• Seçtiğiniz kargo firmaları için Geliver'ın yayınlanmış desi-bazlı fiyatları.
• Sabit desi değerlerinde (1, 2, 3, 5, 10, 15, 20, 30) her firmanın KDV dahil TL fiyatı.
• "—" işareti: o firma o desi için fiyat döndürmüyor (genelde hesabınızda aktif değil veya o ağırlığı kabul etmiyor demektir).

Nasıl kullanılır?

1. Tabloyu inceleyin — hangi firma hangi desi tier'da daha uygun?
2. Kendi shipping rate'lerinizi oluştururken bu fiyatları referans alın. Üzerine kâr marjı koyarak müşteriden alacağınız kargo ücretini belirleyin.
3. Her satırın sonundaki checkbox'ı işaretleyin → submit edince otomatik shipping rate kuralı oluşturulur:
   • min_desi → max_desi: seçtiğiniz desi'lerden kademeli tariff (örn. 1, 5, 10 seçerseniz: 0–1, 1–5, 5–10 desi aralıkları).
   • Fiyat: o satırdaki seçili kargo firmalarının en yüksek fiyatı kullanılır (worst-case; zarar etmeyesiniz diye).
   • İsim: max fiyatı veren firma + desi (örn. "Aras Kargo — up to 5 desi").
   • Kurallar mağazanızın default shipping profile'ının ilk zone'una eklenir.
4. Daha sonra Settings → Shipping → Rates altında bu kuralları manuel düzenleyebilirsiniz (örn. kâr marjı eklemek için).

⚠️ Bu özellik sadece mağaza para biriminiz TRY ise çalışır. USD/EUR vb. mağazalarda uyarı gösterilir ve checkbox'lar disable olur.

7. Shipping packages (paket şablonları)

Geliver'a gönderim yaparken parcel boyutları (length × width × height + ağırlık) gerekli. Bunları üç farklı yerden alabiliriz, öncelik sırası:

1. Variant LWH bilgileri — ürün varyantında doğrudan girilmişse.
2. ShippingPackage referansı — varyant bir paket şablonuna bağlıysa o şablonun ölçüleri.
3. Mağaza varsayılan paketi — Settings → Shipping → Packages altında "Default" işaretli olan paket.
4. Son çare: 20×20×20 cm fallback.

Adımlar:

1. Settings → Shipping → Packages sayfasına gidin.
2. Add package → Ad, Tip (Box/Envelope/Soft pack), L/W/H/birim, ağırlık girin.
3. Bir paket "Standard package" otomatik oluşturulmuştur (shop kuruluşunda); ölçülerini güncellemeniz yeterli.
4. Set as default → mağaza-geneli fallback için bir paketi varsayılan yapın.

💡 Çok çeşitli ürün satıyorsanız: birkaç farklı paket şablonu (Small box, Medium box, Large box) tanımlayın, varyantlarınıza atayın.

8. Variant LWH (varyant boyutları)

En doğru fiyat için her varyanta gerçek boyut girmenizi öneririz:

1. Products → ürün düzenle → Variants sekmesi.
2. Her satırda Length / Width / Height / Weight alanlarını doldurun.
3. Birim olarak cm veya in seçin.

Eğer varyantta boyut yoksa ShippingPackage'a düşer, oradan da yoksa shop default'a, oradan da yoksa 20×20×20 cm'e.

9. Sipariş gönderme

Müşteri ödemeyi yaptıktan sonra sipariş admin panelinizde "Mark as shipped" butonu ile gönderime hazır görünür.

1. Order detail sayfasını açın.
2. Mark as shipped butonuna basın.
3. Açılan modal'da provider olarak Geliver'i seçin ve Submit edin.
   • Geliver dışında bir kargocuyla manuel göndereceğiniz nadir durumlarda Manual seçip tracking numarasını elle de girebilirsiniz; bu seçenek Geliver'a gönderim oluşturmaz.
4. Birkaç saniye içinde sipariş satırında tracking numarası, tracking link ve "Print label" butonu belirir. Aynı anda Geliver bakiyenizden etiket ücreti düşer.
5. Print label'a tıklayarak irsaliye PDF'ini açın, yazdırın ve pakete yapıştırın.
6. Paketi seçtiğiniz kargo şirketine teslim edin — gerisi otomatik takip edilir. Sipariş detay sayfasında "Shipping status is updated automatically by the carrier" bilgilendirmesi görürsünüz.

💡 Müşteri kendi sipariş sayfasından tracking link'i ile gönderiyi takip edebilir; ayrıca durum değiştikçe email bilgilendirmesi alır.

10. Status lifecycle (durum güncellemesi)

Sipariş gönderildikten sonra durum güncellemeleri otomatik gelir:

Mark as shipped
    │
    ▼
[shipping_status: PROCESSING]      ← Etiket basıldı, kargo henüz almadı
    │
    ▼   Kargocu tarama yapar
[shipping_status: SHIPPED]         ← Webhook tetiklenir, müşteriye "Yola çıktı" emaili
    │
    ▼   Müşteriye teslim
[shipping_status: DELIVERED]       ← Webhook, müşteriye "Teslim edildi" emaili

Nasıl çalışıyor:

1. Geliver entegrasyonunu kaydederken Nevuto, Geliver hesabınıza otomatik bir webhook bağlantısı kurar.
2. Kargo firması paketi taradığında Geliver Nevuto'ya bildirim gönderir.
3. Nevuto bunu yakalar, order'ı tracking number ile bulur, status'u günceller.
4. SHIPPED → OrderShippedEvent → inventory düşülür, müşteriye mail gider.
5. DELIVERED → OrderDeliveredEvent → müşteriye teslim emaili gider.

Manuel müdahale gerekmez. Sipariş durumunu kendiniz değiştirmek istemeyin — webhook'un üzerine yazar.

11. SMS bildirimleri

• Nevuto email ile bildirim gönderir (Order shipped / Order delivered).
• SMS Nevuto'dan gönderilmez.
• Geliver veya altındaki kargo firması müşteriye SMS gönderir (TR'de standart davranıştır — kargocular telefon numarasına otomatik SMS atar).
• Geliver panelinde SMS bildirim ayarları varsa kontrol edin.

12. Test modu

Üretime almadan önce mutlaka test edin:

1. Geliver settings'te Test mode'u açın + kaydedin.
2. Mağaza önyüzünden gerçek bir order oluşturun (TL para biriminde küçük tutar — 1 ₺ ürün).
3. Ödemeyi tamamlayın (Stripe test card veya başka bir test gateway).
4. Admin'de Mark as shipped → Geliver seç → Submit.
5. Sonuç:
   • Geliver panelinizde test shipment olarak görünür.
   • Gerçek etiket satın alınmaz.
   • Tracking number gelir ama gerçek kargocu yoktur.
6. Akışı doğruladıktan sonra Test mode'u kapatın, gerçek üretime geçin.

13. Sık karşılaşılan sorunlar

"Geliver API key missing" hatası API key'i boş kaydetmişsinizdir. Settings → Shipping → Geliver → API key alanına token'ı tekrar girin.

"City not found / district not found" Geliver hatası Müşterinin adresinde il/ilçe Geliver'ın beklediği formatla uyumsuz. Nevuto otomatik mapping yapar (province_code → il, city → ilçe) ama bazı edge case'lerde başarısız olur. Müşteri adres bilgisini kontrol edin; özellikle "ilçe" alanı net olmalı (kısaltma değil tam isim).

Fiyat referans tablosu boş geliyor

• Hiç checkbox seçili değil: preferred carriers'a en az 1 firma ekleyip kaydedin.
• "—" her yerde: seçtiğiniz kargo firmaları Geliver hesabınızda aktif değil. Geliver panelinde sözleşme/aktivasyon durumunu kontrol edin.
• Currency uyarısı: mağazanız TRY değil. Fiyatlar gösterilir ama checkbox'lar disable, import yapamazsınız.

Order otomatik Geliver'a gidiyor (Mark as shipped'e basmadan) Bu davranış 2026-05-20'de düzeltildi. Hâlâ yaşıyorsanız PHP queue worker'ı restart edilmemiş olabilir. Workers'ı yeniden başlatın.

Tracking URL gelmiyor / "—" gösteriyor Geliver'ın trackingUrl field'ı kargocu paketi alana kadar boş gelebilir. Nevuto fallback olarak https://app.geliver.io/tracking/{shipmentId} URL'ini kullanır; bu link Geliver paneline yönlendirir.

Webhook gelmiyor / status güncellenmiyor

• Geliver hesabınızda webhook kayıtlı mı kontrol edin (Geliver paneli → API → Webhooks).
• Nevuto admin'de Geliver ayarlarına gidip Submit'e tekrar basın — webhook otomatik olarak yeniden kurulur.

14. Sonraki adımlar

• Üretim siparişlerini izleyin ilk hafta — Geliver paneli ile Nevuto arasında tutarlılık kontrolü yapın.
• Shipping rate'lerinize kâr marjı ekleyin — fiyat referansı tablosundan import edilen rate'ler maliyet fiyatıdır; müşteriden almak istediğiniz tutara göre güncelleyin.
• Tatil dönemlerinde Geliver panelini açık tutun — gecikme/iade durumlarını oradan da takip edin.

Yardım

Geliver API'si veya Nevuto entegrasyonu ile ilgili sorunlarda:

• Geliver tarafı: Geliver destek (geliver.io üzerinden)
• Nevuto tarafı: support@nevuto.com