Nevuto için Shippo entegrasyonu

Shippo nedir?

Shippo, Kuzey Amerika merkezli çok-carrier kargo agregatörüdür. Tek bir API üzerinden USPS, UPS, FedEx, DHL Express, Canada Post ve daha pek çok carrier ile US ve Canada içi gönderim, ek olarak uluslararası teslimat yapabilirsiniz. ABD/Kanada'da satış yapan Nevuto mağazaları için en pratik kargo altyapılarından biridir.

Nevuto Shippo'yu nasıl yönetir?

• Nevuto, Shippo'nun resmi API'sine bağlanır ve webhook bağlantısını otomatik kurar — manuel adım yok.
• Sipariş gönderiminde Shippo tüm carrier'lardan canlı fiyat alır ve en ucuzu seçer.
• Her Nevuto siparişi için tek tıkla label PDF üretilir, yazdırmaya hazır.
• Tracking numarası ve durumu, Shippo webhook'ları üzerinden otomatik senkronize edilir.
• Live token'la üretim, Test tokens ile sandbox testi desteklenir.

1. Ön gereksinimler

• Aktif bir Shippo hesabı. Yoksa goshippo.com üzerinden açın.
• En az bir carrier account Shippo'da connected olmalı (USPS Shippo'da default gelir; UPS/FedEx için kendi hesabınızı bağlamanız gerek).
• Mağaza para biriminiz USD veya CAD olmalı — diğer para birimlerinde Shippo provider listesinde "Not available" görünür.
• Sender address ülkesi US veya CA olmalı (yaygın); diğer ülkelerde sınırlı kapsama.
• Hesap fonlama: Shippo wallet'a top-up yapın veya credit card kaydedin. Her label anlık ücretlendirilir.

2. Shippo API token

1. Shippo dashboard'una giriş yapın.
2. Sağ üst → Settings → API.
3. Live tokens sekmesinden bir token oluşturun (veya Test tokens test için).
4. Token'ı kopyalayın — bir sonraki adımda Nevuto'ya yapıştıracaksınız.

⚠️ Live token gerçek label üretir ve hesabınızdan ücret keser. Test için Test mode kullanın (aşağıda).

3. Nevuto'da Shippo'yu bağlama

1. Nevuto admin panelinden Settings → Shipping → Shipping providers menüsüne gidin.
2. Listeden Shippo'yu seçin.
3. API key alanına Shippo token'ınızı yapıştırın.
4. Enable shipping method toggle'ını açın.
5. (Opsiyonel) Test mode toggle'ı: Test token kullanıyorsanız açın. Live token'la birlikte kapalı bırakın.
6. Submit'e tıklayın.

Submit anında Nevuto:

• API key'i güvenli olarak kaydeder
• Shippo hesabınıza webhook bağlantısını otomatik kurar — manuel adım gerekmez
• Eski webhook varsa silinir ve yenisi kurulur (tekrar Submit ederseniz aynı şekilde yenilenir)

