Clients & external_id

Jedes Vorgio-Team hat seine eigene Liste von Clients (Kunden). Wenn ein Kunde Ihres Shops erstmals einen Checkout durchläuft, legen Sie einen Vorgio-Client an. Beim zweiten Checkout möchten Sie denselben Client wiederverwenden und nicht duplizieren. Das Feld external_id schlägt diese Brücke.

#Wie Find-or-Create funktioniert

Wenn Sie POST /v1/checkouts mit gesetztem client.external_id aufrufen, geht Vorgio so vor:

1. Es sucht in Ihrem Team nach einem bestehenden Client mit derselben external_id.
2. Wird einer gefunden → Vorgio aktualisiert diesen Client mit den von Ihnen übermittelten Feldern (sodass eine Namensänderung in Ihrem Shop übernommen wird) und verwendet ihn für die neue Rechnung.
3. Wird keiner gefunden → Vorgio legt einen neuen Client an.

Der Lookup-Index ist (team_id, external_id) — eindeutig pro Team. Das bedeutet:

• Ein Client mit external_id = "wc_customer_42" in Ihrem Team ist vollständig unabhängig von einem Client mit derselben external_id im Team eines anderen.
• Innerhalb Ihres Teams müssen zwei verschiedene Kunden unterschiedliche external_ids haben.

#Was Sie als external_id verwenden sollten

Die eigene Kunden-ID des Shops, präfigiert mit dem Plattformnamen, um Kollisionen zu vermeiden, falls Sie jemals mehrere Shops mit demselben Vorgio-Team integrieren:

Maximale Länge: 255 Zeichen. Reines ASCII wird empfohlen.

#Was, wenn der Kunde ein Gast-Checkout ist?

Falls Ihr Shop einen Gast-Checkout zulässt (kein dauerhafter Kundendatensatz), verwenden Sie einen stabilen Identifier, den Sie haben — typischerweise die E-Mail-Adresse mit Präfix:

 1external_id = "guest_email_" + sha256(email.lower())[:32]

Damit wird per E-Mail-Adresse dedupliziert, sodass ein wiederkehrender Gast denselben Vorgio-Client erhält. Wenn jeder Gast-Checkout einen eigenen Client erhalten soll (keine Deduplizierung), verwenden Sie stattdessen die Bestell-ID: external_id = "guest_order_1234".

#Mandantentrennung

Kollisionen von external_id über Teams hinweg sind erlaubt. Wenn zwei verschiedene Vorgio-Teams (verschiedene Händler) beide external_id = "customer_1" für völlig unabhängige Kunden verwenden, ist das in Ordnung — der Unique-Constraint gilt pro Team. Es gibt keinen globalen Namespace für external_id.

Das heißt: Gehen Sie niemals davon aus, dass external_id über Ihren Shop hinaus eindeutig ist. Sie ist innerhalb Ihres Teams eindeutig.

#Updates

Wenn Sie eine external_id übermitteln und der Client bereits existiert, überschreibt Vorgio alle übermittelten Client-Felder. Wenn Sie ein bestehendes Feld unverändert lassen möchten, übermitteln Sie seinen aktuellen Wert (senden Sie dieselben Daten erneut).

v1-Verhalten: Alle Client-Felder, die Sie in der API-Referenz als erforderlich markiert haben, sind immer erforderlich, auch beim zweiten und jedem weiteren Aufruf, wenn der Client bereits existiert. Wir haben uns für v1 gegen Partial-Update-Semantik entschieden, weil Shops in der Regel ohnehin alle Felder vorliegen haben und "immer alles senden" deutlich leichter nachzuvollziehen ist.

#Einen Client per external_id nachschlagen

Verwenden Sie GET /v1/clients?external_id=<value> (der List-Endpoint akzeptiert einen Filter). Es wird der passende Client oder eine leere Liste zurückgegeben.

Für die meisten Shops ist das nicht nötig — die Response von POST /v1/checkouts enthält die aufgelöste client_id direkt.

#Wann Sie external_id nicht verwenden sollten

Wenn Ihr Shop ein einmaliges Angebots-/Vorschlags-Tool ist, das pro Kunde genau einmal eine Vorgio-Rechnung ausstellt und nie wieder, können Sie external_id weglassen. Vorgio legt dann pro Aufruf einen frischen Client an. Beachten Sie nur, dass die Vorgio-Client-Liste des Händlers pro Checkout um eine Zeile wächst — unproblematisch bei seltenen Checkouts, hässlich, wenn nicht.

#Verhalten beim Soft-Delete

Wenn der Händler einen Client in der Vorgio-UI per Soft-Delete löscht, wird ein anschließendes POST /v1/checkouts mit derselben external_id … aktuell einen neuen Client anlegen, nicht den gelöschten wiederbeleben. Die gelöschte Zeile behält ihre external_id (der Unique-Constraint gilt für die aktive Zeile).

Das ist beabsichtigt — soft-gelöschte Clients werden in der Regel deshalb gelöscht, weil der Händler sie loswerden möchte. Eine Wiederbelebung beim nächsten Webhook würde überraschen.

Falls Sie einen triftigen Anwendungsfall für eine Wiederbelebung haben, eröffnen Sie ein Issue.