API-Referenz

Shipman API

Aufträge aus dem eigenen Shop oder ERP direkt an das Lager übergeben, Bestände abfragen und Tracking samt Zustellnachweisen zurückholen - über eine schlichte REST-API mit JSON.

https://shipman-api.de

Einstieg

Jede Anfrage geht an die Basis-URL der gewählten Umgebung. Zuerst mit den Zugangsdaten des API-Benutzers über POST /auth ein Token holen, danach jede Anfrage mit dem Header Authorization: Bearer und dem Token senden. Zugangsdaten für die Produktion vergibt euer Ansprechpartner bei Redstone IT.

Schnellstart

curl -X POST "https://shipman-api.de/auth" \  -H "Content-Type: application/json" \  -d '{ "username": "username123", "password": "pwd123" }'curl "https://shipman-api.de/products/stock?pageSize=50" \  -H "Authorization: Bearer <access_token>"

Konventionen

Anfragen und Antworten sind JSON (Content-Type: application/json), Feldnamen in snake_case.
Datumswerte werden als ISO 8601 in UTC übergeben, z. B. 2026-10-14T08:15:00.000Z.
Listen sind paginiert über page und pageSize. Die Gesamtzahl der Treffer steht im Antwort-Header totalCount, nicht im Body.
Filter als filter=feld=wert (Operatoren !=, >, >=, <, <=, , für ODER), Sortierung über sort=-created_at, Feldauswahl über select=name,price.

Fehler

Fehler kommen mit passendem HTTP-Status und einem JSON-Body. Die lesbare Meldung steht in exception.message - bei Validierungsfehlern alle Meldungen mit ; getrennt.

400: Ungültige Anfrage, z. B. Validierungsfehler oder doppelte Auftragsnummer
401: Token fehlt, ist abgelaufen oder die Zugangsdaten sind falsch
403: Aktion im aktuellen Zustand nicht erlaubt, z. B. Storno nach Bearbeitungsbeginn
404: Ressource existiert nicht oder gehört einem anderen Kunden
500: Unerwarteter Serverfehler - bitte mit Zeitstempel melden

Beispiel 400

{  "statusCode": 400,  "timestamp": "2026-10-14T08:15:00.000Z",  "exception": {    "response": "name must be longer than or equal to 2 characters; amount must be a number",    "status": 400,    "message": "name must be longer than or equal to 2 characters; amount must be a number"  }}

Sandbox

Die Sandbox ist eine öffentliche Testumgebung unter dem Präfix /sandbox. Routen, Nutzdaten und Fehlermeldungen entsprechen der Produktion, die Daten sind erfunden und es wird nichts gespeichert: POST /sandbox/orders validiert vollständig und gibt den Auftrag zurück, wie er angelegt worden wäre.

Zugang: Benutzer sandbox, Passwort s4ndb0xAPI über POST /sandbox/auth - das Token gilt 12 Stunden.
Limit: 5 Anfragen pro Sekunde je IP.
Beispielaufträge heißen SBX-1000 bis SBX-1059, Artikelnummern beginnen bei 303-4400-SB (als alias:303-4400-SB bestellbar).

Authentifizierung

Mit Benutzername und Passwort ein Zugriffstoken anfordern. Das Token gilt 2 Tage und wird bei jeder weiteren Anfrage als Authorization: Bearer <token> mitgesendet.

Token anfordern

POST/auth

Meldet einen API-Benutzer an und liefert ein JWT. Bei falschen Zugangsdaten antwortet der Server mit 401.

Request-Body

usernamestringPflicht
Beispiel: username123
passwordstringPflicht
Beispiel: pwd123

Antworten

201Token ausgestellt
401Zugangsdaten falsch

Anfrage

curl -X POST "https://shipman-api.de/auth" \  -H "Content-Type: application/json" \  -d '{  "username": "username123",  "password": "pwd123"}'

Antwort

