Nevuto için EasyPost entegrasyonu

EasyPost nedir?

EasyPost, ABD merkezli çok-carrier kargo agregatörüdür. Tek API üzerinden USPS, UPS, FedEx, DHL Express, OnTrac ve 100+ carrier'a US içi ve uluslararası gönderim yapabilirsiniz. ABD içi yoğunlukludur ancak uluslararası teslimatlar da desteklenir.

Nevuto, EasyPost'u nasıl yönetir?

• Tek API key girersin; Nevuto webhook bağlantısını otomatik kurar.
• Yeni hesaplar için anti-fraud manuel inceleme süreci dikkate alınır.
• Sipariş anında canlı rate listesi çekilir ve en ucuz rate satın alınır.
• Tüm webhook'lar imzalı gelir; Nevuto doğruluğunu senin için doğrular.
• Hem Test Key hem de Production Key destekli; tek toggle ile geçiş yaparsın.

1. Ön gereksinimler

• Aktif bir EasyPost hesabı. Yoksa easypost.com üzerinden açın.
  • ⚠️ EasyPost yeni hesaplarda anti-fraud manuel inceleme yapar. Signup sonrası 1-3 iş günü içinde ID verification + business detail isteyen bir mail gelebilir. Hesabınız aktive olana kadar API key tab'ı görünmeyebilir.
• En az bir carrier account EasyPost'ta connected olmalı. Free tier'da default USPS test account'u var; production'da kendi USPS/UPS/FedEx kontratlarınızı bağlayabilirsiniz.
• Mağaza para biriminiz USD olmalı — EasyPost USD-only.
• Sender address ülkesi US olmalı (yaygın); diğer ülkelerde sınırlı.
• EasyPost Wallet'a fund yatırmanız gerekir (label başına ücret kesilir). Settings → Billing.

2. EasyPost API key

1. EasyPost dashboard'una giriş yapın.
2. Account Settings → API Keys (https://app.easypost.com/account/settings?tab=api-keys).
3. Test Key veya Production Key kopyalayın.
4. Hesabınız henüz active değilse "API Keys" tab'ı boş gelebilir. Anti-fraud onayı bekleniyor demektir; support'a mail atın veya signup mail'inin instruction'larını takip edin.

⚠️ Test key ile test etiketler üretilir (ücret kesilmez). Production key gerçek carrier etiketleri basar ve cüzdandan ücret keser.

3. Nevuto'da EasyPost'u bağlama

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

Submit anında Nevuto:

• API key'i güvenli olarak kaydeder
• EasyPost hesabınıza webhook bağlantısını otomatik kurar — manuel adım gerekmez
• Tüm webhook'lar imzalı olarak gelir; Nevuto doğruluğunu sizin için kontrol eder

4. Preferred carrier accounts

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 EasyPost 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 EasyPost rate listesi alınır, tercih ettiğiniz carrier'larla filtrelenir, en ucuz rate satın alınır.
• Hiçbir tercih yoksa tüm aktif carrier'lar arasından en ucuz seçilir.

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

5. Sender address (gönderici adresi)

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

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

⚠️ Telefon numarasını uluslararası format ile girmeniz önerilir: +12125551234. Yerel format da kabul edilir ama uluslararası format en güvenlidir.

6. Shipping packages

EasyPost paket boyutları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: 12×9×1 inch (USPS Flat Rate Envelope)

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.

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.

💡 US'de standart birim in (inch) ve oz (ounce). EasyPost her ikisini kabul eder; Nevuto otomatik konversiyon yapar.

8. Customs declaration (uluslararası)

US → 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: USD
• Contents type: merchandise
• Non-delivery option: return (teslim edilemezse iade)

HS kodu: Nevuto'da ürün bazında saklanmıyor → boş gönderilir. EasyPost 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 EasyPost'u 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 EasyPost cüzdanı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]         ← EasyPost webhook tetiklenir (tracker.updated)
    │
    ▼   Müşteriye teslim
[shipping_status: DELIVERED]       ← Webhook

EasyPost durum eşleştirmesi (Nevuto):

• Yola çıkıyor, transit, dağıtımda → Shipped
• Teslim edildi, pickup hazır → Delivered
• İade, hata, iptal → yok sayılır

Webhook bağlantısı kurulumda otomatik yapılır ve her bildirim imza ile doğrulanır — manuel müdahale gerekmez.

11. Test modu

EasyPost'un gerçek bir test ortamı vardır:

1. EasyPost dashboard → API Keys → Test Key kopyalayın.
2. Nevuto admin → Settings → Shipping → EasyPost → API key alanına test key'i girin, Test mode toggle'ını açın.
3. Submit.
4. Test gönderimleri:
   • Tracking number gelir (EZ100… formatında)
   • Etiket PDF üretilir (test damgalı)
   • Cüzdandan ücret kesilmez
   • Test bildirimleri gönderilir
5. Üretime geçmeden önce Test mode'u kapatın ve Live key'e geçin.

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

A. "We need a bit more information about your account" mail

• EasyPost yeni hesaplara manuel inceleme uygular. Mail'deki soruları yanıtlayıp Stripe ID doğrulama linkini doldurun; 1-3 iş günü içinde hesabınız aktive olur.

B. API key sekmesi gözükmüyor

• Hesap henüz aktive değil (yukarıdaki A maddesi). Veya hesap tipiniz "Personal" seçildi ancak business detayları isteniyor.

C. Cüzdanda bakiye yok, etiket basamıyorum

• EasyPost dashboard → Account → Billing → Add funds ile cüzdana fon yatırın. Test mode'da ücret kesilmez.

D. "Customs declaration is required for international" hatası

• Uluslararası gönderimde gümrük bilgisi gerekiyor. Müşteri adresinin ülke bilgisinin doğru girildiğinden emin olun.

E. State adı reddediliyor

• EasyPost kısa state kodu ister: CA, NY. Tam isim (California) reddedilir. Settings → Locations'da state'i kısa kod olarak girin.

F. Provider listesinde görünmüyor

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

G. Webhook gelmiyor / "Unauthorized" hatası

• API key'i değiştirdiyseniz Nevuto admin'de Submit'e tekrar basın — webhook bağlantısı yeniden kurulur ve imzalama anahtarı tazelenir.

13. Sonraki adımlar

• EasyPost anti-fraud onayı geldiğinde API key ile bağlayın ve küçük tutarlı bir test gönderimi yapın
• HS code'ları EasyPost panel'inde her product için bir kez girin — international orders için kritik
• Shipping rate'lerinize kâr marjı ekleyin

Yardım

• EasyPost: support@easypost.com
• Nevuto: support@nevuto.com