Partner-Schnittstelle

Anleitung (diese Seite)

https://api.nexcargo.at/api/doku

Zum Ausprobieren

https://api.nexcargo.at/api/doku/swagger

Für Ihr Programm (OpenAPI)

https://api.nexcargo.at/api/doku/openapi.json

Die Schnittstelle selbst liegt unter /api/v1/…. Die Version steht im Pfad, damit später eine v2 danebengestellt werden kann, ohne Ihre Anbindung zu brechen.

Jeder Aufruf braucht den Kopf X-Api-Key mit dem Schlüssel, den Ihnen die ATF-Zentrale ausgegeben hat. Der Schlüssel gehört zu genau einem Partner; angelegte Sendungen werden diesem Partner zugeordnet. Sie sehen ausschließlich Ihre eigenen Sendungen.

curl -H "X-Api-Key: IHR_SCHLUESSEL" https://api.nexcargo.at/api/v1/produkte

Kein Schlüssel oder ein gesperrter Schlüssel ergibt 401. Der Schlüssel ist einzeln sperrbar – wenn einer abhandenkommt, sagen Sie bitte sofort Bescheid. Bitte nur über HTTPS benutzen, sobald das System produktiv erreichbar ist.

Jeder Schlüssel hat vier einzeln schaltbare Rechte. Fehlt eines, antwortet die Schnittstelle mit 403 und dem Code RECHT_FEHLT – das ist ausdrücklich etwas anderes als ein ungültiger Schlüssel: Ein neuer Schlüssel hilft dann nicht, die Freischaltung schon.

Recht	Wofür	Schon nutzbar?
Sendungen anlegen	Neue Sendungen über die Schnittstelle und über den CSV-Import anmelden.	ja
Sendungen ändern und stornieren	Bestehende Sendungen ändern und stornieren. Wer ändern darf, kann eine Sendung faktisch auch entwerten.	ja
Status und Label lesen	Sendungsstatus, Scans und Labels abrufen.	ja
Preisauskunft	Preise vorab berechnen lassen. Gibt die Tarife des Partners preis und ist die aufwendigste Abfrage.	ja

Stammdaten, Partnerverzeichnis und Routing-Auskunft brauchen kein besonderes Recht – nur einen gültigen Schlüssel. Das sind Nachschlagedaten, die man braucht, um überhaupt korrekt anlegen zu können.

Zum Anbinden bekommen Sie einen Testschlüssel. Damit können Sie alles – anlegen, Status abfragen, Label drucken, Preise rechnen –, aber:

• Die Sendungen laufen nicht ins Clearing und werden nie abgerechnet.
• Sie tauchen in keiner Arbeitsliste, keiner Tourenplanung und keiner Auswertung auf.
• Ihre Sendungsnummer beginnt mit TEST-.
• Das Etikett trägt quer über die ganze Fläche den Aufdruck TESTSENDUNG.
• Die Antwort führt das Feld test – wer versehentlich mit dem Testschlüssel produktiv geht, merkt es an dieser Zeile und nicht erst an der Rechnung.

Ein Schlüssel ist entweder Test oder Live und lässt sich nicht umschalten – sonst wäre bei keiner Sendung mehr nachvollziehbar, warum sie nicht abgerechnet wurde. Für den Wechsel bekommen Sie einen zweiten Schlüssel.

In der Swagger-Oberfläche können Sie den Testschlüssel oben rechts eintragen und die Aufrufe direkt absetzen.

Der Fall, um den es geht: Sie schicken eine Sendung, die Antwort geht auf dem Rückweg verloren. Sie wissen jetzt nicht, ob die Sendung entstanden ist. Ohne Schutz steht die Ware nach dem zweiten Versuch zweimal im System – zwei Etiketten, zwei Abholungen, zwei Rechnungen.

Setzen Sie deshalb bei der Sendungsanlage den Kopf Idempotency-Key mit einem von Ihnen gewählten Wert (zum Beispiel Ihrer eigenen Auftragsnummer) und benutzen Sie bei der Wiederholung denselben.

• Gleicher Schlüssel, gleicher Inhalt: Sie bekommen die Antwort von damals samt derselben Sendungsnummer – und den Kopf Idempotency-Replayed: true. Es entsteht nichts Neues.
• Gleicher Schlüssel, anderer Inhalt: 409. Für eine andere Sendung bitte einen neuen Wert wählen.
• Der Kopf ist freiwillig – ohne ihn läuft alles wie bisher.
• Gemerkt wird er 24 Stunden lang, höchstens 200 Zeichen.

