Partner-Schnittstelle

Anleitung (diese Seite)

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

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 5 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
Belege lesen	Eigene Rechnungen und Gutschriften abrufen – Liste, Positionen und PDF. Finanzdaten, deshalb standardmäßig aus.	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.

Den Testschlüssel setzen Sie einfach in die Beispiele auf dieser Seite ein – jeder Aufruf hier ist eine vollständige Zeile zum Kopieren.

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 drei engere: für die Preisauskunft (sie stößt die volle Preisrechnung an), für den Label-Abruf (er erzeugt ein PDF je Packstück) und für die Belege (Liste, Einzelbeleg und PDF teilen sich ein Limit). Alle vier 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.

Drei Aufrufe: die Liste, ein einzelner Beleg mit allen Positionen und das PDF. Alle drei brauchen das Recht Belege lesen. Es ist bei neuen Schlüsseln nicht vorausgewählt – es sind Finanzdaten, deshalb schaltet die ATF-Zentrale es auf Wunsch frei.

Gemeint sind die Belege, die die ATF Ihnen stellt – also Rechnungen der ATF an Sie und Gutschriften der ATF an Sie. Rechnungen, die Sie der ATF stellen, gibt es hier nicht: Beim Abrechnungsweg „Partnerrechnung“ schreiben Sie das Papier, nicht wir. Und Rechnungen, die Sie Ihren eigenen Kunden stellen, fasst diese Schnittstelle ebenfalls nicht an.

Schritt 1 – Die Liste

# Ohne Zeitangabe: die letzten 12 Monate, neueste zuerst
curl -H "X-Api-Key: IHR_SCHLUESSEL" \
  "https://api.nexcargo.at/api/v1/belege"

# Mit Zeitraum, Filter und Summenblock
curl -H "X-Api-Key: IHR_SCHLUESSEL" \
  "https://api.nexcargo.at/api/v1/belege?von=2026-01-01&bis=2026-08-31&art=rechnung&summe=1"

Filtern können Sie nach von und bis (Belegdatum, JJJJ-MM-TT), art (rechnung oder gutschrift) und status (festgeschrieben oder storniert). Geblättert wird mit seite und proSeite (höchstens 200, Vorgabe 50); der Block seite in der Antwort nennt die Gesamtzahl. Ein unbrauchbarer Wert ist 422 mit PARAMETER_UNGUELTIG – er wird nie stillschweigend zurechtgebogen.

Stornierte Belege sind in der Liste enthalten – sie gehören zu Ihrer Buchhaltung. Im Block summe zählen sie nicht mit. Entwürfe erscheinen nie: Ein Beleg, der noch nicht festgeschrieben ist, verhält sich hier wie ein Beleg, den es nicht gibt.

Alle Beträge sind Zeichenketten, nicht Zahlen – "netto": "1234.56". Auf dem Weg durch manche JSON-Bibliothek verliert eine Fließkommazahl Cent-Genauigkeit, und bei Geld ist das keine Kleinigkeit. Bitte als Dezimalzahl einlesen, nicht als Gleitkommazahl. steuersatzProzent: "0.00" bedeutet Reverse Charge.

Schritt 2 – Ein Beleg mit allen Positionen

curl -H "X-Api-Key: IHR_SCHLUESSEL" \
  https://api.nexcargo.at/api/v1/belege/RE-2026-000123

Dazu kommen die beim Ausstellen eingefrorenen Empfängerangaben – also Name, Anschrift und UID so, wie sie damals auf dem Papier standen, auch wenn sich Ihre Stammdaten seither geändert haben. Eine Rechnung, die sich rückwirkend ändert, wäre keine.

Jede Position nennt bezeichnung, leistungsdatum, betrag und, soweit vorhanden, sendungsnummer, liniennummer und gewichtKg. Zur Sendungsnummer gibt es bewusst keinen Link: Auf Ihrer Rechnung stehen Sendungen, deren Auftraggeber ein anderer Partner ist – ein Link liefe gegen dessen Zugriffsgrenze und ginge zuverlässig ins Leere.

