PrestaShop Connector - Send Order to Backoffice

This function is responsible for transferring App4Sales orders to the PrestaShop e-commerce platform. It prepares the order header and order lines based on the App4Sales order object and sends them to PrestaShop via its API. The process involves retrieving customer, address, and carrier information from PrestaShop and then creating a cart and an order within PrestaShop.

Data Source Configuration

The connector retrieves various pieces of information from PrestaShop via its API using the GetResultFromApi method. This includes:

Carriers: Fetched from the 'carriers' endpoint to determine the default carrier for the order.
Customer Details: Retrieved from the 'customers' endpoint using either the App4Sales customer code directly or a mapped PrestaShop customer ID stored in KeySettingsContext (key prefix PrestaShop_CustomerCode_).
Customer Address: The delivery and invoice address ID is retrieved from KeySettingsContext (key prefix CustomerAddress_), which links an App4Sales customer to a PrestaShop address.
Current Currency: The default currency ID is retrieved from KeySettingsContext with the key CurrentCurrency.
Language: The customer's language ID is retrieved from the PrestaShop customer details.
Product ID: For each order line, the PrestaShop product ID is obtained. If the setting ProductReferenceAsItemCode is enabled, the product ID is looked up in KeySettingsContext (key prefix PrestaShop_ArtReference_) using the App4Sales item code. Otherwise, the App4Sales item code is used directly as the PrestaShop product ID.

Data Mapping Tables

PrestaShop Cart Object Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
id_customer	App4Sales Order.Customer.CustomerCode / PrestaShop customer ID	Mapped from App4Sales CustomerCode. If `Settings.CustomerCodeForField` is set, the PrestaShop customer ID is retrieved from `KeySettingsContext` using the key prefix `PrestaShop_CustomerCode_` and the App4Sales CustomerCode.
id_shop	PrestaShop customer document (`prestashop/customer/id_shop`)	Retrieved from the customer information fetched from PrestaShop.
id_shop_group	PrestaShop customer document (`prestashop/customer/id_shop_group`)	Retrieved from the customer information fetched from PrestaShop.
id_currency	`KeySettingsContext` (`CurrentCurrency`)	Retrieved from `KeySettingsContext`. This value represents the default currency ID configured in the connector.
id_lang	PrestaShop customer document (`prestashop/customer/id_lang`)	Retrieved from the customer information fetched from PrestaShop.
secure_key	PrestaShop customer document (`prestashop/customer/secure_key`)	Retrieved from the customer information fetched from PrestaShop.
id_address_delivery	`KeySettingsContext` (`CustomerAddress_`)	Retrieved from `KeySettingsContext` using the key prefix `CustomerAddress_` and the App4Sales CustomerCode. This ID points to the delivery address in PrestaShop. Also used for `id_address_invoice`.
id_address_invoice	`KeySettingsContext` (`CustomerAddress_`)	Same as `id_address_delivery`.
id_carrier	PrestaShop carriers API response	The ID of the first carrier found from the PrestaShop 'carriers' API endpoint.

PrestaShop Cart Row Mapping (for each Order Line)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
id_product	App4Sales OrderLine.Item.ItemCode / PrestaShop product ID	Mapped from App4Sales ItemCode. If `Settings.ProductReferenceAsItemCode` is true, the PrestaShop product ID is retrieved from `KeySettingsContext` using the key prefix `PrestaShop_ArtReference_` and the App4Sales ItemCode. Otherwise, the App4Sales ItemCode is used directly.
id_product_attribute	Hardcoded	Always set to `0`.
quantity	App4Sales OrderLine.Quantity	Directly mapped from the App4Sales order line quantity, cast to an integer.

