SnelStart Connector - Send Order To Backoffice

The SendOrderToBackoffice function in the SnelStart connector is responsible for taking an App4Sales order and transmitting it to the SnelStart ERP system. It handles the conversion of order header information, order lines, and applies discounts before sending the order to SnelStart. Upon successful transmission, it updates the App4Sales order with the order number provided by SnelStart.

Data Source Configuration

The primary data source is the App4Sales order object. The connector also utilizes configuration settings from Administrations.ConnectorSettings.SnelStart (referred to as 'Settings'), country lookup data via LookupCountry, and pre-fetched SnelStart order templates (SnelStartOrderTemplate) to prepare the order for transmission. Data is pushed to the SnelStart API.

Data Mapping Table - Order Header

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
DeliveryAddress	`order.AlternateAddress`	Mapped via `GetDeliveryAddress` helper function.
InvoiceAddress	`order.Customer.Addresses`	Mapped via `GetInvoiceAddress` helper function. Prioritizes the main visit address.
Description	`order.Reference`	Direct mapping.
PaymentReference	`order.YourReference`	Direct mapping.
CustomerId	`order.Customer.CustomerCode`	The `CustomerCode` from App4Sales is used to retrieve the internal GUID from `CustomersContext`.
OrderDate	`order.OrderDate`	Direct mapping.
ModifiedOn	`DateTime.Now`	Set to the current timestamp when the order is sent.
VatType	`SnelStartVatType.Exclusief`	Hardcoded: Orders are always sent with prices excluding VAT to SnelStart.
OrderLines	`order.OrderLines`	Mapped via `GetOrderLines` helper function.
Type	`order.OrderType.ValueToBackoffice`	The `ValueToBackoffice` property of the App4Sales order type is parsed. If not specified, defaults to "Order". Can be split by ":" to determine a specific order template.
Notes	`order.Notes`	Direct mapping.
TemplateId	`order.OrderType.ValueToBackoffice`	Derived from the `ValueToBackoffice` property of the order type, if it contains a template name (e.g., "Order:MyTemplate"). It looks up the `Id` from the preloaded `SnelStartOrderTemplate` list based on the template description.

Data Mapping Table - Delivery Address

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Street	`order.AlternateAddress.AddressLine1`	Direct mapping from the alternate address.
PostalCode	`order.AlternateAddress.PostCode`	Direct mapping from the alternate address.
City	`order.AlternateAddress.City`	Direct mapping from the alternate address.
CountryId	`order.AlternateAddress.Iso2`	Looks up the SnelStart country ID based on the ISO2 code from the alternate address using `LookupCountry`. If not found, defaults to `Guid.Empty`.
ContactName	`order.AlternateAddress.EstablishmentName` or `order.ConsumerName`	If `EstablishmentName` is empty, it uses `ConsumerName` from the order.

Data Mapping Table - Invoice Address

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Street	`address.AddressLine1`	Direct mapping from the customer's main visit address.
PostalCode	`address.PostCode`	Direct mapping from the customer's main visit address.
City	`address.City`	Direct mapping from the customer's main visit address.
CountryId	`address.Iso2`	Looks up the SnelStart country ID based on the ISO2 code from the customer's main visit address using `LookupCountry`. If not found, defaults to `Guid.Empty`.
ContactName	`address.EstablishmentName` or `order.ConsumerName`	If `EstablishmentName` is empty, it uses `ConsumerName` from the order.

Data Mapping Table - Order Lines

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Description	`orderLine.Item.Description`, `orderLine.Instruction`	If `orderLine.Instruction` is not empty, the description is formatted as `"{Item.Description} ({Instruction})"`. Otherwise, it's just `Item.Description`.
ItemId	`orderLine.Item.InternalItemCode`	The `InternalItemCode` from App4Sales is parsed into a GUID.
Quantity	`orderLine.Quantity`	Direct mapping. If `Quantity` is null, defaults to 0.
UnitPrice	`orderLine.Item.SalesPrice` or `price`	If `settings.SendDiscountInsteadOfPrice` is true, uses `orderLine.Item.SalesPrice`. Otherwise, uses the calculated `price` (which includes customer discount compensation).
DiscountPercentage	`discount` or 100m or `null`	If `settings.SendDiscountInsteadOfPrice` is true, uses the calculated `discount` percentage. If `orderLine.Price` is 0, it explicitly sets the discount to 100% to ensure SnelStart doesn't use a default sales price. Otherwise, it's `null`.

Special Logic & Filters

