SnelStart Connector - Create Customer

This document details the process of creating or updating customer records in SnelStart via the App4Sales platform. The connector facilitates the transfer of customer data from App4Sales, converting it into a SnelStart-compatible format for submission. It handles both new customer creation and updates to existing customer records based on the provided data.

Trigger & Permissions

The customer creation/update flow is triggered when a customer record is submitted from the App4Sales application or through a backoffice synchronization.

Data Source Configuration

The data source for this process is an App4Sales Customer object, which contains all the relevant customer information, including personal details, addresses, and contact persons. This object is transformed into a SnelStartCustomer entity before being sent to the SnelStart API.

Payload Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Customer.Id`	`SnelStartCustomer.Id`	Mapped from `customer.InternalCode` if an existing customer (`isNewCustomer` is `false`). If `isNewCustomer` is `true`, `Id` is `null`, and SnelStart assigns a new GUID.
`Customer.CustomerCode`	`SnelStartCustomer.CustomerCode`	Mapped from `customer.CustomerCode`. If `isNewCustomer` is `true`, `CustomerCode` is `null`, and SnelStart assigns a new customer code. Converted to integer.
`Customer.CustomerName`	`SnelStartCustomer.CustomerName`	Directly mapped from `customer.CustomerName`.
`DateTime.Now`	`SnelStartCustomer.ModifiedOn`	Set to the current date and time during creation/update.
`Customer.ChamberOfCommerceCode`	`SnelStartCustomer.ChamberOfCommerce`	Directly mapped from `customer.ChamberOfCommerceCode`.
`Customer.VatCode`	`SnelStartCustomer.VatNumber`	Directly mapped from `customer.VatCode`.
`Customer.ContactPersons.Email`	`SnelStartCustomer.EmailAddress`	First email address from the customer's contact persons.
`Customer.Phone`	`SnelStartCustomer.Phone`	Directly mapped from `customer.Phone`.
`Customer.ContactPersons.MobileNumber`	`SnelStartCustomer.MobilePhone`	First mobile number from the customer's contact persons.
Derived	`SnelStartCustomer.LocationAddress`	See "Addresses & Contacts" section for details. Mapped from the customer's delivery address (`AddressType.Delivery`).
Derived	`SnelStartCustomer.PostAddress`	See "Addresses & Contacts" section for details. Mapped from the customer's visit address (`AddressType.Visit`).
`settings.NewCustomerType`	`SnelStartCustomer.RelationTypes`	A list containing a single relation type. Defaults to "Klant" if `settings.NewCustomerType` is empty.

Addresses & Contacts

App4Sales addresses are mapped to SnelStart's LocationAddress (delivery) and PostAddress (visit). The contact name for both addresses is taken from the first contact person's FullName. Country IDs are looked up using the App4Sales Iso2 country code via the LookupCountry service.

App4Sales Field	SnelStart Address Field	Logic/Notes
`Customer.ContactPersons.FullName`	`SnelStartAddress.ContactName`	First full name from the customer's contact persons.
`Address.AddressLine1`	`SnelStartAddress.Street`	Mapped from the `AddressLine1` of the corresponding address type.
`Address.PostCode`	`SnelStartAddress.PostalCode`	Mapped from the `PostCode` of the corresponding address type.
`Address.City`	`SnelStartAddress.City`	Mapped from the `City` of the corresponding address type.
`Address.Iso2`	`SnelStartAddress.CountryId`	The `Iso2` code is used to look up the corresponding SnelStart country ID. Defaults to `Guid.Empty` if not found.

Validation & Defaults

If customer.CustomerCode is empty, the customer is considered new, and a new Id and CustomerCode will be assigned by SnelStart.
ModifiedOn is always set to the current date and time.
RelationTypes defaults to "Klant" if the connector setting "NewCustomerType" is not specified.
Country IDs are looked up; if not found, Guid.Empty is used.

Response & Error Handling

After sending the customer data to SnelStart, the connector processes the API response:

If the SnelStart API returns an error (result.HasError is true), an exception is thrown with the error message.
If the API response is null, a generic "NoBackoffice" error is returned.
Upon successful creation/update, the SnelStart-assigned Id (GUID) is stored in customer.InternalCode and the CustomerCode is stored in customer.CustomerCode for future reference.

Related Settings & Prerequisites

New Customer Type: Defines the relation type assigned to newly created customers in SnelStart. (settings.NewCustomerType)

Known Limitations

Not explicitly identified in the provided code snippet.

SnelStart - Create customer