Business Partners: Customer / Client

Customers and clients are referred to as business partners in X4Fleet. New business partners are automatically imported and created when posting a shipment (POST Shipment). However, if orders are entered manually or if the business partner catalogue is to be synchronised between the upstream system and X4Fleet, the following API endpoints can be used.

Endpoints

POST /x4gateway/v1/import/client

and
GET /x4gateway/v1/import/client/{id} --> standard GET request by ID
GET /x4gateway/v1/import/client --> GET request by RefID
PUT /x4gateway/v1/import/client/{id} --> UPDATE request by ID
DELETE /x4gateway/v1/import/client/{id} --> standard DELETE request by ID

Request

{
	"refId": "string",
	"organisation": "string",
	"contactName": "string",
	"name2": "string",
	"clientNumber": "string",
	"roles": 0,						//role of the business partner (customer, client, both), new business partners without a value: customer (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": {},					//address / coordinates
	"profilePix": "string",
	"language": "string",
	"paymentType": 0,
	"notes": "string",
	"contacts": [					//contact persons, see fields below
		{
			"id": 0,					//assigned by the system
			"refId": "string",			//reference to the contact person in the upstream system
			"contactName": "string",
			"organisation": "string",
			"...": "..."
		}
	],
	"poBox": "string",				//PO box
	"fax": "string",
	"web": "string",					//website
	"assignedLocations": [{}],			//assigned locations
}

Used enums: Role, Creditworthiness, Payment type.

Import and Update Rules

Business Partners

• A POST with a refId that is already assigned to another business partner is rejected. Existing business partners are updated with PUT.
• Fields that are omitted or sent as null keep their stored value. For text fields, an empty string "" overwrites the stored value with an empty value.
• invoicingMails is only overwritten if at least one non-empty address is sent.
• If roles is not sent, the stored role is kept. New business partners sent without a role receive the role customer (1).

Contacts

A contact (contacts) has the following fields: id, refId, contactName, organisation, phone1, phone2, email, location, fax, poBox, birthday, notes, isMainContact.

• A contact is only accepted if at least one of the fields contactName, organisation, email, phone1 or phone2 is filled in. Contacts without any of these details are ignored.
• Existing contacts are matched first by id and then by refId. Special characters in the refId (e.g. "Łódź") are supported.
• Fields that are omitted or sent as null keep their stored value. An empty string "" overwrites the stored value with an empty value. Exception: the refId of a contact cannot be cleared.
• The refId of a contact can be changed. To do so, identify the contact by its id and send the new refId.
• A refId that is empty or consists only of spaces is treated as not sent.
• Contacts sent with neither id nor refId are, by default, not reliably matched to an existing contact and are usually created anew, which can lead to duplicates. To avoid this, matching by content can be enabled (see below).
• A contact without its own refId is returned with a system-generated numeric refId. For contacts created via the API without a refId, this value is also stored. This refId is not a reference from the upstream system, can change between calls and must not be used for identification. Use the id, your own refId or matching by content instead.

Matching Contacts by Content

With the setting Match gateway contacts without refId by content, contacts sent without id and without refId are matched to an existing contact by their content. The setting is disabled by default and takes effect when it is enabled in the main group. It is located in the settings on the Import tab, Import shipment settings section, and is only visible to super administrators. To have the setting enabled, please contact support.

• Matching order: first by id, then by a refId that was sent, and only then by content. Contacts with id or refId are never matched by content.
• organisation, contactName and phone1 are compared. If all three are empty, email and phone2 are compared instead.
• For organisation, contactName and email, upper/lower case, leading and trailing spaces and multiple spaces are ignored. For phone1 and phone2, only the digits are compared; dialling codes are not normalised, so +41 52 … and 052 … are treated as different.
• An existing contact is only found if at least one of the following fields is sent exactly as it is stored (except for upper/lower case): contactName or phone1 (if only organisation is filled among the three fields: organisation), or email or phone2 if these are compared.
• The search covers the contacts of the main group. If several contacts match, the contact with the lowest id is used.
• Identical contacts within the same request are merged into one contact.
• Matching also applies to site contacts and to the contacts in orders.

Response

The response structure is analogous to the request structure; all information sent in the POST as well as system-added information is returned.

The ID / business partner ID is important information that should ideally be stored in the upstream system.

Common Error Messages

GET:

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