Geschäftspartner: Kunde / Auftraggeber

Kunden und Auftraggeber werden in X4Fleet als Geschäftspartner bezeichnet. Neue Geschäftspartner werden bei POST Shipment automatisch importiert und angelegt. Wenn die Auftragserfassung jedoch manuell erfolgt oder wenn der Geschäftspartnerkatalog zwischen Vorsystem und X4Fleet synchronisiert werden soll, können die folgenden Endpunkte der API verwendet werden.

Endpunkte

POST /x4gateway/v1/import/client

sowie
GET /x4gateway/v1/import/client/{id} --> normaler GET Request mittels ID
GET /x4gateway/v1/import/client --> GET Request mittels RefID
PUT /x4gateway/v1/import/client/{id} --> UPDATE Request mittels ID
DELETE /x4gateway/v1/import/client/{id} --> normaler DELETE Request mittels ID

Request

{
	"refId": "string",
	"organisation": "string",
	"contactName": "string",
	"name2": "string",
	"clientNumber": "string",
	"roles": 0,						//Rolle des Geschäftspartner (Kunde, Auftraggeber, beides), neue Geschäftspartner ohne Angabe: Kunde (1)
	"vat": 0,
	"invoicingVatDisplay": 0,
	"priority": {},
	"invoicingMails": [],
	"creditRating": 0,
	"daysForPayment": 0,
	"skontoDaysForPayment": 0,
	"skontoDiscountPercent": 0,
	"generalPositionsDiscount": 0,
	"guSurchargePercent": 0,
	"guFuelSurchargePercent": 0,
	"guLoadingToolSurchargePercent": 0,
	"guLoadingToolSurchargeFix": 0,
	"phone1": "string",
	"phone2": "string",
	"email": "string",
	"location": {},					//Adresse / Koordinaten
	"profilePix": "string",
	"language": "string",
	"paymentType": 0,
	"notes": "string",
	"contacts": [					//Kontaktpersonen, Felder siehe unten
		{
			"id": 0,					//vom System vergeben
			"refId": "string",			//Referenz zur Kontaktperson aus dem Vorsystem
			"contactName": "string",
			"organisation": "string",
			"...": "..."
		}
	],
	"poBox": "string",				//Postfach
	"fax": "string",
	"web": "string",					//Webseite
	"assignedLocations": [{}],			//Zugewiesene Stellen
}

Verwendete Enum's: Rolle, Kreditwürdigkeit, Zahlungsart.

Import- und Aktualisierungsregeln

Geschäftspartner

• Ein POST mit einer refId, die bereits einem anderen Geschäftspartner zugeordnet ist, wird abgelehnt. Bestehende Geschäftspartner werden mit PUT aktualisiert.
• Felder, die nicht mitgeschickt oder mit null gesendet werden, behalten den gespeicherten Wert. Bei Textfeldern überschreibt ein leerer String "" den gespeicherten Wert mit einem leeren Wert.
• invoicingMails wird nur überschrieben, wenn mindestens eine nicht leere Adresse mitgeschickt wird.
• Wird roles nicht mitgeschickt, bleibt die gespeicherte Rolle erhalten. Neue Geschäftspartner ohne Angabe erhalten die Rolle Kunde (1).

Kontakte

Ein Kontakt (contacts) kennt die folgenden Felder: id, refId, contactName, organisation, phone1, phone2, email, location, fax, poBox, birthday, notes, isMainContact.

• Ein Kontakt wird nur übernommen, wenn mindestens eines der Felder contactName, organisation, email, phone1 oder phone2 gefüllt ist. Kontakte ohne diese Angaben werden ignoriert.
• Bestehende Kontakte werden zuerst über die id und danach über die refId zugeordnet. Sonderzeichen in der refId (z. B. "Łódź") werden dabei unterstützt.
• Felder, die nicht mitgeschickt oder mit null gesendet werden, behalten den gespeicherten Wert. Ein leerer String "" überschreibt den gespeicherten Wert mit einem leeren Wert. Ausnahme: Die refId eines Kontakts kann nicht geleert werden.
• Die refId eines Kontakts kann geändert werden. Dazu den Kontakt über seine id identifizieren und die neue refId mitschicken.
• Eine leere oder nur aus Leerzeichen bestehende refId gilt als nicht mitgeschickt.
• Kontakte, die weder mit id noch mit refId gesendet werden, werden standardmässig nicht zuverlässig einem bestehenden Kontakt zugeordnet und in der Regel neu angelegt, sodass Duplikate entstehen können. Um das zu vermeiden, kann die Zuordnung über den Inhalt eingeschaltet werden (siehe unten).
• Ein Kontakt ohne eigene refId wird mit einer vom System erzeugten numerischen refId zurückgemeldet. Bei Kontakten, die über die API ohne refId angelegt werden, wird dieser Wert auch gespeichert. Diese refId ist keine Referenz aus dem Vorsystem, kann sich zwischen Aufrufen ändern und darf nicht zur Identifikation verwendet werden. Verwenden Sie stattdessen die id, eine eigene refId oder die Zuordnung über den Inhalt.

Kontakte über den Inhalt zuordnen

Mit der Einstellung Gateway-Kontakte ohne refId über den Inhalt zuordnen werden Kontakte, die ohne id und ohne refId gesendet werden, über ihren Inhalt einem bestehenden Kontakt zugeordnet. Die Einstellung ist standardmässig ausgeschaltet und wirkt, wenn sie in der Hauptgruppe eingeschaltet ist. Sie befindet sich in den Einstellungen im Register Import, Bereich Import Einstellungen Aufträge, und ist nur für Superadministratoren sichtbar. Um die Einstellung einschalten zu lassen, wenden Sie sich an den Support.

• Reihenfolge der Zuordnung: zuerst über die id, danach über eine mitgeschickte refId und erst dann über den Inhalt. Kontakte mit id oder refId werden nie über den Inhalt zugeordnet.
• Verglichen werden organisation, contactName und phone1. Sind alle drei leer, werden stattdessen email und phone2 verglichen.
• Bei organisation, contactName und email spielen Gross-/Kleinschreibung, führende und nachfolgende Leerzeichen sowie mehrfache Leerzeichen keine Rolle. Bei phone1 und phone2 werden nur die Ziffern verglichen; Vorwahlen werden nicht vereinheitlicht, +41 52 … und 052 … gelten also als verschieden.
• Ein bestehender Kontakt wird nur gefunden, wenn mindestens eines der folgenden Felder genau so gesendet wird, wie es gespeichert ist (Gross-/Kleinschreibung ausgenommen): contactName oder phone1 (ist von den drei Feldern nur organisation gefüllt: organisation), bzw. email oder phone2, wenn diese verglichen werden.
• Gesucht wird unter den Kontakten der Hauptgruppe. Passen mehrere Kontakte, wird der Kontakt mit der kleinsten id verwendet.
• Gleiche Kontakte innerhalb desselben Requests werden zu einem Kontakt zusammengefasst.
• Die Zuordnung gilt auch für Stellenkontakte und für die Kontakte in Aufträgen.

Response

Die Response-Struktur ist analog der Request-Struktur, und alle Informationen welche im POST gesendet wurden, sowie vom System ergänzte Informationen, werden zurückgemeldet.

Dabei ist die ID / Geschäftspartner-ID eine wichtige Information, die ideallerweise im Vorsystem gemerkt wird.

Häufige Fehlermeldungen

GET:

• {"code":5,"messages":["Client with this id or refNr does not exist"],"RequestId":null,"Id":0}