Zum Hauptinhalt springen
Zu nevuto.com

The Courier Guy mit Nevuto verbinden

Veröffentlicht am 29. April 20267 Min. LesezeitVor 1 Woche aktualisiert

Was ist The Courier Guy?

The Courier Guy ist einer der größten Paketdienste Südafrikas. Im Hintergrund läuft die Plattform ShipLogic — über deren API spricht Nevuto mit dem Carrier. Du kannst Sendungen mit den Servicestufen ECO/OVN/STD/SDX innerhalb Südafrikas verschicken.

So bindet Nevuto The Courier Guy an

  • Nevuto verbindet sich über die ShipLogic-API mit TCG; ein einziger API-Token repräsentiert dein Sandbox- oder Production-Konto.
  • Sowohl die Sandbox- (Test-) als auch die Production- (Live-) Umgebung werden unterstützt; der Test mode-Schalter in Nevuto entscheidet, mit welcher Umgebung kommuniziert wird.
  • Webhooks musst du manuell im TCG/ShipLogic-Portal einrichten — TCG erlaubt das Anlegen von Webhooks nicht per API.
  • Deine Shop-Währung muss ZAR sein, sonst erscheint TCG in der Provider-Liste als "Not available".
  • Die Absenderadresse muss im Land ZA liegen — TCG verschickt nur aus Südafrika heraus.

1. Voraussetzungen

  • Ein aktives The Courier Guy-Konto (live) oder ein Sandbox Couriers-Konto (test):
  • Deine Shop-Währung muss ZAR sein — in anderen Währungen wird TCG in der Provider-Liste als "Not available" angezeigt.
  • Das Land deiner Absenderadresse muss ZA sein — TCG verschickt nur innerhalb Südafrikas.
  • Kontoguthaben oder Kreditkonditionen — im Live-Betrieb wird pro Etikett abgerechnet.

2. The Courier Guy / Sandbox API-Key

Für Tests (Sandbox):

  1. Öffne sandbox.shiplogic.com/register → registriere dich kostenlos.
  2. Bestätige deine E-Mail → melde dich an.
  3. Settings → API Keys → erzeuge einen Key.
  4. Kopiere den Token.

Für den Live-Betrieb:

  1. Melde dich im TCG-Portal an (portal.thecourierguy.co.za).
  2. Settings → API Keys → erzeuge einen Key.
  3. Kopiere den Token.

⚠️ Test- und Live-Konten sind getrennte Systeme. Über den "Test mode"-Schalter weiter unten wechselst du zwischen ihnen.

3. The Courier Guy in Nevuto anbinden

  1. Öffne im Nevuto-Admin Settings → Shipping → Shipping providers.
  2. Wähle The Courier Guy aus der Liste.
  3. Füge deinen Token in das Feld API key ein.
  4. Aktiviere den Schalter Enable shipping method.
  5. Test mode-Schalter: Verwendest du einen Sandbox-Key, schalte ihn ein; bei einem Live-Key lass ihn aus. Damit entscheidet Nevuto, mit welcher TCG-Umgebung gesprochen wird.
  6. Klicke auf Submit.

Beim Submit:

  • speichert Nevuto deinen API-Key sicher,
  • musst du die TCG-Webhooks manuell anlegen (siehe unten) — TCG akzeptiert keine Webhook-Anmeldungen über die API, du musst sie im Portal eintragen.

4. Webhook manuell einrichten (Pflicht)

TCG erlaubt die Webhook-Konfiguration ausschließlich im Portal, nicht über die API. Überspringe diesen Schritt nicht, sonst erhält Nevuto keine Statusupdates:

  1. Melde dich im TCG- oder Sandbox-Portal an.
  2. Öffne Settings → Webhook subscriptions.
  3. Add webhook subscription → wähle das Topic:
    • Tracking event — Statusänderungen der Sendung (Pflicht)
    • Weitere Topics sind optional (Shipment note, Parcel dimension changes usw.)
  4. Trage diese URL ein: 
    https://core-api.nevuto.com/v1/admin/shipping/status/webhook/{shopID}/thecourierguy
    Ersetze {shopID} durch die 32-stellige ID aus Nevuto-Admin → Settings → General → Shop ID.
  5. Speichern.

