Spector Connector - Send Order To Backoffice

This function syncs App4Sales orders to the Spector ERP system. It transforms an App4Sales order object into a Spector-specific format and transmits it via a POST request. Upon successful transmission, the Spector order reference is stored back in App4Sales.

Data Source Configuration

The connector retrieves order data directly from the App4Sales internal order object. Configuration settings within the Spector connector influence how certain fields are mapped and transformed before being sent to Spector.

Order Header Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Customer ID	`order.Customer.CustomerCode`	Maps the unique code of the customer.
Order Date	`order.OrderDate` or Current Date	Formatted as "yyyy-MM-dd". If the setting "Set Order Date As Delivery Date" is enabled, the current date is used; otherwise, the App4Sales order date is used.
Customer Reference	`order.YourReference`	Maps the customer's reference for the order. MaxLength: 70 characters.
Customer Order Reference	`order.Reference`	Maps the order's internal reference. MaxLength: 50 characters.
Currency	Derived	The currency is determined by looking up the price list currency associated with the customer, order type, and other criteria.
Delivery Date	`order.OrderDate` or null	Formatted as "yyyy-MM-dd". If the setting "Set Order Date As Delivery Date" is enabled, this field is not populated. Otherwise, the App4Sales order date is used.
Internal Comment	`order.Notes`, `order.Customer.ExtraData`	If the customer has extra data, it is prepended to the order notes with a newline separator. Otherwise, only order notes are sent.
External Delivery Method	`order.Customer.DeliveryMethod`	Maps the delivery method specified for the customer. MaxLength: 100 characters.
Published Comment	`settings.PublishedCommentOnOrder`	If the connector setting "Published Comment On Order" is configured, its value is sent.
Requirements	`settings.RequirementsOnOrder`	If the connector setting "Requirements On Order" is configured, its value is sent.
Stock Site ID	`settings.StockSiteId`	If the connector setting "Stock Site ID" is configured and is a valid integer, it is sent.
Our Reference User ID	`order.Salesrep`	The Sales Representative's ID is obtained from the App4Sales sales representative object and mapped as an integer user ID.

Order Line Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Line Number	Derived	Automatically assigned sequential line number, starting from 1. Required.
Article Number	`orderLine.ItemCode`	Maps the unique code of the item on the order line. Required. MaxLength: 50 characters.
Article Name	`orderLine.Description`	Maps the description of the item. Required. MaxLength: 130 characters.
Article Comment	`orderLine.Instruction`	Maps any specific instructions for the order line. MaxLength: 200 characters.
Add Article Comment	Derived	Set to true if `orderLine.Instruction` contains text, otherwise false.
Price Excl. VAT	`orderLine.Item?.SalesPrice` or `orderLine.Price`	Required. If the setting "Only Send Discount" is enabled and a discount is present, the item's sales price (without discount applied) is sent. Otherwise, the order line price, adjusted for any webshop discount percentage, is sent.
Number of Items	`orderLine.Quantity`	Required. The quantity of the item on the order line, converted to an integer.
VAT Percentage	`orderLine.Item?.VatPercentage` or 0	Required. If the customer is VAT liable, the item's VAT percentage is sent; otherwise, 0 is sent.
Discount	Derived	If the setting "Only Send Discount" is enabled, the calculated discount (original price discount plus webshop discount percentage) is sent, rounded to 4 decimal places. Otherwise, 0 is sent.

Special Logic & Filters

**Order Conversion:** The App4Sales Order object is converted into a Spector-specific SpecterOrderPost object, including a list of SpecterOrderLinePost objects, through the ConvertToNewOrder extension method. This method handles the primary mapping and transformations described above.
**Data Validation:** Both the SpecterOrderPost and SpecterOrderLinePost objects undergo validation checks (e.g., [Required] and [MaxLength] attributes) before being sent to the Spector API.
**Conditional Discount Sending:** The priceExclVAT and discount fields in order lines are populated conditionally based on the "Only Send Discount" setting, ensuring that either the pre-discount price with a separate discount value or the post-discount price is sent.
**Error Handling:** The GetResponseResult method processes the API response. If the Spector API returns a result code of 1 (success) or a non-fatal result code specified in the connector's logic, the operation is considered successful. Otherwise, an error message is generated combining a generic message with details from the Spector API response.

Domain Specifics

Order Header Logic

The order header captures essential customer and order metadata. The customer's unique code is mandatory. Dates are formatted consistently, with the option to use the current date as the delivery date. Customer and internal references are mapped, with length constraints applied. The order's currency is dynamically determined based on customer and price list configurations. Internal and external comments, as well as specific requirements, can be transmitted if configured. Stock site and sales representative user IDs are included if provided through connector settings or derived from App4Sales data.

Line & Pricing Logic

Each order line includes a sequential line number, a mandatory article number and name, and the quantity. Pricing is handled carefully: if the connector is configured to "Only Send Discount," the original item sales price is sent along with a separate discount amount; otherwise, the final price after any webshop discounts is sent. VAT percentages are included based on the customer's VAT liability and the item's configured VAT rate. Optional article-specific comments can also be included.

Charges & Attachments

The current implementation of SendOrderToBackoffice in the Spector connector does not explicitly handle separate charge lines, surcharges, or attachments like PDFs or images. These aspects are not mapped in the ConvertToNewOrder method. If required, these would need custom implementation or may be handled by other parts of the Spector integration not covered by this function.

Responses & Error Handling

After sending the order, the connector parses the response from the Spector API. If the API returns a success code, the Spector-generated order number (or code) is updated in the App4Sales order record. In case of errors, a detailed error message is constructed and returned, providing administrators with insight into why the order failed to send, including the Spector API's specific error message and code.

Related Settings & Prerequisites

**Set Order Date As Delivery Date:** (Boolean) When enabled, the current date is used for the Spector order date, and the Spector delivery date is not populated.
**Published Comment On Order:** (Text) Specifies a comment that will be sent as a published comment on the Spector order.
**Requirements On Order:** (Text) Specifies any special requirements that will be sent to Spector with the order.
**Stock Site ID:** (Numeric) The ID of the stock site in Spector to associate with the order. Must be a valid integer.
**Only Send Discount:** (Boolean) When enabled, the item's original sales price and a separate discount amount are sent. Otherwise, the final discounted price is sent as priceExclVAT.

Known Limitations

The current SendOrderToBackoffice implementation in the Spector connector does not explicitly map all available fields in the SpecterOrderPost DTO (e.g., ExternalOrderNo, PayTypeIdentifier, agent details, or SendOrderMail). These fields are either not utilized by this specific function or are expected to be populated by the Spector system itself. Additionally, there is no explicit handling for surcharges or attachments within this order sending process.

Spector - Send order