Die Referenzfelder sind dafür nicht gedacht: Referenz 1 und 2 dürfen mehrfach vorkommen – eine Bestellung geht nun einmal in mehreren Lieferungen raus.

Es gibt ein allgemeines Minutenlimit je Schlüssel und zusätzlich zwei engere: für die Preisauskunft (sie stößt die volle Preisrechnung an) und für den Label-Abruf (er erzeugt ein PDF je Packstück). Alle drei stehen am Schlüssel und lassen sich für Sie hochsetzen – melden Sie sich einfach.

Eine gebremste Antwort ist 429 und trägt den Kopf Retry-After mit der Wartezeit in Sekunden. Bitte danach richten, statt im Sekundentakt weiter anzuklopfen.

Vier Aufrufe, von der Frage nach dem Preis bis zum fertigen Etikett. Ersetzen Sie IHR_SCHLUESSEL durch Ihren Testschlüssel.

Schritt 1 – Was kostet das?

Rechnet nur. Es entsteht nichts, und Sie brauchen hier nur die vier Felder, die den Preis bestimmen: beide Länder und beide Postleitzahlen, dazu mindestens ein Packstück.

curl -X POST https://api.nexcargo.at/api/v1/preisauskunft \
  -H "X-Api-Key: IHR_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -d '{
    "absenderLand": "DE",
    "absenderPlz": "40210",
    "empfaengerLand": "DE",
    "empfaengerPlz": "80331",
    "packstuecke": [
      { "laengeCm": 60, "breiteCm": 40, "hoeheCm": 50, "realgewichtKg": 18 }
    ]
  }'

In der Antwort steht jede Position einzeln mit ihrem Rechenweg. Zwei Felder sind wichtig: preisVerfuegbar sagt, ob überhaupt ein Preis herauskam – vollstaendig sagt, ob alle Anteile gerechnet werden konnten. Die Summe kann plausibel aussehen und trotzdem einen Anteil auf 0,00 enthalten.

Schritt 2 – Sendung anlegen

Derselbe Rumpf wie eben, ergänzt um Name, Straße und Ort. Pflicht sind: absenderName, absenderStrasse, absenderPlz, absenderOrt, empfaengerName, empfaengerStrasse, empfaengerPlz, empfaengerOrt – dazu mindestens ein Packstück. Insgesamt kennt eine Sendung 52 Felder; alle stehen in der OpenAPI-Beschreibung.

curl -X POST https://api.nexcargo.at/api/v1/sendungen \
  -H "X-Api-Key: IHR_SCHLUESSEL" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: mein-auftrag-4711" \
  -d '{
    "absenderName": "Muster GmbH",
    "absenderStrasse": "Musterweg 1",
    "absenderPlz": "40210",
    "absenderOrt": "Düsseldorf",
    "absenderLand": "DE",
    "empfaengerName": "Empfänger AG",
    "empfaengerStrasse": "Zielweg 2",
    "empfaengerPlz": "80331",
    "empfaengerOrt": "München",
    "empfaengerLand": "DE",
    "referenz1": "IHRE-AUFTRAGSNUMMER",
    "produktCode": "ND",
    "packstuecke": [
      { "laengeCm": 60, "breiteCm": 40, "hoeheCm": 50, "realgewichtKg": 18 }
    ]
  }'

Antwort 201. Merken Sie sich daraus die sendungsnummer sowie die fertigen Adressen label und statusUrl – bitte von dort übernehmen, statt sie selbst zusammenzubauen.

Schritt 3 – Status abfragen

curl -H "X-Api-Key: IHR_SCHLUESSEL" \
  https://api.nexcargo.at/api/v1/sendungen/TEST-TST-100-0000123

Es geht auch mit einer Packstücknummer (etwa …-0000123-2) – im Lager liegt oft nur ein Etikett vor. Die Antwort führt neben dem Gesamtstatus jedes Packstück einzeln mit seinen Scans.

Schritt 4 – Etiketten drucken

curl -H "X-Api-Key: IHR_SCHLUESSEL" \
  -o etiketten.pdf \
  https://api.nexcargo.at/api/v1/sendungen/TEST-TST-100-0000123/label

Ein Label je Packstück in einem PDF. Ein einzelnes Etikett zum Nachdruck holen Sie mit /label/1. Der Link ist nicht öffentlich – er verlangt denselben Schlüssel, denn auf dem Etikett stehen Empfängername, Anschrift und Route.