Webshop Discount: order.ApplyWebshopDiscountOnOrderLines(Constants.Client.Portal4Sales) applies discounts specific to the webshop to each order line before the order is converted.
Order Type and Template Selection: The order.OrderType.ValueToBackoffice setting in App4Sales allows administrators to specify both the SnelStart order type (e.g., "Order", "Quote") and an optional SnelStart order template ID. The template is resolved from pre-fetched SnelStartOrderTemplate entities.
VAT Type: The VatType is always set to SnelStartVatType.Exclusief, indicating that all prices are sent excluding VAT to SnelStart. SnelStart is expected to handle the VAT calculation.
Customer Discount Compensation: The GetItemPrice helper function adjusts the order line price to compensate for customer discounts. This prevents SnelStart from applying the discount twice, as SnelStart treats customer discounts as "invoice discounts" rather than "order line discounts." Items identified as shipping costs are exempt from this discount compensation.
Error Handling: If the API Post operation to SnelStart encounters an error, the method returns a descriptive error string.
Order Number Update: Upon successful order creation in SnelStart, the returned SnelStart OrderNumber is used to update the corresponding App4Sales order's internal order ID.

Domain Specifics

Order Header Logic

Customer Selection: The App4Sales CustomerCode is used to retrieve the corresponding internal SnelStart customer ID (GUID) for the order.
Numbering: Order numbers are generated by SnelStart. The connector updates the App4Sales order with this external SnelStart order number.
Order-Type Routing: The ValueToBackoffice property of the App4Sales order type dictates the SnelStart order type (e.g., "Order", "Quote") and can optionally specify a SnelStart order template by using a colon-separated value (e.g., "Order:StandardTemplate").
Payment/Shipping Fields: The PaymentReference field is mapped from order.YourReference. Delivery and Invoice addresses are derived from alternate addresses and customer main addresses respectively, with country lookups and contact name logic applied.

Line & Pricing Logic

Source fields for items: The App4Sales orderLine.Item.InternalItemCode is used to identify the item in SnelStart. The line description is constructed from orderLine.Item.Description and optionally orderLine.Instruction.
Quantities: The orderLine.Quantity from App4Sales is directly mapped to the SnelStart order line quantity.
Prices: The unit price sent to SnelStart depends on the SendDiscountInsteadOfPrice setting. It can either be the original orderLine.Item.SalesPrice or a calculated price that has been adjusted to account for customer discounts to prevent double discounting.
Discounts: The DiscountPercentage is either explicitly calculated (if SendDiscountInsteadOfPrice is true) or set to 100% if the effective line price is zero to ensure SnelStart doesn't apply a default sales price.
VAT Adjustments: All order prices are transmitted as excluding VAT, with SnelStart responsible for applying the correct VAT rates.

Charges & Attachments

Freight/Payment Surcharges: Items configured as shipping costs within App4Sales are handled specifically; their prices are transferred without the customer discount compensation that applies to regular product lines. This ensures shipping costs are not inadvertently discounted.
PDF/JSON Exports: The current implementation of the SendOrderToBackoffice method does not include explicit logic for handling or transmitting PDF/JSON exports, signature images, or other attachments alongside the order to SnelStart.

Responses & Error Handling

Returned Order Numbers: After successfully posting an order to SnelStart, the ERP returns a unique order number. This number is then used to update the corresponding order record within the App4Sales system.
Duplicate Detection: The provided code does not explicitly contain logic for detecting duplicate orders before submission to SnelStart. Errors reported by the SnelStart API are directly returned by the connector.
Retry/Backoff Strategies: The SendOrderToBackoffice method does not implement automated retry or backoff strategies in case of transient API errors.

Related Settings & Prerequisites

Send discount instead of price: This setting (Administrations.ConnectorSettings.SnelStart.SendDiscountInsteadOfPrice) controls whether the connector sends the actual unit price or the original sales price along with a separate discount percentage for each order line.
Order Templates: If the ValueToBackoffice property of an App4Sales order type specifies a SnelStart template (e.g., "Order:MyTemplate"), that template must exist and be correctly configured within SnelStart for the order to be processed as intended.

Known Limitations

The connector explicitly sends all order prices to SnelStart excluding VAT. SnelStart is expected to handle the calculation and application of VAT based on its internal configuration.
There is no explicit functionality within the SendOrderToBackoffice method for transmitting attachments (such as PDFs, XML files, signature images, or other supplementary documents) to SnelStart alongside the order.
The order sending process does not include explicit logic for detecting and preventing duplicate order submissions to SnelStart.

SnelStart - Send order