Partner commerciali: Cliente / Committente

Clienti e committenti sono denominati partner commerciali in X4Fleet. I nuovi partner commerciali vengono importati e creati automaticamente durante il POST Shipment. Se la registrazione degli ordini avviene manualmente o se il catalogo dei partner commerciali deve essere sincronizzato tra il sistema sorgente e X4Fleet, è possibile utilizzare i seguenti endpoint API.

Endpoint

POST /x4gateway/v1/import/client

nonché
GET /x4gateway/v1/import/client/{id} --> normale richiesta GET tramite ID
GET /x4gateway/v1/import/client --> richiesta GET tramite RefID
PUT /x4gateway/v1/import/client/{id} --> richiesta UPDATE tramite ID
DELETE /x4gateway/v1/import/client/{id} --> normale richiesta DELETE tramite ID

Request

{
	"refId": "string",
	"organisation": "string",
	"contactName": "string",
	"name2": "string",
	"clientNumber": "string",
	"roles": 0,						//Ruolo del partner commerciale (cliente, committente, entrambi), nuovi partner commerciali senza indicazione: cliente (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": {},					//Indirizzo / Coordinate
	"profilePix": "string",
	"language": "string",
	"paymentType": 0,
	"notes": "string",
	"contacts": [					//Persone di contatto, campi vedi sotto
		{
			"id": 0,					//assegnato dal sistema
			"refId": "string",			//Riferimento alla persona di contatto nel sistema sorgente
			"contactName": "string",
			"organisation": "string",
			"...": "..."
		}
	],
	"poBox": "string",				//Casella postale
	"fax": "string",
	"web": "string",					//Sito web
	"assignedLocations": [{}],			//Sedi assegnate
}

Enumerazioni utilizzate: Ruolo, Solvibilità, Modalità di pagamento.

Regole di importazione e aggiornamento

Partner commerciali

Un POST con un refId già assegnato a un altro partner commerciale viene rifiutato. I partner commerciali esistenti vengono aggiornati con PUT.
I campi non inviati o inviati con null mantengono il valore memorizzato. Per i campi di testo, una stringa vuota "" sovrascrive il valore memorizzato con un valore vuoto.
invoicingMails viene sovrascritto solo se viene inviato almeno un indirizzo non vuoto.
Se roles non viene inviato, il ruolo memorizzato viene mantenuto. I nuovi partner commerciali senza indicazione ricevono il ruolo cliente (1).

Contatti

Un contatto (contacts) prevede i seguenti campi: id, refId, contactName, organisation, phone1, phone2, email, location, fax, poBox, birthday, notes, isMainContact.

Un contatto viene acquisito solo se almeno uno dei campi contactName, organisation, email, phone1 o phone2 è compilato. I contatti senza questi dati vengono ignorati.
I contatti esistenti vengono associati prima tramite l'id e poi tramite il refId. I caratteri speciali nel refId (ad es. "Łódź") sono supportati.
I campi non inviati o inviati con null mantengono il valore memorizzato. Una stringa vuota "" sovrascrive il valore memorizzato con un valore vuoto. Eccezione: il refId di un contatto non può essere svuotato.
Il refId di un contatto può essere modificato. A tale scopo, identifichi il contatto tramite il suo id e invii il nuovo refId.
Un refId vuoto o composto solo da spazi viene considerato come non inviato.
I contatti inviati senza id né refId per impostazione predefinita non vengono associati in modo affidabile a un contatto esistente e di regola vengono creati di nuovo, per cui possono nascere duplicati. Per evitarlo, è possibile attivare l'associazione tramite il contenuto (vedi sotto).
Un contatto senza un proprio refId viene restituito con un refId numerico generato dal sistema. Per i contatti creati tramite l'API senza refId, questo valore viene anche memorizzato. Questo refId non è un riferimento del sistema sorgente, può cambiare da una chiamata all'altra e non deve essere utilizzato per l'identificazione. Utilizzi invece l'id, un proprio refId o l'associazione tramite il contenuto.

Associare i contatti tramite il contenuto

Con l'impostazione Match gateway contacts without refId by content, i contatti inviati senza id e senza refId vengono associati a un contatto esistente tramite il loro contenuto. L'impostazione è disattivata per impostazione predefinita e ha effetto se è attivata nel gruppo principale. Si trova nelle impostazioni nella scheda Importazione, sezione Impostazioni di importazione degli ordini, ed è visibile solo ai superamministratori. Per far attivare l'impostazione, si rivolga al supporto.

Ordine di associazione: prima tramite l'id, poi tramite un refId inviato e solo dopo tramite il contenuto. I contatti con id o refId non vengono mai associati tramite il contenuto.
Vengono confrontati organisation, contactName e phone1. Se tutti e tre sono vuoti, vengono confrontati invece email e phone2.
Per organisation, contactName e email non contano maiuscole/minuscole, spazi iniziali e finali né spazi multipli. Per phone1 e phone2 vengono confrontate solo le cifre; i prefissi non vengono uniformati, quindi +41 52 … e 052 … sono considerati diversi.
Un contatto esistente viene trovato solo se almeno uno dei seguenti campi viene inviato esattamente come è memorizzato (maiuscole/minuscole escluse): contactName o phone1 (se dei tre campi è compilato solo organisation: organisation), oppure email o phone2, se vengono confrontati questi.
La ricerca avviene tra i contatti del gruppo principale. Se corrispondono più contatti, viene utilizzato il contatto con l'id più piccolo.
I contatti uguali all'interno della stessa richiesta vengono raggruppati in un unico contatto.
L'associazione vale anche per i contatti delle sedi e per i contatti negli ordini.

Response

La struttura della risposta è analoga alla struttura della richiesta; vengono restituite tutte le informazioni inviate nel POST nonché le informazioni integrate dal sistema.

L'ID / l'ID partner commerciale è un'informazione importante che dovrebbe idealmente essere memorizzata nel sistema sorgente.

Messaggi di errore frequenti

GET:

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