Aufträge

Transportaufträge anlegen, abfragen, stornieren — und die manipulationssichere Event-Historie lesen.

Alle Pfade relativ zur Basis-URL (…/api/partner/v1). Die vollständigen Feldlisten mit Typen und Beispielen stehen in der API-Referenz.

Endpoint	Zweck	Scope
`POST /orders`	Auftrag anlegen	`orders:write`
`GET /orders`	Aufträge auflisten (Cursor-Pagination, Filter)	`orders:read`
`GET /orders/{id}`	Auftragsdetail	`orders:read`
`POST /orders/{id}/cancel`	Auftrag stornieren	`orders:write`
`GET /orders/{id}/events`	Event-Historie (Chain of Custody)	`orders:read`
`GET /locations`, `POST /locations`	Standorte der Organisation lesen/anlegen	`orders:read` / `orders:write`

Auftrag anlegen

POST /orders. Abhol- und Zustellort (pickup, dropoff) geben Sie jeweils in einer von drei Formen an:

Form	Feld	Verhalten
Bestehender Standort	`location_id`	referenziert einen Standort Ihrer Organisation (siehe `GET /locations`)
Strukturierte Adresse	`address`	wird serverseitig geocodiert und als Standort Ihrer Organisation angelegt bzw. wiederverwendet
Freitext-Adresse	`address_text`	wie `address`, aber als eine Zeile Freitext

Kann eine Adresse nicht aufgelöst werden, antwortet die API mit 422 und dem Fehler-Code ADDRESS_NOT_RESOLVED — der Auftrag wird dann nicht angelegt. Prüfen Sie die Adresse und senden Sie erneut.

external_id (empfohlen): Ihre eigene Referenz (z. B. Bestell- oder Rezeptnummer, max. 100 Zeichen). Sie ist pro Organisation eindeutig, erscheint in Webhook-Payloads und ist als Filter in GET /orders nutzbar — damit verknüpfen Sie Hemostat-Aufträge robust mit Ihrem System.

Weitere Felder (SLA, Zeitfenster, Notizen, Positionen mit Warentyp) entnehmen Sie der API-Referenz.

Idempotenz

Übermitteln Sie bei POST /orders den Header Idempotency-Key mit einem von Ihnen erzeugten eindeutigen Wert (z. B. UUID). Damit sind Retries — etwa nach Timeout — gefahrlos:

Gleicher Key, gleicher Request-Body: Die API führt den Auftrag nicht erneut aus, sondern liefert die gespeicherte ursprüngliche Antwort zurück, gekennzeichnet mit dem Response-Header Idempotency-Replayed: true.
Gleicher Key, anderer Request-Body: 409 — der Key wurde bereits mit anderem Inhalt verwendet. Erzeugen Sie für einen neuen Auftrag einen neuen Key.

Idempotency-Keys werden zeitlich begrenzt vorgehalten (Größenordnung ein Tag); für langfristige Dublettenvermeidung nutzen Sie zusätzlich external_id.

Auflisten, Pagination, Filter

GET /orders liefert Seiten in stabiler Reihenfolge über Cursor-Pagination: Jede Antwort enthält einen Cursor, den Sie für die nächste Seite übergeben; limit ist auf 100 begrenzt. Verlassen Sie sich nicht auf Seitenzahlen — Cursor bleiben auch bei parallel entstehenden Aufträgen konsistent.

Filter:

Parameter	Wirkung
`status`	nur Aufträge in diesem Status
`external_id`	Auftrag zu Ihrer Referenz finden
`updated_since`	nur seitdem geänderte Aufträge (für Abgleich-Läufe)

Für laufende Statusverfolgung sind Webhooks das vorgesehene Mittel; Polling mit updated_since eignet sich als Abgleich- und Nachhol-Mechanismus.

Event-Historie

GET /orders/{id}/events liefert die Chain-of-Custody-Historie des Auftrags als Auszug aus dem hashverketteten Event-Log der Plattform: wer wann welchen Schritt dokumentiert hat — von der Beauftragung über Abholung und Siegel-Scan bis zur Zustellung. Dieselbe Datenbasis speist das revisionssichere Transportprotokoll.

Die Feldstruktur der Events entnehmen Sie der API-Referenz.

Stornieren

POST /orders/{id}/cancel storniert einen Auftrag, solange die Übernahme in die Gewahrsamskette noch nicht begonnen hat — es gelten dieselben Regeln wie in der Hemostat-Plattform. Danach ist eine Stornierung über die API nicht mehr möglich; wenden Sie sich in dem Fall an die Disposition.

Fehlerformat

Alle Fehler haben denselben Envelope:

{
  "error": {
    "code": "ADDRESS_NOT_RESOLVED",
    "message": "Die Zustelladresse konnte nicht aufgelöst werden.",
    "details": {
      "field": "dropoff.address_text"
    }
  }
}

code: stabiler, maschinenlesbarer Code — darauf sollte Ihre Fehlerbehandlung reagieren.
message: menschenlesbare Beschreibung; Wortlaut kann sich ändern.
details: optionale Zusatzinformationen, Struktur je nach Fehler.

Die je Endpoint möglichen Codes listet die API-Referenz.