PrestaShop Connector - Create Customer (OptA4SNewCustomers)

This function handles the creation or update of customer records in PrestaShop, triggered by data received from the App4Sales platform. It processes incoming customer information, validates essential fields, performs duplicate checks, maps data to PrestaShop's customer and address structures, and then submits the data to the PrestaShop API. It supports both creating new customers and updating existing ones based on a unique identifier.

Trigger & Permissions

The customer creation flow is initiated by an internal request from the App4Sales platform (e.g., a new customer submission from the mobile app or a portal request). It requires the CreateCustomer feature flag to be enabled within the connector's configuration settings (ConnectorInfoInternalIds.CreateCustomer).

Data Source Configuration

The connector receives customer data as an XML document within the internal request's input stream. This XML is then transformed into App4Sales Customer objects for processing. The XML structure is expected to contain elements that map to the fields described in the 'Payload Mapping' section below.

Payload Mapping

The incoming XML payload is parsed into an App4Sales Customer object, which is then mapped to the PrestaShop customer and address entities. The following tables detail the mapping from the App4Sales internal data fields (derived from the incoming XML) to the PrestaShop API fields.

Core Customer Fields (App4Sales to PrestaShop)

App4Sales Field	Source Field (XML DataRow)	PrestaShop Target Field	Logic/Notes
`CustomerGuid`	`customerGuid`	N/A	Used internally in App4Sales.
`CustomerCode`	`debCode`	`prestaCustomer.id`	If the incoming XML contains `debCode`, this is used to identify an existing PrestaShop customer (via `customerFactory.Get(id)`). If no `debCode` is provided, a new customer is created.
`CustomerName`	`customerName`	`prestaCustomer.company`	Maps to the company name in PrestaShop.
`MainContactPerson.Email`	`contactEmail`	`prestaCustomer.email`	Sets the customer's email address.
`MainContactPerson.FullName`	`contactfullname`	`prestaCustomer.firstname`, `prestaCustomer.lastname`	The full name is split into first name (first word) and last name (remaining words).
N/A	N/A	`prestaCustomer.passwd`	Hardcoded to "8680b93fc1cd38c19fffa7686709956f".
N/A	N/A	`prestaCustomer.active`	Hardcoded to `1` (active).
N/A	N/A	`prestaCustomer.id_shop_group`	Hardcoded to `1`.
N/A	N/A	`prestaCustomer.id_shop`	Set from the connector's `Settings.IdShop`.

Address Fields (App4Sales to PrestaShop)

The connector supports both a 'delivery' and 'visit' address. Addresses are created or updated if AddressLine1 is present. The VatCode from the customer is also applied to the address.

App4Sales Field	Source Field (XML DataRow)	PrestaShop Target Field	Logic/Notes
`deliveryAddress.AddressLine1`	`deliveryAddress1`	`prestaAddress.address1`	Delivery address line 1.
`deliveryAddress.AddressLine2`	`deliveryAddress2`	`prestaAddress.address2`	Delivery address line 2.
`deliveryAddress.PostCode`	`deliveryPostCode`	`prestaAddress.postcode`	Delivery address postal code.
`deliveryAddress.City`	`deliveryCity`	`prestaAddress.city`	Delivery address city.
`visitAddress.AddressLine1`	`visitAddress1`	`prestaAddress.address1`	Visit address line 1.
`visitAddress.AddressLine2`	`visitAddress2`	`prestaAddress.address2`	Visit address line 2.
`visitAddress.PostCode`	`visitPostCode`	`prestaAddress.postcode`	Visit address postal code.
`visitAddress.City`	`visitCity`	`prestaAddress.city`	Visit address city.
`deliveryAddress.Phone`	`contactPhone`	`prestaAddress.phone`	Uses the contact phone for both delivery and visit addresses.
`deliveryAddress.Email`	`contactEmail`	`prestaAddress.email`	Uses the contact email for both delivery and visit addresses.
`deliveryAddress.Fax`	`contactFax`	`prestaAddress.fax`	Uses the contact fax for both delivery and visit addresses.
`deliveryAddress.Iso2`, `visitAddress.Iso2`	`countryCode` (fallback to `languageCode`)	`prestaAddress.id_country`	The ISO2 country code from the XML is used to look up the internal PrestaShop country ID via `KeySettingsContext`. If `countryCode` is not present, `languageCode` is used as a fallback.
`customer.VatCode`	`VatCode`	`prestaAddress.vat_number`	The VAT code from the App4Sales customer is assigned to the PrestaShop address.
N/A	N/A	`prestaAddress.alias`	Hardcoded to "App4Sales address " followed by a random 5-character hex number.