PrestaShop Order Object Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
id_address_delivery	`KeySettingsContext` (`CustomerAddress_`)	Retrieved from `KeySettingsContext` using the key prefix `CustomerAddress_` and the App4Sales CustomerCode. This ID points to the delivery address in PrestaShop. Also used for `id_address_invoice`.
id_address_invoice	`KeySettingsContext` (`CustomerAddress_`)	Same as `id_address_delivery`.
id_cart	Derived	The ID of the newly created PrestaShop cart.
id_currency	`KeySettingsContext` (`CurrentCurrency`)	Retrieved from `KeySettingsContext`. This value represents the default currency ID configured in the connector.
id_lang	PrestaShop customer document (`prestashop/customer/id_lang`)	Retrieved from the customer information fetched from PrestaShop.
id_customer	App4Sales Order.Customer.CustomerCode / PrestaShop customer ID	Mapped from App4Sales CustomerCode. If `Settings.CustomerCodeForField` is set, the PrestaShop customer ID is retrieved from `KeySettingsContext` using the key prefix `PrestaShop_CustomerCode_` and the App4Sales CustomerCode.
id_carrier	PrestaShop carriers API response	The ID of the first carrier found from the PrestaShop 'carriers' API endpoint.
module	`Settings.Module` / Hardcoded	If `Settings.Module` is not empty, its value is used. Otherwise, it defaults to `"cheque"`.
payment	`Settings.OrderPayment` / Hardcoded	If `Settings.OrderPayment` is not empty, its value is used. Otherwise, it defaults to `"Payments by check"`.
total_paid_real	Hardcoded	Always set to `0`.
total_paid_tax_excl	Hardcoded	Always set to `0`.
total_paid_tax_incl	Hardcoded	Always set to `0`.
total_products	Hardcoded	Always set to `0`.
total_products_wt	Hardcoded	Always set to `0`.
conversion_rate	Hardcoded	Always set to `1`.
secure_key	PrestaShop customer document (`prestashop/customer/secure_key`)	Retrieved from the customer information fetched from PrestaShop.
id_shop	PrestaShop customer document (`prestashop/customer/id_shop`)	Retrieved from the customer information fetched from PrestaShop.
id_shop_group	PrestaShop customer document (`prestashop/customer/id_shop_group`)	Retrieved from the customer information fetched from PrestaShop.
current_state	Hardcoded	Initially set to `1` (presumably for creation), then updated to `9` after creation.

PrestaShop Order Row Mapping (for each Order Line)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
product_id	App4Sales OrderLine.Item.ItemCode / PrestaShop product ID	Mapped from App4Sales ItemCode. If `Settings.ProductReferenceAsItemCode` is true, the PrestaShop product ID is retrieved from `KeySettingsContext` using the key prefix `PrestaShop_ArtReference_` and the App4Sales ItemCode. Otherwise, the App4Sales ItemCode is used directly.
product_attribute_id	Hardcoded	Always set to `0`.
quantity	App4Sales OrderLine.Quantity	Directly mapped from the App4Sales order line quantity, cast to an integer.

Special Logic & Filters

Customer Address Validation: The connector checks if a valid address ID exists for the customer in KeySettingsContext. If not, the order send process is aborted, and an error message "ERROR: Customer needs a valid address" is returned.
Customer and Product ID Resolution: Customer and product IDs for PrestaShop are resolved using KeySettingsContext based on connector settings (Settings.CustomerCodeForField and Settings.ProductReferenceAsItemCode). This allows for mapping App4Sales codes to PrestaShop specific IDs.
Cart and Order Creation: The process involves two main steps: first, a PrestaShop cart object is created using CartFactory.Add, and then an order object is created using OrderFactory.Add, referencing the created cart.
Order State Update: After an order is initially created with current_state = 1, it is immediately updated to current_state = 9. The exact meaning of these states (e.g., 'pending' to 'completed') would depend on PrestaShop's internal state definitions.
Order Number Update: Upon successful creation of the order in PrestaShop, the returned PrestaShop order ID is saved back into the App4Sales system using OrdersContext.Instance.UpdateOrderNumber.

Domain Specifics / Extension Section

Order Header Logic

Customer information (ID, shop, shop group, language, secure key) is sourced directly from PrestaShop's customer API endpoint, using the App4Sales customer code to identify the corresponding PrestaShop customer. The delivery and invoice address IDs are retrieved from the KeySettingsContext, which must contain a valid PrestaShop address ID linked to the App4Sales customer. The currency ID is also obtained from the KeySettingsContext. The connector selects the first carrier returned by the PrestaShop carriers API as the default carrier for the order. Payment module and method are configured via connector settings or default to "cheque" and "Payments by check" respectively.