{  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI2NjI3ZDFm…"}

Produkte

Lesender Zugriff auf die Produkte des eigenen Kunden, wahlweise mit Bestand. Listen sind paginiert - die Gesamtzahl steht in den Antwort-Headern.

Produkte auflisten

GET/productsBearer-Token

Listet die dem eigenen Kunden zugeordneten Produkte. Ohne Bestand - dafür GET /products/stock verwenden.

Query-Parameter

pageinteger
Seite, 1-basiert
Beispiel: 1
pageSizeinteger
Treffer pro Seite
Beispiel: 50
sortstring
Sortierfeld, - kehrt die Richtung um. Mehrere Felder kommagetrennt
Beispiel: -created_at
selectstring
Nur diese Felder zurückgeben, kommagetrennt
Beispiel: name,price,dimensions
searchstring
Freitextsuche über die durchsuchbaren Felder
Beispiel: vorlage
filterstring
Feldfilter feld=wert, mehrere Filter als eigene Parameter. Operatoren: !=, >, >=, <, <=, , für ODER
Beispiel: active=true

Antworten

200Eine Seite Produkte
Antwort-Header:totalCount Gesamtzahl der Treffer über alle Seitenpage Aktuelle SeitepageSize Anzahl der Treffer auf dieser Seite
401Token fehlt, ist abgelaufen oder ungültig

Anfrage

curl -X GET "https://shipman-api.de/products" \  -H "Authorization: Bearer <token>"

Antwort

[  {    "_id": "6627d1f4a3b21c4e9f0a1b2c",    "active": true,    "name": "Inkontinenzvorlage Maxi",    "always_show_stock": false,    "description": "Aufsaugende Vorlage, Beutel à 20 Stück",    "dimensions": {      "height": 12.5,      "length": 30,      "width": 20,      "weight": 1.2    },    "price": {      "amount_net": 19.99,      "amount_vat": 3.8,      "amount_total": 23.79,      "currency": "EUR"    },    "tags": [      "hygiene",      "bestseller"    ],    "flyer": false,    "ignore": false,    "aliases": [      "303-4402-IV",      "4055500123456"    ],    "manufacturer": "6627d1f4a3b21c4e9f0a1b30",    "created_at": "2026-04-23T09:02:00.000Z",    "updated_at": "2026-06-01T14:31:10.000Z"  }]

Produkte per Volltextsuche finden

GET/products/searchBearer-Token

Durchsucht Name, Beschreibung, Aliase und Scancodes. Es werden ausschließlich Produkte des eigenen Kunden zurückgegeben.

Query-Parameter

textSearchstringPflicht
Suchbegriff
Beispiel: vorlage
pageinteger
Seite, 1-basiert
Beispiel: 1
pageSizeinteger
Treffer pro Seite
Beispiel: 50
sortstring
Sortierfeld, - kehrt die Richtung um. Mehrere Felder kommagetrennt
Beispiel: -created_at
selectstring
Nur diese Felder zurückgeben, kommagetrennt
Beispiel: name,price,dimensions
searchstring
Freitextsuche über die durchsuchbaren Felder
Beispiel: vorlage
filterstring
Feldfilter feld=wert, mehrere Filter als eigene Parameter. Operatoren: !=, >, >=, <, <=, , für ODER
Beispiel: active=true

Antworten

200Treffer
Antwort-Header:totalCount Gesamtzahl der Treffer über alle Seitenpage Aktuelle SeitepageSize Anzahl der Treffer auf dieser Seite
401Token fehlt, ist abgelaufen oder ungültig

Anfrage

curl -X GET "https://shipman-api.de/products/search?textSearch=vorlage" \  -H "Authorization: Bearer <token>"

Antwort

[  {    "_id": "6627d1f4a3b21c4e9f0a1b2c",    "active": true,    "name": "Inkontinenzvorlage Maxi",    "always_show_stock": false,    "description": "Aufsaugende Vorlage, Beutel à 20 Stück",    "dimensions": {      "height": 12.5,      "length": 30,      "width": 20,      "weight": 1.2    },    "price": {      "amount_net": 19.99,      "amount_vat": 3.8,      "amount_total": 23.79,      "currency": "EUR"    },    "tags": [      "hygiene",      "bestseller"    ],    "flyer": false,    "ignore": false,    "aliases": [      "303-4402-IV",      "4055500123456"    ],    "manufacturer": "6627d1f4a3b21c4e9f0a1b30",    "created_at": "2026-04-23T09:02:00.000Z",    "updated_at": "2026-06-01T14:31:10.000Z"  }]

Produkte mit Bestand auflisten

GET/products/stockBearer-Token

Wie GET /products, zusätzlich mit stock und charge_numbers. Bei Produkten, die mehreren Kunden zugeordnet sind, entfällt stock, sofern always_show_stock nicht gesetzt ist.

Query-Parameter

pageinteger
Seite, 1-basiert
Beispiel: 1
pageSizeinteger
Treffer pro Seite
Beispiel: 50
sortstring
Sortierfeld, - kehrt die Richtung um. Mehrere Felder kommagetrennt
Beispiel: -created_at
selectstring
Nur diese Felder zurückgeben, kommagetrennt
Beispiel: name,price,dimensions
searchstring
Freitextsuche über die durchsuchbaren Felder
Beispiel: vorlage
filterstring
Feldfilter feld=wert, mehrere Filter als eigene Parameter. Operatoren: !=, >, >=, <, <=, , für ODER
Beispiel: active=true

Antworten

200Eine Seite Produkte mit Bestand
Antwort-Header:totalCount Gesamtzahl der Treffer über alle Seitenpage Aktuelle SeitepageSize Anzahl der Treffer auf dieser Seite
401Token fehlt, ist abgelaufen oder ungültig

Anfrage

curl -X GET "https://shipman-api.de/products/stock" \  -H "Authorization: Bearer <token>"

Antwort

[  {    "_id": "6627d1f4a3b21c4e9f0a1b2c",    "active": true,    "name": "Inkontinenzvorlage Maxi",    "always_show_stock": false,    "description": "Aufsaugende Vorlage, Beutel à 20 Stück",    "dimensions": {      "height": 12.5,      "length": 30,      "width": 20,      "weight": 1.2    },    "price": {      "amount_net": 19.99,      "amount_vat": 3.8,      "amount_total": 23.79,      "currency": "EUR"    },    "tags": [      "hygiene",      "bestseller"    ],    "flyer": false,    "ignore": false,    "aliases": [      "303-4402-IV",      "4055500123456"    ],    "manufacturer": "6627d1f4a3b21c4e9f0a1b30",    "created_at": "2026-04-23T09:02:00.000Z",    "updated_at": "2026-06-01T14:31:10.000Z",    "stock": 148,    "charge_numbers": [      "CH-2026-118"    ]  }]

Einzelnes Produkt abrufen

GET/products/{ID}Bearer-Token

Liefert ein Produkt anhand seiner ID. Produkte fremder Kunden werden mit 404 beantwortet.

Pfad-Parameter

IDstringPflicht
Produkt-ID
Beispiel: 6627d1f4a3b21c4e9f0a1b2c

Antworten

200Das Produkt
401Token fehlt, ist abgelaufen oder ungültig
404Produkt existiert nicht oder gehört einem anderen Kunden

Anfrage

curl -X GET "https://shipman-api.de/products/6627d1f4a3b21c4e9f0a1b2c" \  -H "Authorization: Bearer <token>"

Antwort

{  "_id": "6627d1f4a3b21c4e9f0a1b2c",  "active": true,  "name": "Inkontinenzvorlage Maxi",  "always_show_stock": false,  "description": "Aufsaugende Vorlage, Beutel à 20 Stück",  "dimensions": {    "height": 12.5,    "length": 30,    "width": 20,    "weight": 1.2  },  "price": {    "amount_net": 19.99,    "amount_vat": 3.8,    "amount_total": 23.79,    "currency": "EUR"  },  "tags": [    "hygiene",    "bestseller"  ],  "flyer": false,  "ignore": false,  "aliases": [    "303-4402-IV",    "4055500123456"  ],  "manufacturer": "6627d1f4a3b21c4e9f0a1b30",  "created_at": "2026-04-23T09:02:00.000Z",  "updated_at": "2026-06-01T14:31:10.000Z"}

Bestand eines Produkts abrufen

GET/products/{ID}/stockBearer-Token

Liefert ein einzelnes Produkt inklusive stock und charge_numbers.

Pfad-Parameter

IDstringPflicht
Produkt-ID
Beispiel: 6627d1f4a3b21c4e9f0a1b2c

Antworten

200Das Produkt mit Bestand
401Token fehlt, ist abgelaufen oder ungültig
404Produkt existiert nicht oder gehört einem anderen Kunden

Anfrage

curl -X GET "https://shipman-api.de/products/6627d1f4a3b21c4e9f0a1b2c/stock" \  -H "Authorization: Bearer <token>"

Antwort

{  "_id": "6627d1f4a3b21c4e9f0a1b2c",  "active": true,  "name": "Inkontinenzvorlage Maxi",  "always_show_stock": false,  "description": "Aufsaugende Vorlage, Beutel à 20 Stück",  "dimensions": {    "height": 12.5,    "length": 30,    "width": 20,    "weight": 1.2  },  "price": {    "amount_net": 19.99,    "amount_vat": 3.8,    "amount_total": 23.79,    "currency": "EUR"  },  "tags": [    "hygiene",    "bestseller"  ],  "flyer": false,  "ignore": false,  "aliases": [    "303-4402-IV",    "4055500123456"  ],  "manufacturer": "6627d1f4a3b21c4e9f0a1b30",  "created_at": "2026-04-23T09:02:00.000Z",  "updated_at": "2026-06-01T14:31:10.000Z",  "stock": 148,  "charge_numbers": [    "CH-2026-118"  ]}

Aufträge

Aufträge anlegen und stornieren, Sendungsverfolgung und Zustellnachweise abrufen. Aufträge lassen sich über Auftragsnummer, Auftrags-ID oder externe ID ansprechen.

Auftrag anlegen

POST/ordersBearer-Token

Legt einen Auftrag für den eigenen Kunden an. Kunde und Lager werden aus dem API-Benutzer übernommen und müssen nicht mitgesendet werden. name muss je Kunde eindeutig sein - ein Duplikat wird mit 400 abgelehnt.

Request-Body

namestringPflichtmax. 250 Zeichen
Auftragsnummer, eindeutig je Kunde
Beispiel: 240-4055-ER205
notestringmax. 750 Zeichen
Notiz
Beispiel: Notiz
original_filestring
Ursprungsdatei als base64

Antworten

201Auftrag angelegt
400Validierungsfehler - alle Meldungen mit ; getrennt
401Token fehlt, ist abgelaufen oder ungültig

Anfrage

curl -X POST "https://shipman-api.de/orders" \  -H "Authorization: Bearer <token>" \  -H "Content-Type: application/json" \  -d '{  "name": "240-4055-ER205",  "note": "Bitte vor 12 Uhr zustellen",  "data": {    "id_external": "10366603870800923",    "tags": [      "paid"    ]  },  "delivery": {    "carrier": "dhl",    "service": {      "dhl_service": "standard"    },    "neutral_packaging": false,    "notification": true  },  "price": {    "amount_net": 19.99,    "amount_vat": 3.8,    "amount_total": 23.79,    "currency": "EUR"  },  "delivery_address": {    "name": "Max Mustermann",    "street": "Hauptstraße",    "house_number": "23b",    "postal_code": "12345",    "city": "Berlin",    "country_code": "DE",    "email": "max.mustermann@example.de"  },  "items": [    {      "item": "alias:303-4402-IV",      "amount": 2    },    {      "item": "6627d1f4a3b21c4e9f0a1b2c",      "amount": 1    }  ]}'

Antwort

{  "_id": "66a1f0c2e4b0d93a7c5e1f20",  "status": 1,  "name": "240-4055-ER205",  "note": "Bitte vor 12 Uhr zustellen",  "data": {    "id_external": "10366603870800923",    "tags": [      "paid"    ],    "origin_name": "api"  },  "delivery": {    "carrier": "dhl",    "service": {      "dhl_service": "standard"    },    "neutral_packaging": false,    "notification": true  },  "price": {    "amount_net": 19.99,    "amount_vat": 3.8,    "amount_total": 23.79,    "currency": "EUR"  },  "delivery_address": {    "name": "Max Mustermann",    "street": "Hauptstraße",    "house_number": "23b",    "postal_code": "12345",    "city": "Berlin",    "country_code": "DE",    "email": "max.mustermann@example.de"  },  "items": [    {      "item": "alias:303-4402-IV",      "amount": 2    },    {      "item": "6627d1f4a3b21c4e9f0a1b2c",      "amount": 1    }  ],  "created_at": "2026-10-14T08:15:00.000Z"}

Sendungsverfolgung abrufen

GET/orders/{ID}/trackingBearer-Token

Liefert die Trackingnummern aller versendeten Pakete eines Auftrags und - sobald vorhanden - deren Statushistorie.

Pfad-Parameter

IDstringPflicht
Auftragsname, Auftrags-ID oder externe ID
Beispiel: 240-4055-ER205

Antworten

200Trackingdaten
401Token fehlt, ist abgelaufen oder ungültig
404Auftrag nicht gefunden

Anfrage

curl -X GET "https://shipman-api.de/orders/240-4055-ER205/tracking" \  -H "Authorization: Bearer <token>"

Antwort

{  "carrier": "dhl",  "tracking_numbers": [    "00340434180860993875"  ],  "histories": [    {      "tracking_number": "00340434180860993875",      "tracking_url": "https://nolp.dhl.de/nextt-online-public/set_identcodes.do?lang=de&idc=00340434180860993875",      "tracking_history": [        {          "date": "2026-03-17T16:40:00.000Z",          "name": "Einlieferung",          "text": "Die Sendung wurde abgeholt.",          "place": "Köln",          "code": "PCKDU",          "retoure": false        },        {          "date": "2026-03-18T09:02:00.000Z",          "name": "Zustellung erfolgreich",          "text": "Die Sendung wurde erfolgreich zugestellt.",          "place": "Bonn",          "code": "DLVRD",          "retoure": false        }      ]    }  ]}

Zustellnachweise abrufen

GET/orders/{ID}/signaturesBearer-Token

Liefert die Ablieferbelege aller zugestellten, zurückgesendeten oder nicht zustellbaren Pakete. signature ist base64-kodiert - PDF oder JPEG je nach Kundeneinstellung.

Pfad-Parameter

IDstringPflicht
Auftragsname, Auftrags-ID oder externe ID
Beispiel: 240-4055-ER205

Antworten

200Zustellnachweise
401Token fehlt, ist abgelaufen oder ungültig
404Auftrag nicht gefunden

Anfrage

curl -X GET "https://shipman-api.de/orders/240-4055-ER205/signatures" \  -H "Authorization: Bearer <token>"

Antwort

{  "carrier": "dhl",  "signatures": [    {      "tracking_number": "00340434180860993875",      "tracking_url": "https://nolp.dhl.de/nextt-online-public/set_identcodes.do?lang=de&idc=00340434180860993875",      "shipment_date": "2026-03-17T16:40:00.000Z",      "mimetype": "application/pdf",      "signature": "JVBERi0xLjMKJf////8KNyAwIG9iago8PAovVHlwZSAvUGFnZQ…",      "delivered": true,      "returned": false,      "not_delivered": false,      "tracking_history": [        {          "date": "2026-03-17T16:40:00.000Z",          "name": "Einlieferung",          "text": "Die Sendung wurde abgeholt.",          "place": "Köln",          "code": "PCKDU",          "retoure": false        },        {          "date": "2026-03-18T09:02:00.000Z",          "name": "Zustellung erfolgreich",          "text": "Die Sendung wurde erfolgreich zugestellt.",          "place": "Bonn",          "code": "DLVRD",          "retoure": false        }      ]    }  ]}

Auftrag stornieren

PUT/orders/{ID}/cancelBearer-Token

Storniert einen Auftrag. Über die API ist das nur im Status 1 (Offen) möglich - sobald das Lager mit der Bearbeitung begonnen hat, antwortet der Server mit 403.

Pfad-Parameter

IDstringPflicht
Auftragsname, Auftrags-ID oder externe ID
Beispiel: 240-4055-ER205

Antworten

200Storniert
403Kann nur im Status 1 (Offen) storniert werden
401Token fehlt, ist abgelaufen oder ungültig
404Auftrag nicht gefunden

Anfrage

curl -X PUT "https://shipman-api.de/orders/240-4055-ER205/cancel" \  -H "Authorization: Bearer <token>"

Antwort

{  "message": "Auftrag erfolgreich storniert"}

Einstieg

Konventionen

Fehler

Sandbox

Authentifizierung

Token anfordern

Request-Body

Antworten

Produkte

Produkte auflisten

Query-Parameter

Antworten

Produkte per Volltextsuche finden

Query-Parameter

Antworten

Produkte mit Bestand auflisten

Query-Parameter

Antworten

Einzelnes Produkt abrufen

Pfad-Parameter

Antworten

Bestand eines Produkts abrufen

Pfad-Parameter

Antworten

Aufträge

Auftrag anlegen

Request-Body

dataobjectPflicht4 Felder

deliveryobject7 Felder

priceobject4 Felder

delivery_addressobjectPflicht12 Felder

sender_addressobject12 Felder

itemsobject[]Pflicht2 Felder

Antworten

Sendungsverfolgung abrufen

Pfad-Parameter

Antworten

Zustellnachweise abrufen

Pfad-Parameter

Antworten

Auftrag stornieren

Pfad-Parameter

Antworten