Other Customer Fields (App4Sales to PrestaShop, not directly mapped to PrestaShop customer object)

App4Sales Field	Source Field (XML DataRow)	Logic/Notes
`VatCode`	`VatCode`	If present, stored in the App4Sales customer object. Used for address VAT number.
`Discount`	`discount`	Parsed as a decimal.
`LanguageCode`	`languageCode`	Stored in the App4Sales customer object.
`UsesPriceField`	`usesPrice`	Parsed as an integer.
`PaymentConditionCode`	`paymentCondition`	Looks up the payment condition code in the App4Sales database. If not found, uses the raw value from the XML.
`VatLiable`	`isVatLiable`	Parsed as a boolean.
`OutstandingItems`	`outstandingItems`	Stored as a string.

Validation & Defaults

**Required Fields:** The connector expects at least contactfullname and an address with deliveryAddress1 or visitAddress1 to create a functional customer and address.
**Default Values:**
- New PrestaShop customers are always marked as active = 1.
- id_shop_group is hardcoded to 1.
- A default, hardcoded password is assigned to new PrestaShop customers.
- If debCode is not provided in the incoming XML, a new customer is created in PrestaShop.
- Addresses are only created if AddressLine1 is not empty.
- If the countryCode is not available in the incoming XML for an address, the languageCode is used as a fallback for the ISO2 country code.
- Address aliases are generated with a random hex number.
**Data Transformations:**
- The contactfullname from the XML is split to derive firstname and lastname for the PrestaShop customer.
- ISO2 country codes are converted to full country names for internal App4Sales address objects.
- discount is parsed to a decimal, usesPrice to an integer, and isVatLiable to a boolean.

Response & Error Handling

**Duplicate Detection:** The connector attempts to find an existing PrestaShop customer using the CustomerCode (which maps to debCode in the incoming XML). If a customer with this ID exists, their record is updated; otherwise, a new customer is created.
**PrestaShop API Responses:** The connector interacts with the PrestaShop API using CustomerFactory and AddressFactory to add or update customer and address entities.
**Error Handling:** The current implementation uses basic try-catch blocks. In case of an exception during API calls, it might result in a partial update or failure to create a customer/address without specific error messages returned to the App4Sales UI beyond generic exceptions.
**New Codes Storage:** Upon successful creation or update of a PrestaShop customer, their PrestaShop ID is appended to the return message. Additionally, the PrestaShop address IDs are stored in the KeySettingsContext using keys like "CustomerAddress_" + prestaCustomer.id and "CustomerAddressLink_" + prestaCustomer.id. This allows the connector to link App4Sales customer IDs to their corresponding PrestaShop IDs for future operations.

Special Logic & Filters

**Address Update/Creation Logic:** When processing addresses, the connector first checks if an address with the same AddressLine1 already exists for the customer in PrestaShop. If a match is found, the existing address is updated; otherwise, a new address is created.
**Random Address Alias:** New addresses in PrestaShop are assigned an alias in the format "App4Sales address [random_hex_number]".

Related Settings & Prerequisites

The following connector settings influence the customer creation process:

**Id Shop:** This setting specifies the PrestaShop shop ID to which new customers will be associated.
**Application Key:** This is the API key used to authenticate requests to the PrestaShop API.
**Customer Code For Field:** If configured, this setting determines which field in the PrestaShop customer object maps to the App4Sales CustomerCode for identifying existing customers. If not set, the PrestaShop customer ID is used directly as the CustomerCode.

Known Limitations

The password for new PrestaShop customers is hardcoded, which might be a security concern or require manual updates in PrestaShop after creation.
The country code mapping relies on KeySettingsContext. If the mapping is incorrect or missing, the address country might not be correctly set in PrestaShop.
Error handling is general; specific PrestaShop validation errors are not explicitly parsed and returned to the App4Sales platform.
The code contains a TODO comment regarding country code handling, indicating a known area for improvement: "TODO find another way to handle these Country codes -- when we start using the PrestaShop connector again :-)".

PrestaShop - Create customer