Multivers Extended V3 - Create Customer

This document describes the process of creating a new customer in Multivers Extended V3 from App4Sales. The process is initiated when a new customer is created in the App4Sales application. The connector then creates a corresponding Debtor and Organisation in Multivers, along with associated addresses and contact persons.

Trigger & Permissions

The customer creation process is triggered when a user with the appropriate permissions creates a new customer in the App4Sales app. The following connector information flags must be enabled for this functionality to work:

CreateCustomer
EditCustomer

Validation & Defaults

Before creating a customer, the connector performs several validations and applies default values:

A template debtor and organisation must be configured in the connector settings (InsertCustomerTemplate). If the template is not found, the process will fail.
If the CreateDebtorNumberOnThePortal setting is enabled, the connector generates a new debtor number based on configured number ranges. Otherwise, it uses the CustomerCode from App4Sales.
The VAT scenario is determined based on the customer's country and the VAT settings configured in the connector (HomeCountry, VatScenarioCodeHomeCountry, VatScenarioCodeEU, VatScenarioCodeOutsideEU).

Payload Mapping

The following tables detail how App4Sales data is mapped to Multivers Extended V3 fields.

Customer (Debtor)

Multivers Debtor Field	App4Sales Customer Field / Logic	Logic/Notes
IsActive	-	Hardcoded to `true`.
OrganisationCode	(From created Organisation)	The code of the newly created Organisation.
DebtorCode	`CustomerCode`	Uses the App4Sales `CustomerCode`. If that is empty and `CreateDebtorNumberOnThePortal` is enabled, a new code is generated from a number range.
ContactPersonCode	`MainContactPerson.ContactId`	The ID of the main contact person.
VatNumber	`VatCode`	The customer's VAT number.
PaymentConditionCode	`PaymentConditionCode`	The customer's payment condition code.
CurrencyCode	`Currency`	The customer's currency.
PriceListCode	(from `UsesPriceField`)	The price list code is retrieved from the App4Sales PriceLists context based on the `UsesPriceField`.
VatScenarioCode	(Calculated)	Determined based on the customer's country in relation to the connector's VAT settings.
CalculateVat	(from VAT aceanrio)	Derived from the determined VAT scenario.
AccountReferenceCode	-	Uses the `DefaultAccountReference` setting, or falls back to the account reference from the VAT scenario.
DeliveryAddressCode	(from created Address)	The ID of the created delivery address.
VisitorsAddressCode	(from created Address)	The ID of the created visiting address.
PostalAddressCode	(from created Address)	The ID of the created postal address.
AddressPriorityCode	(from created Address)	The ID of the created general address.
InvoiceTypeCode	-	Hardcoded to "0".
RepresentativeCode	(from request)	The sales representative ID from the request data.
DeliveryConditionCode	`DefaultDeliveryConditionCode`	Uses the value from the connector settings.

Organisation

Multivers Organisation Field	App4Sales Customer Field / Logic	Logic/Notes
Name	`CustomerName`	The name of the customer.
LanguageCode	`LanguageCode`	The customer's language code.
SearchName	`CustomerName`	The customer name, truncated to 6 characters.
Emails	`Email`, `EmailAddressForStock`	A list of email addresses.
CocNumber	`ChamberOfCommerceCode`	The customer's Chamber of Commerce number.
TelephoneNumbers	`Phone`, `Fax`, `ContactPersons.MobileNumber`	A list of telephone numbers.
CountryCode	`Addresses.Iso2`	The ISO2 code from the customer's main address.

Address

Multivers Address Field	App4Sales Address Field / Logic	Logic/Notes
Inactive	-	Hardcoded to `false`.
AddressTypeCode	`AddressType`	The App4Sales address type is mapped to a Multivers address type.
CountryCode	`Country`, `Iso2`	The country code is determined from the address's country or ISO2 code.
City	`City`	The city of the address.
Street	`AddressLine1`	The street is parsed from the first address line.
StreetNumber	`AddressLine1`	The street number is parsed from the first address line.
ZipCode	`PostCode`	The postal code of the address.
AddressAttributes	-	An external address hash is added as an attribute if the `OrgAddressAttributeIdForExternalAddressHash` setting is provided. This is used to track changes to the address.

Contact Person

Multivers Person Field	App4Sales Contact Person Field / Logic	Logic/Notes
FirstName	`FirstName`	The first name of the contact person.
LastName	`LastName`	The last name of the contact person.
FullName	`FullName`	The full name of the contact person.
LanguageCode	(from customer)	The language code of the customer.
Gender	`Gender`	The gender of the contact person. The value "F" is converted to "V".
Initials	`Initials`	The initials of the contact person.
PersonCode	`ContactId`	Uses the App4Sales `ContactId`. If that is empty and `CreateDebtorNumberOnThePortal` is enabled, a new code is generated.
EmailAddresses	`Email`	A list of email addresses.
TelephoneNumbers	`Phonenumber`, `MobileNumber`	A list of telephone numbers.
CountryCode	(from customer address)	The country code from the customer's main address.
PrefixTitle	`Function`	The first word of the contact person's function.
SuffixTitle	`Function`	The second word of the contact person's function.

Response & Error Handling

After the customer is created in Multivers, the new debtor ID is returned. This ID is then used to update the CustomerCode in the App4Sales database. If any errors occur during the process (e.g., the template debtor is not found, or the API call fails), an exception is thrown and the error is logged. The user will receive an error message in the App4Sales application.

After the customer is created, the connector fetches the newly created Organisation from Multivers to update the address and contact person IDs in the App4Sales database. This ensures that subsequent updates to the customer are correctly linked.

Related Settings & Prerequisites

InsertCustomerTemplate: The code of the template debtor in Multivers to use when creating new customers. This is a mandatory setting.
CreateDebtorNumberOnThePortal: If enabled, the connector generates a new debtor number based on configured number ranges.
HomeCountry: The home country of the company, used for determining the correct VAT scenario.
VatScenarioCodeHomeCountry: The VAT scenario code to use for customers in the home country.
VatScenarioCodeEU: The VAT scenario code to use for customers in other EU countries.
VatScenarioCodeOutsideEU: The VAT scenario code to use for customers outside the EU.
DefaultDeliveryConditionCode: The default delivery condition code to use for new customers.
OrgAddressAttributeIdForExternalAddressHash: The ID of the organisation address attribute used to store a hash of the address for change detection.
TeleComUsedTypeEmail: The telecom usage type code for the customer's email address.
TeleComUsedTypeTelephone: The telecom usage type code for the customer's telephone number.

MultiversExtended - Create customer