King - Send Order

This document describes the process of sending an order from App4Sales to the King backoffice. The connector generates an XML file with the order data and uploads it to a specified FTP server location. The process is primarily one-way; it sends the order data but does not process a response from King to confirm the order was successfully imported.

Data Source Configuration

The order data is transmitted as an XML file to an FTP server. The configuration for the FTP server is maintained in the App4Sales administration settings for the connector.

Transport Protocol: FTP
File Format: XML
File Name Convention: [OrderNr].xml
FTP Path: The file is uploaded to the /orders/ directory within the folder specified in the FolderName setting.

Data Mapping

The following tables detail the mapping of App4Sales order fields to the generated XML file. The XML generation is handled by the core App4Sales framework, and this documentation assumes a standard App4Sales order XML structure.

Order Header

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Order Number	`Order.OrderNr`	If the order number is not already present, a new one is generated using the `CalculateOrderNumber` logic from the Portal Server Provider.
Customer	`Order.Customer`	For dropshipment orders (when `CreateOrderDropshipmentCustomerInKing` is enabled), a new customer is created in King using the dropshipment address, and this new customer is associated with the order. The new customer may be assigned to a specific debtor group if `DebtorGroupForDropshipmentCustomers` is set.
Reference	`Order.Reference`	If the `ReplaceOurReferenceWithSalesRep` setting is enabled, the value of this field is replaced with the username of the sales representative (`Order.Salesrep`).
Notes	`Order.Notes`	If the `PlaceOrderNumberBeforeTheOrderNotes` setting is enabled, the order number is prepended to the notes. If the notes are empty, they will be populated with the order number.

Order Lines

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Description	`OrderLine.Description`	If the `MergeInstructionAndDescriptionInTheOrder` setting is enabled, the instruction from the order line (`OrderLine.Instruction`) is appended to the description.
Discount	`OrderLine.Discount`	Two settings control the discount logic: If `CalculateTotalDiscountForOrderLine` is enabled, the discount percentage is recalculated. It is derived from the difference between the original item price and the price on the order line. The original price is queried from the database based on the customer's price settings. If `DontSendDiscountToBackoffice` is enabled, the discount is set to 0, and the order line price is recalculated to reflect the original price before the discount was applied.
Price	`OrderLine.Price`	If the `DontSendDiscountToBackoffice` setting is enabled, this price is recalculated to be the price before discount was applied.

Domain Specifics

Order Header Logic

The connector prepares the order header data before generating the XML. It ensures an order number exists, handles dropshipment scenarios by potentially creating new customers in King, and can modify the order reference and notes based on connector settings.

Line & Pricing Logic

The connector can modify order line data. It can merge the instruction field into the item description. It also has two distinct modes for handling discounts: either recalculating the discount based on the original price or removing the discount entirely and adjusting the price accordingly. This logic is controlled by connector settings and is intended to accommodate different pricing and discount strategies in the King backoffice.

Charges & Attachments

The analyzed code does not contain specific logic for handling surcharges or attachments. Any such data would need to be part of the standard order object and be handled by the generic `GenerateOrderXml` method.

Responses & Error Handling

The connector's primary success metric is the successful upload of the XML file to the FTP server. It does not wait for or process any response from King. If the FTP upload fails, the error is logged, and the order number that was assigned is reset in the App4Sales database to allow for a retry. The error message from the FTP exception is returned to the caller.

Related Settings & Prerequisites

The following settings in the App4Sales administration panel influence the behavior of the send order process:

CreateOrderDropshipmentCustomerInKing: If enabled, for dropshipment orders, a new customer is created in King using the order's dropshipment details.
DebtorGroupForDropshipmentCustomers: Specifies the debtor group to be used for newly created dropshipment customers in King.
ReplaceOurReferenceWithSalesRep: If enabled, the "Our Reference" field on the order is populated with the sales representative's username.
PlaceOrderNumberBeforeTheOrderNotes: If enabled, the order number is prepended to the order notes.
MergeInstructionAndDescriptionInTheOrder: If enabled, the content of the 'Instruction' field on an order line is appended to the 'Description' field.
CalculateTotalDiscountForOrderLine: If enabled, the discount percentage for each order line is recalculated based on the difference between the original item price and the price on the order.
DontSendDiscountToBackoffice: If enabled, the discount on the order lines is set to 0, and the price is adjusted to compensate.
FolderName: Specifies the base folder on the FTP server where the order XML files are uploaded.

Known Limitations

The integration is one-way. The connector sends the order to King but does not verify that the order was successfully processed by King.
Error handling is limited to FTP connectivity and write permissions. Any data validation errors within King will not be caught by the connector.

King - Send order