💡 Gib diese URL nicht an Unbefugte weiter — damit könnten sie deine Bestellstatus verändern.

5. Service level

Nach dem Speichern öffnet sich darunter eine Settings-Karte:

  1. Wähle im Dropdown Service level einen oder mehrere TCG-Servicecodes:
    • ECO — Economy (günstigster Tarif, Standard, 3-5 Werktage)
    • OVN — Overnight Express (1 Werktag)
    • STD — Standard (2-3 Werktage)
    • SDX — Same Day Express (gleicher Tag in Großstädten)
  2. Klicke auf Submit.

Verhalten:

  • Beim Erstellen der Sendung verwendet Nevuto den ersten ausgewählten Service Level (TCG akzeptiert pro Sendung nur einen).
  • Wählst du nichts aus, wird ECO als Standard verwendet.

💡 Falls TCG einen neuen Service Level einführt, erscheint er nach dem nächsten Nevuto-Update im Dropdown.

6. Absenderadresse

TCG verwendet bei jeder Sendung deine Absenderadresse. Nevuto übernimmt sie aus dem Standardstandort deines Shops:

  1. Settings → Locations.
  2. Trage die Default Location als ZA-Adresse ein:
    • Street, City, Province (z. B. Gauteng oder Kurzcode GP), ZIP (Postleitzahl), Country (ZA), Phone

💡 Province-Feld: TCG akzeptiert sowohl den vollen Namen (Gauteng) als auch den Kurzcode (GP).

7. Versandpakete

TCG erwartet Paketmaße in cm und Gewicht in kg. Nevuto liest diese Daten in folgender Reihenfolge:

  1. Variant LWH — sofern in der Produktvariante hinterlegt (genaueste Quelle)
  2. ShippingPackage-Referenz
  3. Standardpaket des Shops
  4. Letzter Ausweg: 20×20×20 cm + 0,5 kg Fallback

Schritte:

  1. Gehe zu Settings → Shipping → Packages.
  2. Add package → Name, Typ, L/W/H/Einheit, Gewicht.
  3. Set as default.

8. Variant LWH

Trage in jeder Variante echte Maße + Gewicht ein (TCG-Tarife reagieren auf das Volumengewicht):

  1. Products → Produkt bearbeiten → Variants.
  2. Length / Width / Height / Weight.
  3. Einheit: cm, Gewicht: g/kg.

9. Customs declaration (international)

TCG verschickt derzeit nur innerhalb ZA. Für internationale Sendungen nutze diese Integration nicht — wähle einen anderen Provider wie Shippo oder EasyPost.

10. Eine Bestellung versenden

Sobald der Kunde gezahlt hat, taucht die Bestellung im Admin mit dem Button "Mark as shipped" auf.

  1. Öffne die Detailseite der Bestellung.
  2. Klicke auf Mark as shipped.
  3. Wähle im Modal The Courier Guy als Provider und klicke auf Submit.
  4. Nach wenigen Sekunden erscheinen in der Bestellzeile eine TCG-Tracking-Nummer (z. B. S7GL...), ein Tracking-Link und der Button "Print label".
  5. Klicke auf Print label, öffne das Waybill-PDF, drucke es und klebe es aufs Paket.
  6. Übergib das Paket einem TCG-Kurier oder gib es an einer TCG-Drop-off-Stelle ab.

💡 Über den Tracking-Link verfolgt der Kunde die Sendung in seiner Bestellseite und erhält automatisch E-Mail-Benachrichtigungen bei Statusänderungen.

11. Status lifecycle

Mark as shipped
    │
    ▼
[shipping_status: PROCESSING]      ← Etikett gedruckt, Carrier hat noch nicht abgeholt
    │
    ▼   "collected" → Carrier hat das Paket abgeholt
