RestJson Connector - Create Customer

This document describes the process of creating or updating a customer in the ERP system via the RestJson connector.

Trigger & Permissions

The customer creation process is triggered when a user in the App4Sales application creates a new customer or updates an existing one. The setting SendCustomersToBackoffice must be enabled in the connector settings for this functionality to work. If this setting is disabled, a new customer number will be generated locally, but no data will be sent to the ERP.

The internal connector info flag CreateCustomer must also be enabled.

Payload Mapping

The connector sends a JSON payload to the ERP. The following tables describe the mapping from the App4Sales customer model to the JSON payload.

Customer

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Id	`CustomerGuid`	The GUID of the customer in App4Sales.
Code	`CustomerCode`	The customer's code. This is used to identify existing customers.
ChamberOfCommerceCode	`ChamberOfCommerceCode`	The customer's Chamber of Commerce code.
Discount	`Discount`	The customer's discount percentage. The value is parsed to a decimal.
IsBlocked	-	Hardcoded to `false`.
IsProspect	-	Hardcoded to `false`.
IsSuspect	-	Hardcoded to `false`.
Created	-	Set to the current date and time (`DateTime.Now`) if the `CustomerCode` is empty (new customer). Otherwise, it is `null`.
Modified	-	Set to the current date and time (`DateTime.Now`).
LanguageCode	`LanguageCode`	The customer's language code.
Name	`CustomerName`	The customer's name.
PaymentCondition	`Id` from the ERP's PaymentConditions endpoint	The GUID of the payment condition. The connector first retrieves the payment conditions from the `/PaymentConditions` endpoint and matches the `Code` from App4Sales with the `Code` from the ERP.
PaymentConditionCode	`Code` from the ERP's PaymentConditions endpoint	The code of the payment condition.
PriceList	`Id` from the ERP's PriceLists endpoint	The GUID of the price list. The connector first retrieves the price lists from the `/PriceLists` endpoint and matches the `Code` from App4Sales with the `Code` from the ERP.
VatCode	`VatCode`	The customer's VAT code.
VatLiable	`VatLiable`	Indicates if the customer is VAT liable.
CustomerManager	`username`	The username of the user who is creating or updating the customer.
UnknownElements	`UnknownElements`	This field is only included if the `IncludeUnknownElementsForNewCustomers` setting is enabled. It contains any extra XML elements from the input that were not mapped to other fields.

Addresses

The connector creates two types of addresses if the corresponding fields are present: a delivery address (del) and a visiting address (vis).

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Id	-	A new GUID is generated for each new address. For existing customers, the connector tries to find the existing address ID in the database.
AddressLine1	`DeliveryAddress1` or `VisitAddress1`
AddressLine2	`DeliveryAddress2` or `VisitAddress2`
City	`DeliveryCity` or `VisitCity`
CountryCode	`CountryCode`	The same country code is used for both addresses.
Customer	`CustomerGuid`	The GUID of the customer.
IsMainAddress	-	Hardcoded to `true`.
PostalCode	`DeliveryPostCode` or `VisitPostCode`
Type	-	Hardcoded to `del` for delivery address and `vis` for visiting address.

Contact

A main contact person is created if the ContactFullName field is present.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Id	-	A new GUID is generated for the new contact. For existing customers, the connector tries to find the existing contact ID in the database.
Phone	`Phone`
LanguageCode	`LanguageCode`
Email	`Email`
FirstName	`ContactFullName`	The first name is extracted from the `ContactFullName` field.
LastName	`ContactFullName`	The last name is extracted from the `ContactFullName` field.
IsMainContact	-	Hardcoded to `true`.
Customer	`CustomerGuid`	The GUID of the customer.
Mobile	`Mobile`

Validation & Defaults

The connector distinguishes between new and existing customers based on the presence of the CustomerCode.

If the CustomerCode is empty or null, the connector assumes it is a new customer. It sends a POST request to the /Customers endpoint. The ERP is expected to return a new customer code.
If the CustomerCode has a value, the connector assumes it is an existing customer. It sends a PUT request to the /Customers endpoint.

Response & Error Handling

For a new customer, the connector expects the ERP to return a JSON object containing the new customer's code in the `Code` field. This code is then saved back to the App4Sales database.

If the SendCustomersToBackoffice setting is disabled, the connector generates a new customer code locally by incrementing the maximum existing customer code by 1.

If the API returns an error, or if the response for a new customer does not contain a customer code, the process will fail and an error message will be returned to the user.

Related Settings & Prerequisites

SendCustomersToBackoffice: When enabled, the connector will send new and updated customer data to the backoffice.
IncludeUnknownElementsForNewCustomers: When enabled, any unmapped XML elements from the source data will be included in the `UnknownElements` field of the JSON payload.

Data Source Configuration

The connector interacts with the following API endpoints:

Customers: /Customers (POST for new customers, PUT for existing customers)
Payment Conditions: /PaymentConditions (GET)
Price Lists: /PriceLists (GET)

RestJson - Create customer