Partenaires commerciaux : Client / Donneur d'ordre

Les clients et donneurs d'ordre sont désignés comme partenaires commerciaux dans X4Fleet. Les nouveaux partenaires commerciaux sont automatiquement importés et créés lors du POST Shipment. Si la saisie des commandes est effectuée manuellement ou si le catalogue de partenaires commerciaux doit être synchronisé entre le système source et X4Fleet, les endpoints API suivants peuvent être utilisés.

Endpoints

POST /x4gateway/v1/import/client

ainsi que
GET /x4gateway/v1/import/client/{id} --> requête GET normale via ID
GET /x4gateway/v1/import/client --> requête GET via RefID
PUT /x4gateway/v1/import/client/{id} --> requête UPDATE via ID
DELETE /x4gateway/v1/import/client/{id} --> requête DELETE normale via ID

Request

{
	"refId": "string",
	"organisation": "string",
	"contactName": "string",
	"name2": "string",
	"clientNumber": "string",
	"roles": 0,						//Rôle du partenaire commercial (client, donneur d'ordre, les deux), nouveaux partenaires commerciaux sans indication : client (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 / Coordonnées
	"profilePix": "string",
	"language": "string",
	"paymentType": 0,
	"notes": "string",
	"contacts": [					//Personnes de contact, champs voir ci-dessous
		{
			"id": 0,					//attribué par le système
			"refId": "string",			//Référence à la personne de contact dans le système source
			"contactName": "string",
			"organisation": "string",
			"...": "..."
		}
	],
	"poBox": "string",				//Case postale
	"fax": "string",
	"web": "string",					//Site web
	"assignedLocations": [{}],			//Sites assignés
}

Énumérations utilisées : Rôle, Solvabilité, Mode de paiement.

Règles d'import et de mise à jour

Partenaires commerciaux

Un POST avec un refId déjà attribué à un autre partenaire commercial est refusé. Les partenaires commerciaux existants sont mis à jour avec PUT.
Les champs qui ne sont pas transmis ou qui sont envoyés avec null conservent la valeur enregistrée. Pour les champs de texte, une chaîne vide "" remplace la valeur enregistrée par une valeur vide.
invoicingMails n'est remplacé que si au moins une adresse non vide est transmise.
Si roles n'est pas transmis, le rôle enregistré est conservé. Les nouveaux partenaires commerciaux sans indication reçoivent le rôle client (1).

Contacts

Un contact (contacts) comprend les champs suivants : id, refId, contactName, organisation, phone1, phone2, email, location, fax, poBox, birthday, notes, isMainContact.

Un contact n'est repris que si au moins l'un des champs contactName, organisation, email, phone1 ou phone2 est renseigné. Les contacts sans ces indications sont ignorés.
Les contacts existants sont associés d'abord via l'id, puis via le refId. Les caractères spéciaux dans le refId (p. ex. « Łódź ») sont pris en charge.
Les champs qui ne sont pas transmis ou qui sont envoyés avec null conservent la valeur enregistrée. Une chaîne vide "" remplace la valeur enregistrée par une valeur vide. Exception : le refId d'un contact ne peut pas être vidé.
Le refId d'un contact peut être modifié. Pour cela, identifiez le contact via son id et transmettez le nouveau refId.
Un refId vide ou composé uniquement d'espaces est considéré comme non transmis.
Les contacts transmis sans id ni refId ne sont par défaut pas associés de manière fiable à un contact existant et sont en règle générale créés à nouveau, ce qui peut entraîner des doublons. Pour éviter cela, l'association par le contenu peut être activée (voir ci-dessous).
Un contact sans refId propre est renvoyé avec un refId numérique généré par le système. Pour les contacts créés via l'API sans refId, cette valeur est également enregistrée. Ce refId n'est pas une référence du système source, peut changer d'un appel à l'autre et ne doit pas être utilisé pour l'identification. Utilisez plutôt l'id, votre propre refId ou l'association par le contenu.

Associer les contacts par le contenu

Avec le paramètre Associer les contacts de la passerelle sans refId par leur contenu, les contacts transmis sans id et sans refId sont associés à un contact existant par leur contenu. Le paramètre est désactivé par défaut et s'applique lorsqu'il est activé dans le groupe principal. Il se trouve dans les paramètres, onglet Importation, section Importation des paramètres d'ordres, et n'est visible que pour les superadministrateurs. Pour faire activer le paramètre, adressez-vous au support.

Ordre d'association : d'abord via l'id, ensuite via un refId transmis et seulement ensuite par le contenu. Les contacts avec id ou refId ne sont jamais associés par le contenu.
Les champs organisation, contactName et phone1 sont comparés. Si les trois sont vides, ce sont email et phone2 qui sont comparés.
Pour organisation, contactName et email, les majuscules/minuscules, les espaces en début et en fin ainsi que les espaces multiples ne jouent aucun rôle. Pour phone1 et phone2, seuls les chiffres sont comparés ; les indicatifs ne sont pas uniformisés, +41 52 … et 052 … sont donc considérés comme différents.
Un contact existant n'est trouvé que si au moins l'un des champs suivants est transmis exactement tel qu'il est enregistré (hormis les majuscules/minuscules) : contactName ou phone1 (si, parmi les trois champs, seul organisation est renseigné : organisation), ou email ou phone2 lorsque ceux-ci sont comparés.
La recherche porte sur les contacts du groupe principal. Si plusieurs contacts correspondent, le contact avec le plus petit id est utilisé.
Les contacts identiques au sein d'une même requête sont regroupés en un seul contact.
L'association s'applique également aux contacts de sites et aux contacts dans les ordres.

Response

La structure de la réponse est analogue à la structure de la requête ; toutes les informations envoyées dans le POST ainsi que les informations complétées par le système sont renvoyées.

L'ID / l'ID partenaire commercial est une information importante qui devrait idéalement être mémorisée dans le système source.

Messages d'erreur fréquents

GET:

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