Ana içeriğe atla
nevuto.com'a git

Nevuto için The Courier Guy entegrasyonu

Yayın: 29 Nisan 20267 dk okuma1 hafta önce güncellendi

The Courier Guy nedir?

The Courier Guy, Güney Afrika'nın en büyük kargo şirketlerinden biridir. Arkasında ShipLogic platformu vardır; Nevuto API'sini bu platform üzerinden konuşur. ECO/OVN/STD/SDX servis seviyeleriyle Güney Afrika içi (yurtiçi) gönderim yapabilirsiniz.

Nevuto, TCG entegrasyonunu nasıl yönetir?

  • Nevuto, TCG'ye ShipLogic API'si üzerinden bağlanır; tek bir API token Sandbox ya da production hesabınızı temsil eder.
  • Hem sandbox (test) hem production (canlı) ortamı desteklenir; geçişi Nevuto'daki Test mode toggle'ı yönetir.
  • Webhook'lar TCG/ShipLogic portalında manuel kurulur — TCG API üzerinden webhook eklemeye izin vermez.
  • Mağaza para biriminiz ZAR olmalıdır; aksi halde TCG provider listesinde "Not available" görünür.
  • Sender address ülkesi ZA olmak zorundadır; TCG sadece Güney Afrika içinden gönderim yapar.

1. Ön gereksinimler

  • Aktif bir The Courier Guy hesabı (canlı) veya Sandbox Couriers hesabı (test):
  • Mağaza para biriminiz ZAR olmalı — diğer para birimlerinde TCG provider listesinde "Not available" görünür.
  • Sender address ülkesi ZA olmalı — TCG sadece Güney Afrika içinden gönderim yapar.
  • Hesap bakiyesi veya credit terms — production'da label başına ücret düşer.

2. The Courier Guy / Sandbox API key

Test (sandbox) için:

  1. sandbox.shiplogic.com/register → ücretsiz kayıt olun.
  2. E-posta doğrulayın → giriş yapın.
  3. Settings → API Keys → key oluşturun.
  4. Token'ı kopyalayın.

Canlı kullanım için:

  1. TCG portal'a giriş yapın (portal.thecourierguy.co.za).
  2. Settings → API Keys → key oluşturun.
  3. Token'ı kopyalayın.

⚠️ Test ve canlı hesaplar ayrı sistemlerdir. Aralarında geçiş yapmak için aşağıdaki "Test mode" toggle'ını kullanın.

3. Nevuto'da The Courier Guy'ı bağlama

  1. Nevuto admin panelinden Settings → Shipping → Shipping providers menüsüne gidin.
  2. Listeden The Courier Guy'ı seçin.
  3. API key alanına token'ınızı yapıştırın.
  4. Enable shipping method toggle'ını açın.
  5. Test mode toggle'ı: Sandbox key kullanıyorsanız mutlaka açın, canlı key'le kapalı bırakın. Bu toggle Nevuto'nun hangi TCG ortamıyla konuşacağını belirler.
  6. Submit'e tıklayın.

Submit anında Nevuto:

  • API key'i güvenli olarak kaydeder
  • TCG webhook'ları için manuel kurulum gerekir (aşağıda gösteriyoruz) — TCG API ile webhook eklemeye izin vermez, panel'den ayarlamanız gerek

4. Webhook'u manuel kurma (zorunlu)

TCG webhook'larını API üzerinden değil portal üzerinden ayarlatır. Sipariş durum güncellemelerinin Nevuto'ya gelmesi için bu adımı atlamayın:

  1. TCG / Sandbox portal'a giriş yapın.
  2. Settings → Webhook subscriptions menüsüne gidin.
  3. Add webhook subscription → topic seçimi:
    • Tracking event — sipariş durumu değişiklikleri (zorunlu)
    • Diğer topic'ler opsiyonel (Shipment note, Parcel dimension changes vb.)
  4. URL alanına yapıştırın: 
    https://core-api.nevuto.com/v1/admin/shipping/status/webhook/{shopID}/thecourierguy
    {shopID} yerine Nevuto admin → Settings → General → Shop ID alanındaki 32 karakterlik kimliği yazın.
  5. Save.

💡 Bu URL'i yetkisiz kişilerle paylaşmayın; sipariş durumlarınızı değiştirebilir.

5. Service level (servis seviyesi)

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

  1. Service level dropdown'ından bir veya birden çok TCG servis kodu seçin:
    • ECO — Economy (en ucuz, varsayılan, 3-5 iş günü)
    • OVN — Overnight Express (1 iş günü)
    • STD — Standard (2-3 iş günü)
    • SDX — Same Day Express (büyük şehirlerde aynı gün)
  2. Submit edin.

Davranış:

  • Sipariş gönderilirken Nevuto, tercih ettiğiniz ilk service level'ı kullanır (TCG her gönderim için tek service level kabul eder).
  • Hiçbir seçim yapmazsanız ECO varsayılan olarak kullanılır.

💡 TCG yeni bir service level eklerse Nevuto güncellemesi sonrası dropdown'da görünür.