Line & Pricing Logic

Each App4Sales order line is translated into a PrestaShop cart row and order row. The PrestaShop product ID is resolved based on the App4Sales item code, potentially using a lookup in KeySettingsContext if ProductReferenceAsItemCode is enabled. The quantity is directly mapped. No specific pricing logic (customer price list, action price, promotional override) or discount aggregation, rounding rules, tax/VAT recalculation, or currency conversions are handled within this method for the order lines themselves, as total_paid_real, total_paid_tax_excl, total_paid_tax_incl, total_products, and total_products_wt are hardcoded to 0.

Charges & Attachments

There is no explicit logic within the SendOrderToBackoffice method to handle charges (freight, payment fees, coupons) or attachments (PDF, signature images, custom payloads). These would not be transferred to PrestaShop through this specific function.

Responses & Error Handling

If the order is successfully created in PrestaShop, the returned PrestaShop order ID is used as the order number and stored in the App4Sales system. In case of an exception during the process, a generic error message including the exception details is returned, prefixed with "ERRORORDERNR". A specific error is returned if the customer does not have a valid address stored in the KeySettingsContext.

Related Settings & Prerequisites

For this function to operate correctly, the following settings and prerequisites must be in place:

Application key: A valid PrestaShop API key (Settings.Applicationkey) for authentication with the PrestaShop API.
PrestaShop Admin Address: The base URL of the PrestaShop administration interface (AdministrationSession.CurrentSession.Administration.Address).
Customer Code for Field: (Settings.CustomerCodeForField) If specified, this setting determines which field in the PrestaShop customer object is used as the customer code. This also influences how the PrestaShop customer ID is retrieved from KeySettingsContext (PrestaShop_CustomerCode_).
Product Reference as Item Code: (Settings.ProductReferenceAsItemCode) If true, the connector uses the PrestaShop product reference as the item code and performs a lookup in KeySettingsContext (PrestaShop_ArtReference_) to get the actual PrestaShop product ID. Otherwise, the App4Sales item code is used directly as the PrestaShop product ID.
Module: (Settings.Module) Specifies the PrestaShop payment module to use. Defaults to "cheque" if not set.
Order Payment: (Settings.OrderPayment) Specifies the payment method description for the order. Defaults to "Payments by check" if not set.
Multi Order Rows: (Settings.MultiOrderRows) This setting is passed to the OrderFactory.Add and OrderFactory.Update methods, likely influencing how multiple order lines are handled.
KeySettingsContext Entries: The KeySettingsContext must contain the following entries:
- PrestaShop_CustomerCode_[App4SalesCustomerCode]: Maps App4Sales customer codes to PrestaShop customer IDs (if Settings.CustomerCodeForField is used).
- CustomerAddress_[App4SalesCustomerCode]: Stores the PrestaShop address ID for a given App4Sales customer code. This is crucial for successful order placement.
- PrestaShop_ArtReference_[App4SalesItemCode]: Maps App4Sales item codes to PrestaShop product IDs (if Settings.ProductReferenceAsItemCode is true).
- CurrentCurrency: The default currency ID used for orders.

Known Limitations

Limited Pricing Detail: The connector does not transfer detailed pricing information (like individual unit prices, discounts, or tax breakdowns) from App4Sales to PrestaShop. The total_paid_real, total_paid_tax_excl, total_paid_tax_incl, total_products, and total_products_wt fields in the PrestaShop order are hardcoded to 0.
No Surcharges or Attachments: There is no functionality to send order surcharges (e.g., freight, payment fees) or attachments (e.g., PDFs, signatures) to PrestaShop.
Single Carrier: Only the first carrier retrieved from the PrestaShop API is used, without any logic for selecting a specific carrier based on App4Sales order details.
No Product Attributes: The id_product_attribute for order lines is hardcoded to 0, meaning product variations or attributes are not supported by this send order function.
Generic Error Handling: Beyond checking for a valid customer address, error handling is generic, returning a general error message on exceptions without detailed insights into the cause of failure from the PrestaShop API.

PrestaShop - Send order