Schritt 5 – Ändern und stornieren

Alle fünf Aufrufe brauchen das Recht Sendungen ändern und stornieren und antworten in derselben Form: die vollständige Sendung in ihrem neuen Stand, der neu berechnete Preis und das Feld labelNeuDrucken.

# Sendungsdaten ändern - nur die Felder, die sich ändern
curl -X PATCH https://api.nexcargo.at/api/v1/sendungen/TEST-TST-100-0000123 \
  -H "X-Api-Key: IHR_SCHLUESSEL" -H "Content-Type: application/json" \
  -d '{ "empfaengerStrasse": "Neuer Weg 7" }'

# Maße oder Gewicht eines Packstücks korrigieren
curl -X PATCH https://api.nexcargo.at/api/v1/sendungen/TEST-TST-100-0000123/packstuecke/1 \
  -H "X-Api-Key: IHR_SCHLUESSEL" -H "Content-Type: application/json" \
  -d '{ "realgewichtKg": 22.5 }'

# Ein weiteres Packstück dazunehmen
curl -X POST https://api.nexcargo.at/api/v1/sendungen/TEST-TST-100-0000123/packstuecke \
  -H "X-Api-Key: IHR_SCHLUESSEL" -H "Content-Type: application/json" \
  -d '{ "laengeCm": 40, "breiteCm": 30, "hoeheCm": 20, "realgewichtKg": 5 }'

# Ein Packstück herausnehmen (das letzte geht nicht - dann bitte stornieren)
curl -X DELETE https://api.nexcargo.at/api/v1/sendungen/TEST-TST-100-0000123/packstuecke/2 \
  -H "X-Api-Key: IHR_SCHLUESSEL"

# Die ganze Sendung stornieren (kein Rumpf nötig)
curl -X POST https://api.nexcargo.at/api/v1/sendungen/TEST-TST-100-0000123/storno \
  -H "X-Api-Key: IHR_SCHLUESSEL"

Steht labelNeuDrucken auf true, bitte die Etiketten neu drucken und die alten vernichten. Die gedruckten Barcodes bleiben scanbar, zeigen aber veraltete Angaben – das ist die Stelle, an der im Lager sonst etwas schiefgeht.

Ein entferntes Packstück wird nicht gelöscht, sondern markiert. Es zählt nirgends mehr mit, aber sein Etikett bleibt gültig: Wird der Barcode doch gescannt, kommt das Packstück automatisch zurück in die Sendung und in die Abrechnung, und der Preis wird neu berechnet. In der Antwort steht es weiter unter packstuecke mit "entfernt": true. Packstücknummern werden nie neu vergeben.

Ist die Sendung schon abgerechnet, wird die Rechnung nicht geändert. Stattdessen entsteht eine Nachberechnung – oder, wenn es günstiger wird, eine Gutschrift – über den Unterschiedsbetrag, die auf der nächsten Rechnung steht und dort Sendung und Ursprungsbeleg nennt. Ein Storno nach der Abrechnung läuft genauso: Gutschrift in voller Höhe. In der Antwort steht das dann unter hinweise; der Wert unter preis ist der neue Gesamtpreis der Sendung, nicht der Betrag der kommenden Rechnung.

Jede dieser Aktionen hat eine zeitliche Grenze, die die ATF-Zentrale je Scan-Typ einstellt – für alle Partner gleich. Zu spät heißt 409 mit dem Code AENDERUNG_ZU_SPAET; der Text nennt den Scan mit Zeitpunkt. Fest und unabhängig davon gilt: Nach der Zustellung ist Schluss. Ein reiner Informations-Scan zählt nie als Grenze.

Jede Fehlerantwort hat dieselbe Form: ein deutscher Text für den Menschen und ein Kürzel für Ihr Programm.

{ "fehler": "Pflichtfelder fehlen: empfaengerName", "code": "PFLICHTFELD_FEHLT" }

Der Text darf sich jederzeit ändern, das Kürzel nie. Ein einmal veröffentlichtes Kürzel wird weder umbenannt noch wiederverwendet – Sie dürfen Ihre Logik darauf stützen.