Der Rechenweg (grundlage) ist Freitext – genau der Satz, der auch auf dem PDF steht. Eine maschinenlesbare Kalkulation mit einzeln abrufbaren Zwischenschritten gibt es im System nicht; wir liefern lieber den echten Satz als eine erfundene Struktur. Auf Vergütungspositionen enthält er auch den Preisanteil, den ein anderer Partner für denselben Zuschlag zahlt – das steht heute schon so auf Ihrer Rechnung, und wir kürzen es hier nicht stillschweigend.

nachtragZu nennt bei einer Nachberechnung die Belegnummer des Vorbelegs. Das ist eine eingefrorene Textangabe, kein garantierter Verweis: Nach einem Storno steht dort null, während im archivierten PDF weiterhin der Bezug zu lesen ist. Wenn es für Sie zählt, gilt das Dokument.

Schritt 3 – Das PDF

curl -H "X-Api-Key: IHR_SCHLUESSEL" \
  -o rechnung.pdf \
  https://api.nexcargo.at/api/v1/belege/RE-2026-000123/pdf

Sie bekommen das beim Festschreiben archivierte Original, Byte für Byte dasselbe Dokument wie im Partner-Portal. Es wird nie neu gezeichnet: Gibt es keine Archivdatei – das betrifft Belege aus der Zeit vor der Archivierung – oder stimmt deren Prüfsumme nicht mehr, antworten wir mit 409 und BELEG_PDF_NICHT_VERFUEGBAR statt mit einem Ersatzdokument. Ein Buchhaltungsbeleg ist entweder das Original, oder er ist nicht verfügbar. Die Belegdaten selbst bleiben in diesem Fall über Schritt 2 abrufbar.

Jeder Beleg trägt seine Adressen gleich mit: unter links.selbst und links.pdf – bitte von dort übernehmen, statt sie selbst zusammenzubauen. Der PDF-Link steht auf jedem Beleg; ob dahinter ein archiviertes Dokument liegt, sagt erst der Abruf.

Einen Beleg, den es nicht gibt, der einem anderen Partner gehört oder der noch nicht festgeschrieben ist, beantworten alle drei Aufrufe gleich: 404 mit BELEG_NICHT_GEFUNDEN und wortgleichem Text. Das ist Absicht – ein anderer Text wäre schon die Auskunft, dass es diesen Beleg gibt.

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.
BELEG_NICHT_GEFUNDEN	Zu dieser Nummer gibt es keinen Beleg – oder er gehört einem anderen Partner oder ist noch nicht festgeschrieben. Alle drei sehen absichtlich gleich aus.
PARAMETER_UNGUELTIG	Ein Filterwert in der Adresszeile ist unbrauchbar – etwa ein Datum, das nicht JJJJ-MM-TT ist, oder eine Seitengröße über 200. Welcher, steht im Text.
BELEG_PDF_NICHT_VERFUEGBAR	Den Beleg gibt es, sein PDF lässt sich aber nicht ausliefern (Archivdatei fehlt oder Prüfsumme stimmt nicht). Ein Wiederholen hilft nicht – bitte bei der ATF melden.
ENDPUNKT_UNBEKANNT	Diese Adresse gibt es an der Schnittstelle nicht – meist ein Tippfehler im Pfad. Die gültigen Adressen stehen unter /api/doku.
METHODE_NICHT_ERLAUBT	Die Adresse gibt es, aber nicht mit diesem HTTP-Verfahren. Welche erlaubt sind, nennt der Kopf "Allow" der Antwort.
ANFRAGE_ABGEWIESEN	Die Anfrage wurde abgewiesen, bevor ein Endpunkt sie beurteilen konnte – etwa weil der Rumpf unbrauchbar oder eine hochgeladene Datei zu groß war.
INTERNER_FEHLER	Ein unerwarteter Fehler auf unserer Seite. Der Aufruf darf wiederholt werden; bleibt es dabei, bitte bei der ATF melden – dort steht die Einzelheit im Protokoll.

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