Uniconta Connector - Create Customer

This function handles the creation of new customer records in Uniconta, triggered when a new customer is submitted from the App4Sales platform. It also supports updating existing customer records if a matching customer code is provided. The process involves mapping App4Sales customer data to Uniconta's debtor structure, including core fields, addresses, contact persons, and custom user-defined fields.

Trigger & Permissions

The customer creation flow is triggered when a new customer is created or an existing one is updated within the App4Sales platform (e.g., via the mobile app or backoffice synchronization). This functionality is controlled by the following connector info flags:

EditCustomer
CreateCustomer

These flags must be enabled in the connector's configuration for customer creation and updates to function.

Payload Mapping

Core Customer Fields

App4Sales Field	Source Field (Uniconta Debtor)	Logic/Notes
`CustomerName`	`_Name`	Direct mapping.
`MainContactPerson.Email`	`_ContactEmail`	Email address of the main contact person.
`EmailAddressForStock`	`_InvoiceEmail`	If provided, this email is used for invoices; otherwise, the general `Email` is used.
`MainContactPerson.FullName`	`_ContactPerson`	Full name of the main contact person.
`LanguageCode`	`_Language`	App4Sales language code is parsed to a Uniconta language enum.
`MainContactPerson.MobileNumber`	`_MobilPhone`	Mobile phone number of the main contact person.
`Phone`	`_Phone`	General phone number.
`VatCode`	`_LegalIdent`	VAT identification number.
`Website`	`_Www`	Customer's website.
`PriceList.Code` (from `UsesPriceField`)	`_PriceList`	The code of the customer's assigned price list.
`PriceList.ExternalCurrency` (from `UsesPriceField`)	`_Currency`	External currency code from the price list, parsed to Uniconta currency enum. Defaults to `XXX` if not parsable.
`PaymentConditionCode`	`_Payment`	Customer's payment condition code.
`PaymentConditionCode`	`_PaymentMethod`	Parsed as a byte and then cast to Uniconta's `PaymentTypes` enum.
`CustomerCode`	`_Account`	If an existing `CustomerCode` is provided, it is used. Otherwise, a new code is generated as "A4S " + `NextCustomerNumber` from connector settings.

Visit Address Mapping

App4Sales Field	Source Field (Uniconta Debtor)	Logic/Notes
`Addresses` (Type: `Visit`)`.AddressLine1`	`_Address1`	Direct mapping for the main address line.
`Addresses` (Type: `Visit`)`.AddressLine2`	`_Address2`	Direct mapping for the second address line.
`Addresses` (Type: `Visit`)`.AddressLine3`	`_Address3`	Direct mapping for the third address line.
`Addresses` (Type: `Visit`)`.IsoCode`	`_Country`	ISO2 country code is converted to Uniconta's `CountryCode` enum using `CultureHelper.GetCountryFromIso2`.
`Addresses` (Type: `Visit`)`.City`	`_City`	Direct mapping for the city.
`Addresses` (Type: `Visit`)`.PostCode`	`_ZipCode`	Direct mapping for the postal code.

Delivery Address Mapping

App4Sales Field	Source Field (Uniconta Debtor)	Logic/Notes
`Addresses` (Type: `Delivery`)`.AddressLine1`	`_DeliveryAddress1`	Direct mapping for the delivery address line.
`Addresses` (Type: `Delivery`)`.AddressLine2`	`_DeliveryAddress2`	Direct mapping for the second delivery address line.
`Addresses` (Type: `Delivery`)`.AddressLine3`	`_DeliveryAddress3`	Direct mapping for the third delivery address line.
`Addresses` (Type: `Delivery`)`.City`	`_DeliveryCity`	Direct mapping for the delivery city.
`Addresses` (Type: `Delivery`)`.IsoCode`	`_DeliveryCountry`	ISO2 country code is converted to Uniconta's `CountryCode` enum using `CultureHelper.GetCountryFromIso2`.
`Addresses` (Type: `Delivery`)`.PostCode`	`_DeliveryZipCode`	Direct mapping for the delivery postal code.

Custom User Fields

Custom fields can be mapped from App4Sales to Uniconta user-defined fields based on the CustomerFreeFieldsConfiguration connector setting. This setting is a JSON string that defines the mapping between App4Sales fields (either entity properties or elements within UnknownElements) and Uniconta's user fields.

App4Sales Field	Source Field (Uniconta Debtor User Field)	Logic/Notes
`customField.XmlName` (from config)	`unicontaCustomer.UserField[X]`	Value is retrieved from `customer` (either property or `UnknownElements`) based on `customField.IsEntityField` and mapped to a Uniconta user field identified by `customField.PropertyName`. Type conversion (Boolean, DateTime, Double, Single, String) is applied based on `customField.PropertyType`.

Validation & Defaults

New Customer Code Generation: If no CustomerCode is provided from App4Sales, a new one is generated in the format "A4S " followed by the NextCustomerNumber from the connector settings. The NextCustomerNumber setting is incremented after a successful new customer creation.
Country Code Conversion: App4Sales ISO2 country codes are converted to Uniconta's internal CountryCode enum. If conversion fails, the country information may be omitted, and the error is logged.
Currency Conversion: The external currency code from the assigned price list is parsed into Uniconta's Currencies enum. If parsing fails, it defaults to Currencies.XXX.
Payment Method Conversion: The PaymentConditionCode is parsed to a byte and then cast to Uniconta's PaymentTypes enum.

Response & Error Handling

Upon attempting to insert or update a customer, the connector calls the Uniconta API and checks the returned ErrorCodes.

Success: If the API call is successful (ErrorCodes.Succes), the Uniconta customer account number (unicontaCustomer._Account) is returned as the new CustomerCode for App4Sales. The customer cache within the connector is also expired to ensure fresh data on subsequent reads.
Error: If the API returns an error code, an exception is thrown with a message indicating the error code and the customer code, providing details for troubleshooting.
Custom User Fields Update: Setting custom user fields is performed in a separate API call after the main customer insert/update. Any errors during this specific step are logged but do not block the overall customer creation if the initial insert/update was successful.

Related Settings & Prerequisites

NextCustomerNumber: An internal setting used to generate unique customer codes for new customers.
CustomerFreeFieldsConfiguration: A JSON string configuring how custom App4Sales fields map to Uniconta's user-defined fields.
Connector Info Flags: EditCustomer and CreateCustomer must be enabled.

Known Limitations

The connector assumes that PaymentConditionCode can be safely parsed as a byte to derive the Uniconta PaymentTypes enum. Incorrect values may lead to errors.
Errors during country code or currency parsing may result in incomplete address or currency information in Uniconta.

Uniconta - Create customer