Lieferungsfelder und Multi-Stop-Payloads

Eine Lieferung wird aus einem zuvor kalkulierten Angebot oder direkt aus einer vollständigen Route erstellt.

Route kalkulieren#

Senden Sie an POST /partner/v1/quotes:

• pickup und dropoff mit address, latitude und longitude.
• vehicle_type_id aus GET /partner/v1/vehicle-types.
• Optional bis zu zehn stops in der Reihenfolge, in der sie angefahren werden sollen.
• Optional extras mit extra_id, option_id und quantity.

Das Angebot enthält eine quote_id, Preis, Distanz, Dauer und valid_until. Eine Quote ist fünf Minuten gültig.

Lieferung erstellen#

Senden Sie an POST /partner/v1/deliveries entweder eine gültige quote_id oder die vollständige Route. Beides darf nicht kombiniert werden.

Zusätzlich erforderlich ist contact mit name und phone; email ist optional. Unterstützt werden außerdem:

• external_id als Ihre eigene eindeutige Referenz.
• notes für operative Hinweise.
• scheduled_at als RFC-3339-Zeitstempel.
• test_scenario mit courier_cancelled oder delivery_failed bei Testschlüsseln.

Jeder Create-Request benötigt einen eindeutigen Idempotency-Key-Header.

Artikel beschreiben#

POST /partner/v1/quotes und POST /partner/v1/deliveries akzeptieren optional ein items-Array mit einer bis hundert Positionen. Jede Position beschreibt identische Einheiten:

• quantity, weight_kg pro Einheit sowie die Außenmaße length_cm, width_cm und height_cm pro Einheit sind Pflicht.
• sku, customer_reference, barcode, gtin, sscc und source_line_id sind optionale Kennungen. Sie bleiben an der Lieferung, werden auf Paketlabels gedruckt und vom Fahrer gescannt.
• fragile, keep_upright und stackable beschreiben die Handhabung. Zerbrechliche Einheiten werden nie gestapelt; lassen Sie stackable weg, wenn Sie es nicht wissen.

vehicle_type_id bleibt Pflicht. Maxmove prüft, ob das gewählte Fahrzeug alle Positionen transportieren kann. Andernfalls schlägt der Request mit HTTP 400 und dem Fehlercode vehicle_does_not_fit fehl; wählen Sie dann ein größeres Fahrzeug aus GET /partner/v1/vehicle-types und wiederholen Sie den Aufruf. Ungültige Positionsdaten liefern invalid_items.

Senden Sie items sowohl bei der Quote als auch bei der Lieferung, damit der Preis bereits das Fahrzeug widerspiegelt, mit dem Sie die Lieferung anlegen.

Multi-Stop-Regeln#

• pickup und dropoff nicht in stops wiederholen.
• Zwischenstopps in der tatsächlichen Fahrreihenfolge senden.
• Pro Route sind maximal zehn Zwischenstopps zulässig.
• Adressen immer zusammen mit gültigen Koordinaten übertragen.

Die API übernimmt die übermittelte Reihenfolge unverändert für Dispatch, Tracking und ETA-Berechnung.