6. Sender address

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

  1. Settings → Locations.
  2. Default location'ı ZA adresi olarak doldurun:
    • Street, City, Province (örn. Gauteng veya kısa kod GP), ZIP (postal code), Country (ZA), Phone

💡 Province alanı: TCG hem tam isim (Gauteng) hem kısa kod (GP) kabul eder.

7. Shipping packages

TCG paket boyutlarını cm, ağırlığı kg olarak ister. Nevuto bu bilgiyi şu sırayla alır:

  1. Variant LWH bilgileri — ürün varyantında girilmişse (en doğru)
  2. ShippingPackage referansı
  3. Mağaza varsayılan paketi
  4. Son çare: 20×20×20 cm + 0.5 kg fallback

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.

8. Variant LWH

Her varyanta gerçek boyut + ağırlık girin (TCG ücretlendirmesi volumetric weight'a duyarlıdır):

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

9. Customs declaration (uluslararası)

TCG şu an sadece ZA içi çalışır. Uluslararası gönderim için bu integration'ı kullanmayın — Shippo/EasyPost gibi başka bir provider düşünün.

10. 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 The Courier Guy'ı seçin ve Submit edin.
  4. Birkaç saniye içinde sipariş satırında TCG tracking numarası (örn. S7GL...), tracking link ve "Print label" butonu belirir.
  5. Print label'a tıklayarak waybill PDF'i açın, yazdırın ve pakete yapıştırın.
  6. Paketi TCG kuryesine teslim edin veya yakındaki TCG drop-off noktasına bırakın.

💡 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.

11. Status lifecycle

Mark as shipped
    │
    ▼
[shipping_status: PROCESSING]      ← Etiket basıldı, carrier henüz almadı
    │
    ▼   "collected" → carrier paketi aldı
[shipping_status: SHIPPED]         ← Webhook
    │
    ▼   "in-transit", "at-hub", "out-for-delivery" — devam
    │
    ▼   "delivered" → müşteride
[shipping_status: DELIVERED]       ← Webhook

TCG durum eşleştirmesi (Nevuto):

  • Alım öncesi: submitted, collection-assigned, awaiting-dropoff → değişiklik yok
  • Transit: collected, at-hub, manifested, ready-for-dispatch, in-transit, at-destination-hub, delivery-assigned, out-for-delivery, returned-to-hub → Shipped
  • Teslim: delivered, ready-for-pickup → Delivered
  • Başarısız teslim: cancelled, undeliverable, returned-to-sender ve istisna durumlar → yok sayılır

12. Label download

"Print label" butonuna tıklayınca etiket PDF'i yeni sekmede açılır. Sticker tipi etiket gerekirse TCG portal'dan da indirebilirsiniz.

13. Test modu

Sandbox'la başlamanızı öneririz:

  1. sandbox.shiplogic.com → hesap açın, API key alın.
  2. Nevuto'da Test mode AÇIK + sandbox key girin + Submit.
  3. Test gönderimleri:
    • Tracking number gelir
    • Etiket PDF üretilir (test damgalı)
    • Gerçek courier hareketi yoktur (test ortamı simüle eder)
    • Test webhook'ları gönderilir (Tracking event'e abone olduysanız)
  4. Üretime geçmeden önce Test mode'u kapatın ve canlı API key girin.

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

A. Tracking number geliyor ama durum güncellenmiyor

  • TCG portal → Webhook subscriptions kontrol edin. Tracking event konusunda Nevuto webhook URL'i kayıtlı mı? Eğer eklemediyseniz durum güncellemeleri Nevuto'ya gelmez (4. bölüme bkz.)

B. "401 Unauthorized" hatası

  • Sandbox key'iyle canlı ortama veya tersine bağlanmaya çalışıyor olabilirsiniz. Test mode toggle'ını doğru ayarlayın.

C. Service level "OVN" reddediliyor

  • TCG hesabınızda OVN servisi aktif değil. TCG portal → Account → Services'tan kontrol edin. ECO her hesapta varsayılan olarak çalışır.

D. Paket boyutları 20×20×20 görünüyor

  • Ürün varyantında boyut bilgisi girilmemiş; Nevuto bu varsayılan değerleri kullanıyor. Daha doğru ücretlendirme için variant'lara LWH girin.

E. State adı reddediliyor

  • TCG hem Gauteng hem GP kabul eder. Reddediliyorsa province alanında yazım hatası vardır.

F. Provider listesinde görünmüyor

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

G. Canlıya geçince webhook çalışmıyor

  • Sandbox ve canlı hesaplar ayrı webhook kayıtları kullanır. Canlı TCG portal'da webhook subscription'ı yeniden ekleyin.

15. Sonraki adımlar

  • Sandbox'ta end-to-end test yapın — order create → fulfill → label download → simulated tracking webhook gelene kadar
  • Production'a geçtikten sonra ilk haftada TCG portal ile Nevuto arasında tutarlılık izleyin
  • OVN/SDX service level'larını spesifik müşteri segmentleri için flat-rate olarak shipping rules'a ekleyin

Soru / yardım

İlgili makaleler