Appearance

Adressen & Kunden erkennen ​

Überblick ​

Viele Adressen sind im Cockpit schon mit Telefonnummer, Ansprechpartner usw. hinterlegt. Die API erkennt sie wieder, damit Ihr System nicht jedes Mal alles mitschicken muss.

So wird eine Adresse erkannt ​

Für pickup und delivery gilt jeweils:

  1. 🆔 Mit id: Die gespeicherte Adresse wird verwendet. Mitgeschickte Felder überschreiben einzelne Werte.
  2. 🔤 Mit name: Gesucht wird eine gespeicherte Adresse mit genau diesem Namen (Groß-/Kleinschreibung egal).
    • Schicken Sie zusätzlich city oder zipCode mit, müssen diese passen. „Autohaus Müller, Dresden“ wird also nie mit „Autohaus Müller, Leipzig“ verwechselt.
    • Ein Treffer: Fehlende Felder (Telefon, Kontakt, Straße …) kommen aus dem Cockpit. Was Sie mitschicken, hat Vorrang.
    • Kein Treffer: Mit mindestens name und city wird eine neue Adresse angelegt. Sonst: address_not_found.
    • Mehrere Treffer: address_ambiguous. Die passenden Adressen stehen in extensions.candidates – schicken Sie dann die id mit.

Tipp: Mit GET /addresses?search=Müller finden Sie gespeicherte Adressen und ihre id, bevor Sie den Auftrag anlegen.

Beispiel für mehrere Treffer (422):

json
{
  "title": "pickup: Mehrere gespeicherte Adressen passen; bitte id, Ort oder PLZ angeben.",
  "status": 422,
  "extensions": {
    "errorCode": "address_ambiguous",
    "field": "pickup",
    "candidates": [
      { "id": 9001, "name": "Autohaus Müller", "street": "Hauptstraße", "zipCode": "04109", "city": "Leipzig" },
      { "id": 9017, "name": "Autohaus Müller", "street": "Ringweg", "zipCode": "04109", "city": "Leipzig" }
    ]
  }
}

So wird ein Kunde erkannt ​

  • client: { "id": 17 } oder client: { "name": "Logether GmbH" } (genauer Name, Groß-/Kleinschreibung egal)
  • Kein Treffer: client_not_found – Kunden werden per API nicht neu angelegt, bitte im Cockpit anlegen.
  • Mehrere Treffer: client_ambiguous mit Kandidaten
  • Ohne client entsteht der Auftrag ohne Kunden.
  • Kunden finden: GET /clients?search=Logether

Doppelte Aufträge vermeiden ​

Geben Sie bei jedem Auftrag Ihre eigene Nummer als externalId mit. Schickt Ihr System dieselbe Anfrage noch einmal (z. B. nach einem Netzwerkfehler), entsteht kein zweiter Auftrag: Die API antwortet mit 409 duplicate_external_id und liefert den vorhandenen Auftrag unter extensions.order.

  • Die Nummer gilt je Person bzw. Token-Besitzer.
  • Auch stornierte Aufträge belegen ihre Nummer weiter.

Was jeder sieht ​

Der Abgleich durchsucht nur, was der Token-Besitzer im Cockpit sehen darf. Ein Auftraggeber findet nur selbst angelegte Adressen und die ihm zugeordneten Kunden – siehe Rechte je Rolle.

Siehe auch ​