Code	Bedeutung
SCHLUESSEL_UNGUELTIG	Der Kopf X-Api-Key fehlt, der Schlüssel ist unbekannt oder er wurde gesperrt.
RATE_LIMIT_ERREICHT	Das Minutenlimit dieses Schlüssels ist erreicht. Der Kopf "Retry-After" nennt die Wartezeit in Sekunden.
IP_LIMIT_ERREICHT	Das Minutenlimit dieser Absender-Adresse ist erreicht. Auch hier sagt "Retry-After", wie lange.
JSON_UNGUELTIG	Der Rumpf der Anfrage ist kein gültiges JSON-Objekt.
PFLICHTFELD_FEHLT	Mindestens ein Pflichtfeld fehlt oder ist leer. Welche, steht im Text.
FELD_UNGUELTIG	Ein Feld hat das falsche Format – etwa ein Datum, das nicht JJJJ-MM-TT ist.
PACKSTUECK_FEHLT	Die Sendung hat kein einziges Packstück.
PACKSTUECK_UNGUELTIG	Ein Packstück hat fehlende oder unsinnige Maße bzw. Gewichte (alle vier Zahlen müssen größer als 0 sein).
PRODUKT_UNBEKANNT	Die angegebene Sendungsart gibt es nicht oder sie ist abgeschaltet. Die gültigen Codes liefert GET /api/v1/produkte.
ROUTING_NICHT_MOEGLICH	Die Sendungsart wird an dieser Zustelladresse nicht angeboten. GET /api/v1/routing sagt, wer die Adresse bedient.
TARIF_FEHLT	Für diese Strecke und Sendungsart ist kein Preis hinterlegt.
SENDUNG_UNGUELTIG	Eine Angabe verstößt gegen eine Regel der Sendung selbst – etwa eine Abstellgenehmigung ohne Abstellort.
SENDUNGSNUMMER_KONFLIKT	Die vergebene Sendungsnummer war belegt. Einfach denselben Aufruf noch einmal senden.
IDEMPOTENZ_KONFLIKT	Derselbe Idempotency-Key wurde bereits mit einem anderen Inhalt benutzt. Für eine andere Sendung bitte einen neuen Schlüssel wählen.
IDEMPOTENZ_LAEUFT_NOCH	Ein Aufruf mit demselben Idempotency-Key wird gerade verarbeitet. Kurz warten, dann wiederholen.
IDEMPOTENZ_SCHLUESSEL_ZU_LANG	Der Idempotency-Key ist länger als 200 Zeichen. Er wird bewusst nicht gekürzt, sonst würden zwei verschiedene Schlüssel still zu einem.
SENDUNG_NICHT_GEFUNDEN	Zu dieser Nummer gibt es keine Sendung – oder sie gehört einem anderen Partner. Beides sieht absichtlich gleich aus.
PACKSTUECK_NICHT_GEFUNDEN	Das Packstück gibt es in dieser Sendung nicht, oder die Sendung hat überhaupt keines.
PARTNER_NICHT_GEFUNDEN	Zu diesem Kürzel gibt es keinen aktiven Partner.
PARAMETER_FEHLT	Ein Pflichtangabe in der Adresszeile fehlt oder ist unbrauchbar – etwa Land oder PLZ bei der Routing-Abfrage.
RECHT_FEHLT	Der Schlüssel ist gültig, hat aber das nötige Recht nicht. Bitte bei der ATF-Zentrale freischalten lassen – ein neuer Schlüssel hilft hier nicht.
PREIS_NICHT_BERECHENBAR	Die Preisrechnung selbst ist gescheitert. Das ist kein Fehler Ihres Aufrufs, sondern ein Loch in unseren Preisstammdaten – bitte bei der ATF melden.
AENDERUNG_ZU_SPAET	Die Sendung ist zu weit für diese Änderung. Der Text nennt den Scan, der die Grenze gesetzt hat, mit Zeitpunkt. Ein anderes Recht hilft hier nicht.
LETZTES_PACKSTUECK	Das letzte Packstück einer Sendung lässt sich nicht entfernen. Wer die Sendung loswerden will, storniert sie.
BEREITS_STORNIERT	Die Sendung ist bereits storniert.

• Der alte Pfad bleibt. Wer noch gegen /api/sendungen anbindet, wird mit 308 auf /api/v1/sendungen umgeleitet – Methode und Rumpf bleiben dabei erhalten. Neue Anbindungen bitte gleich auf v1.
• Sendungs- und Stationsnummern dürfen Schrägstriche enthalten (etwa CAM/ANS). Sie werden ganz normal in die Adresse geschrieben, ohne Kodierung.
• Ein Aufruf, eine Sendung. Eine Massenanlage mehrerer Sendungen in einem Aufruf gibt es bewusst nicht – für Stapel gibt es den CSV-Import unter /import/csv.