4. Preferred carriers (tercih edilen carrier'lar)

Kaydettikten sonra altta Settings kartı açılır:

1. Preferred carriers dropdown'ından bir veya birden çok carrier account ID seçin.
2. Dropdown listesi Shippo hesabınızdan canlı olarak çekilir — sadece sizin hesabınızda aktif olan carrier'lar görünür.
3. Submit edin.

Davranış:

• Sipariş gönderilirken Shippo tüm carrier'lardan fiyat teklifi alır → tercih ettiğiniz carrier'larla filtreler → en ucuz olanı seçer.
• Hiçbir tercih yoksa Shippo'nun önerdiği en iyi değerli rate kullanılır.
• Tercih ettiğiniz carrier o güzergaha hizmet vermiyorsa tüm seçenekler arasından en ucuzu seçilir (siparişiniz aksamaz).

💡 Dropdown'da carrier'larınız readable name'leriyle görünür (USPS, UPS, DHL Express vb.).

5. Sender address (gönderici adresi)

Shippo her gönderim için sender adresinizi kullanır. Nevuto bu adresi mağaza varsayılan lokasyonundan çeker:

1. Settings → Locations sayfasına gidin.
2. Default location'ınızı US/CA adresi olarak doldurun:
   • Street, City, State (kısa kod: CA, NY, vb.), ZIP, Country (US/CA), Phone

⚠️ State alanı için kısa kod kullanın (örn. CA, NY, TX) — Shippo full state name kabul etmez.

6. Shipping packages (paket şablonları)

Shippo paket boyutlarını ve ağırlığını her gönderimde ister. Nevuto bu bilgiyi şu sırayla alır:

1. Variant LWH bilgileri
2. ShippingPackage referansı
3. Mağaza varsayılan paketi
4. Fallback: Shippo kendi default'unu kullanır (genelde mismatch)

Adımlar:

1. Settings → Shipping → Packages sayfasına gidin.
2. Add package → Ad, Tip, L/W/H/birim, ağırlık.
3. Set as default → mağaza-geneli fallback.

7. Variant LWH

Her varyanta gerçek boyut + ağırlık girin:

1. Products → ürün düzenle → Variants.
2. Length / Width / Height / Weight.
3. Birim: cm/in, weight: g/kg/oz/lb.

8. Customs declaration (uluslararası)

US/CA → diğer ülkelere gönderimde Nevuto otomatik gümrük bildirimi ekler:

• Items: sipariş satırları (ürün açıklaması, adet, ağırlık, değer, menşe ülke)
• US gümrük gereklilikleri: gerekli muafiyet işaretleri otomatik eklenir
• Currency: mağaza para birimi (USD/CAD)
• Contents type: MERCHANDISE

HS kodu: Nevuto'da ürün bazında saklanmıyor → boş gönderilir. Shippo panel'inde manuel girebilirsiniz.

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 Shippo'yu seçin ve Submit edin.
4. Birkaç saniye içinde sipariş satırında tracking numarası, tracking link ve "Print label" butonu belirir. Aynı anda Shippo hesabınızdan etiket ücreti düşer.
5. Print label'a tıklayarak etiketi PDF olarak açın, yazdırın ve pakete yapıştırın.
6. Paketi tercih ettiğiniz carrier'a teslim edin — gerisi otomatik takip edilir.

💡 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

Mark as shipped
    │
    ▼
[shipping_status: PROCESSING]      ← Label basıldı, carrier henüz almadı
    │
    ▼   Carrier paketi taradığında
[shipping_status: SHIPPED]         ← Shippo webhook tetiklenir
    │
    ▼   Müşteriye teslim
[shipping_status: DELIVERED]       ← Webhook

Webhook bağlantısı kurulumda otomatik yapılır — Shippo tracking güncellemeleri Nevuto'ya gelir, sipariş durumu otomatik güncellenir.

11. Test modu

Shippo gerçek bir test environment sunar:

1. Shippo dashboard → API → Test tokens sekmesinden token alın.
2. Nevuto'da Settings → Shipping → Shippo → Test mode toggle'ını açın + API key'i test token ile değiştirin.
3. Submit.
4. Test gönderimleri:
   • Tracking number döner
   • Label PDF üretilir (Shippo Logo'lu test page)
   • Hesabınızdan gerçek ücret kesilmez
   • Test webhook'ları gönderilir
5. Üretime almadan önce Test mode kapatın ve API key'i Live token ile değiştirin.

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

A. Etiket oluştu ama tracking güncellenmiyor

• Shippo rate seçiminde bir sorun olabilir. Sık nedenler:
  • Sender/recipient adres doğrulama problemleri (state kısa kodu yanlış vb.)
  • Uluslararası gönderimde HS kodu eksik
  • Carrier hesabınız duraklatılmış
• Shippo dashboard'unda Shipments → ilgili gönderim → hata mesajını kontrol edin.

B. "Customs declaration is required for international shipments via the USPS"

• Uluslararası gönderimde gümrük bilgisi eklenmiyor. Mağaza adresinizin ve müşteri adresinin ülke kodlarının doğru girildiğinden emin olun.

C. State name reject ediyor

• Shippo state code (kısa) ister: CA (California için), NY, vb. Tam isim (California) reddedilir. Settings → Locations'da state'i kısa kod olarak girin.

D. Provider listesinde görünmüyor

• Mağaza para biriminiz USD/CAD değilse "Not available in your store currency" uyarısı görünür. Settings → General → Currency.
• Mağaza adresinizin ülkesi US/CA değilse "Doesn't ship from your shop location" uyarısı görünür.

E. Webhook gelmiyor

• Nevuto admin'de Shippo ayarlarına gidip Submit'e tekrar basın — webhook bağlantısı yeniden kurulur.

13. Sonraki adımlar

• İlk haftada Shippo dashboard ile Nevuto arasında tutarlılık kontrolü yapın
• Shipping rate'lerinize kâr marjı ekleyin — Shippo'nun cheapest rate'i maliyet; müşteriden almak istediğinize göre ayarlayın
• USPS Priority Mail Express International gibi international servisleri kullanıyorsanız HS code'ları doldurmayı unutmayın

Soru / yardım

• Shippo tarafı: support@goshippo.com veya dashboard chat
• Nevuto tarafı: support@nevuto.com