Spector Connector - Create Customer

This document describes how the Spector connector creates or updates customer records in the Specter ERP system. The process involves converting an App4Sales customer object into a Specter-specific format, sending it via an API call, and handling the response. The connector determines whether to create a new customer or update an existing one based on the presence of an App4Sales Customer Code.

Data Source Configuration

The connector communicates with the Specter API at the endpoint: https://api.specter.se. Authentication details and a unique integration ID are used in constructing the API requests. Data is pushed to the Specter system via HTTP POST requests.

Data Mapping Table: Customer Header Fields

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`CustomerCode`	`CustomerId`	If `CustomerCode` is present, it is used to identify an existing customer for update. Otherwise, a new customer is created. This also influences `ForceCustomerUpdate` and `IdentifyByCustomerId`.
`CustomerName`	`Name`	Mapped directly. Required field in Specter. Max length 100 characters.
`LanguageCode`	`Language`	Mapped directly.
`ChamberOfCommerceCode`	`OrgNo`	Mapped directly. Max length 20 characters.
`VatCode`	`VatNo`	Mapped directly. Max length 30 characters.
`Website`	`Homepage`	Mapped directly. Max length 50 characters.
`Email` (from MainContactPerson or Customer)	`EmailAddress`	Prioritizes email from `MainContactPerson`, then `Customer.Email`, then `VisitAddress.Email`. Required field in Specter. Max length 100 characters.
`Phone` (from Customer, VisitAddress, or ContactPerson)	`PhoneNo`	Prioritizes phone from `Customer.Phone`, then `VisitAddress.Phone`, then `ContactPerson.Phonenumber`. Max length 50 characters.
`Fax` (from Customer or VisitAddress)	`FaxNo`	Prioritizes fax from `Customer.Fax`, then `VisitAddress.Fax`. Max length 50 characters.
`UsesPriceField` (PriceList ID)	`Currency`	The `Currency` is retrieved from the App4Sales PriceList associated with `customer.UsesPriceField`. If the PriceList or Currency is not found, Specter will use its default currency (SEK).
`UnknownElements["CustomerGroupId"]`	`CustomerGroupId`	If present in `customer.UnknownElements`, it is parsed as an integer.
`request.Username`	`SalesRepresentativeId`	The `ResIdString` associated with the `request.Username` (from the SalesReps table) is parsed as an integer and used as the Sales Representative ID. If not found or invalid, it's set to null.
Hardcoded	`TypeCustomer`	Defaults to "C" (Company) for new customers; otherwise, it is not sent. Max length 1 character.
Hardcoded	`CustomerOrganizationalForm`	Defaults to "C" (Company) for new customers; otherwise, it is not sent. Max length 1 character.
`AlertText` (from ExtraData if enabled)	`CustomerFreeField` (serialized XML)	If setting `ShowAlertTextOnRelationCard` is enabled, `ExtraData` is serialized as an XML list of `CustomerFreeField` objects.

Data Mapping Table: Contact Person Fields

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`ContactPersons.FirstOrDefault().FullName`	`ContactPerson`	Full name of the first contact person.
`ContactPersons.FirstOrDefault().FirstName`	`FirstName`	First name of the first contact person. Required field in Specter. Max length 50 characters.
`ContactPersons.FirstOrDefault().LastName`	`SurName`	Last name of the first contact person. Required field in Specter. Max length 50 characters.
`ContactPersons.FirstOrDefault().MobileNumber`	`MobileNo`	Mobile number of the first contact person. Max length 50 characters.

Data Mapping Table: Visit Address Fields

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Visit).AddressLine1`	`Address`	Address Line 1 from the App4Sales visit address. Max length 100 characters.
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Visit).AddressLine2`	`AddressRow2`	Address Line 2 from the App4Sales visit address. Max length 100 characters.
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Visit).City`	`City`	City from the App4Sales visit address. Max length 50 characters.
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Visit).Iso2`	`CountryCode`	ISO 2-letter country code from the App4Sales visit address. Max length 2 characters.
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Visit).PostCode`	`ZipCodeEng`	Postcode from the App4Sales visit address. Max length 10 characters.

Data Mapping Table: Delivery Address Fields

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
`CustomerName`	`DeliveryCompanyName`	Customer name is used as the delivery company name. Max length 100 characters.
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Delivery).AddressLine1`	`DeliveryAddress`	Address Line 1 from the App4Sales delivery address. Max length 100 characters.
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Delivery).AddressLine2`	`DeliveryAddressRow2`	Address Line 2 from the App4Sales delivery address. Max length 100 characters.
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Delivery).City`	`DeliveryCity`	City from the App4Sales delivery address. Max length 50 characters.
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Delivery).Iso2`	`DeliveryCountryCode`	ISO 2-letter country code from the App4Sales delivery address. Max length 2 characters.
`Addresses.FirstOrDefault(x => x.AddressType == Core.Constants.AddressType.Delivery).PostCode`	`DeliveryZipCodeEng`	Postcode from the App4Sales delivery address. Max length 10 characters.

Special Logic & Filters

**Upsert Logic**: The connector employs an upsert (update or insert) strategy. If an App4Sales CustomerCode is present, ForceCustomerUpdate and IdentifyByCustomerId flags are set to true in the Specter payload, indicating an update to an existing customer. If CustomerCode is empty, a new customer creation is assumed.
**Organizational Form**: For new customer creations (when CustomerCode is empty), TypeCustomer and CustomerOrganizationalForm are hardcoded to "C" (Company). These fields are not sent for updates to existing customers, implying Specter maintains their existing values.
**Sales Representative ID**: The SalesRepresentativeId in Specter is populated from the ResIdString associated with the App4Sales user's username. This ID is retrieved from the SalesReps table in the App4Sales database.
**Currency**: The currency sent to Specter is derived from the App4Sales PriceList linked to the customer's UsesPriceField. If this currency is not found, Specter's default currency (SEK) will be used.
**Dynamic Fields**: The connector checks for a CustomerGroupId within the UnknownElements dictionary of the App4Sales customer object.
**Data Truncation**: Fields with [MaxLength] attributes in SpecterPostCustomer are truncated to their specified maximum length before being sent to Specter.
**Required Fields**: Fields marked with [Required] in SpecterPostCustomer (e.g., Name, FirstName, SurName, EmailAddress) must have values, otherwise the Specter API may reject the request.

Response & Error Handling

After sending the customer data, the Specter connector processes the API response.

The API response is encapsulated in an ApiResponse object, which includes a Result code, a Code (often the new customer ID), and a Message.
A Result code of 1 indicates successful processing by Specter.
If the response Result is not 1 (or is null), an error is logged. If the response Code begins with "ERROR", a CustomerCouldNotCreatedOrUpdated exception is thrown, preventing the customer from being created or updated in App4Sales.
Upon successful creation or update, the returned Code from the Specter API is used to update the customer.CustomerCode in App4Sales. This Code typically represents the new Specter customer ID.

Spector - Create customer