[shipping_status: SHIPPED]         ← Webhook
    │
    ▼   "in-transit", "at-hub", "out-for-delivery" — unterwegs
    │
    ▼   "delivered" → beim Kunden
[shipping_status: DELIVERED]       ← Webhook

TCG-Status-Mapping (Nevuto):

  • Vor Abholung: submitted, collection-assigned, awaiting-dropoff → keine Änderung
  • In transit: collected, at-hub, manifested, ready-for-dispatch, in-transit, at-destination-hub, delivery-assigned, out-for-delivery, returned-to-hub → Shipped
  • Zustellung: delivered, ready-for-pickup → Delivered
  • Fehlgeschlagene Zustellung: cancelled, undeliverable, returned-to-sender sowie Ausnahmezustände → werden ignoriert

12. Label-Download

Per Klick auf Print label öffnet sich das Etiketten-PDF in einem neuen Tab. Wenn du ein Aufkleber-Etikett brauchst, kannst du es alternativ aus dem TCG-Portal herunterladen.

13. Testmodus

Wir empfehlen, mit der Sandbox zu starten:

  1. Öffne sandbox.shiplogic.com → registriere dich und hole dir einen API-Key.
  2. Schalte in Nevuto Test mode AN, füge den Sandbox-Key ein und klicke auf Submit.
  3. Testsendungen:
    • Du erhältst eine Tracking-Nummer
    • Es wird ein Label-PDF erzeugt (als Test gekennzeichnet)
    • Keine echte Kurierbewegung — die Testumgebung simuliert das
    • Test-Webhooks werden ausgelöst (sofern du Tracking event abonniert hast)
  4. Vor dem Live-Gang Test mode ausschalten und den Live-API-Key eintragen.

14. Häufige Probleme

A. Tracking-Nummer kommt, aber der Status aktualisiert sich nicht

  • Prüfe TCG-Portal → Webhook subscriptions. Ist die Nevuto-Webhook-URL für das Topic Tracking event registriert? Ohne diesen Eintrag erreichen Statusupdates Nevuto nie (siehe Abschnitt 4).

B. Fehler "401 Unauthorized"

  • Möglicherweise verwendest du einen Sandbox-Key gegen die Live-Umgebung (oder umgekehrt). Stelle den Test mode-Schalter passend ein.

C. Service level "OVN" wird abgelehnt

  • Auf deinem TCG-Konto ist OVN nicht aktiv. Prüfe TCG-Portal → Account → Services. ECO ist auf jedem Konto standardmäßig verfügbar.

D. Paketmaße werden als 20×20×20 angezeigt

  • In der Produktvariante sind keine Maße hinterlegt; Nevuto fällt auf den Default zurück. Trage LWH in den Varianten ein, damit die Tarifrechnung korrekt ist.

E. Bundesland-Name wird abgelehnt

  • TCG akzeptiert sowohl Gauteng als auch GP. Wird er abgelehnt, ist meist ein Tippfehler im Province-Feld die Ursache.

F. Provider erscheint nicht in der Liste

  • Wenn deine Shop-Währung nicht ZAR ist, siehst du "Not available in your store currency". Anpassen unter Settings → General → Currency.
  • Wenn das Land deiner Shop-Adresse nicht ZA ist, siehst du "Doesn't ship from your shop location".

G. Nach dem Live-Gang funktionieren die Webhooks nicht

  • Sandbox- und Live-Konto verwenden getrennte Webhook-Registrierungen. Lege das Webhook-Abo im Live-TCG-Portal erneut an.

15. Nächste Schritte

  • Mache einen End-to-End-Test in der Sandbox — Order anlegen → Fulfillment → Label-Download → simulierter Tracking-Webhook
  • Nach dem Live-Gang beobachte in der ersten Woche die Konsistenz zwischen TCG-Portal und Nevuto
  • Lege OVN/SDX-Service-Levels als Flat-Rate-Shipping-Rules für gezielte Kundensegmente an

Hilfe

Verwandte Artikel