Multivers Extended V3 - Send Order
This document describes the process of sending an order from App4Sales to the Multivers Extended V3 backoffice. The process involves mapping App4Sales order data to a Multivers sales order object and sending it to the Multivers API. The behavior of the process can be customized using various connector settings.
Data Source Configuration
The connector sends orders to the Multivers V3 API. The specific endpoint is determined by the `_salesOrderRepository.CreateWithTemplate` method, which creates a `MultiversV3SalesOrder` entity.
Data Mapping Tables
Order Header
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
CustomerCode |
| The customer code from the App4Sales order. |
OrderTypeCode |
| The order type from the App4Sales order. If not provided, it defaults to "NOR". |
OrderDate |
| The current date in "yyyy-MM-dd" format. |
CurrencyCode |
| The currency from the customer associated with the order. |
CalculateVat |
| The value is taken from the debtor (customer) record in Multivers. |
DiscountPercentage |
| The customer's discount percentage. This is only applied if the setting "Put customer discount on orderline during send order" is disabled. |
InvoiceAddressCode |
| The ID of the first active invoice address found for the customer's organization. |
Reference |
| The reference field. If the setting "Combine Default Reference\Reference\Description1\Your Reference as order reference" is enabled, it concatenates several fields. Otherwise, it uses `Order.YourReference`. |
InvoiceTypeCode |
| The value is taken from the debtor (customer) record in Multivers. |
PaymentConditionCode |
| The value is taken from the debtor (customer) record in Multivers. |
SalesRepCode |
| The value is taken from the debtor (customer) record in Multivers. |
VatScenario |
| The value is taken from the debtor (customer) record in Multivers. |
OrderStatus | "O" | Defaults to "O" (Open). Can be overridden by the "Order status for new orders" setting. |
OrderText |
| The notes from the App4Sales order. This is used if the setting "Send order notes in on order instructions" is disabled. |
OrderInstruction |
| The notes from the App4Sales order. This is used if the setting "Send order notes in on order instructions" is enabled. |
PaidOnlineAmount |
| The amount paid online, if any. |
PaidOnlineMerchantTransactionId |
| The transaction ID from the online payment, if any. |
Order Line
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
Discount |
| The discount on the order line. The calculation is affected by the "Don't send order & quotation line discounts to Multivers" and "Send custom price in as the sales price on an order line" settings. |
InstructionText |
| The instruction text from the order line. Can be used as the delivery date if the "Use instruction line as delivery date" setting is enabled. |
OrderLineNumber | (sequential) | A sequential number for each order line. |
Price |
| The price of the item on the order line. The calculation is affected by the "Don't send order & quotation line discounts to Multivers" and "Send custom price in as the sales price on an order line" settings. |
PricePer |
| The purchase package size of the item. Defaults to 0 if not set. |
QtyOrdered |
| The quantity of the item ordered. |
ProductDescrText |
| The description of the item. Can be disabled with the "Don't send the Item description on the orderline note" setting. |
UnitCode |
| The unit of the item. |
ProductIdentifier.ProductCode |
| The internal item code. |
DeliveryAddress |
| The delivery address for the order line. It prioritizes the alternate address from the order, then falls back to the customer's delivery or invoice address based on settings. |
DeliveryAddressOneOff | (setting) | Controlled by the "Set the delivery address as One off so it won't get saved" setting. |
VatGroup |
| The VAT group from the App4Sales order line. |
DeliveryDateAfter / DeliveryDateBefore |
| The delivery date. If the setting "Use instruction line as delivery date" is enabled, it tries to parse the date from the line instruction. Otherwise, it uses the order date. Can be disabled with the "Never fill in the delivery date on orderlines" setting. |
StockProblem | (setting) | A default value can be set for all order lines using the "Default stock problem value" setting. |
Special Logic & Filters
Alternate Address
If an alternate address is provided on the App4Sales order and it does not have an existing `AddressId`, a new address is created in Multivers. This new address is then used as the delivery address for the order lines.
Sales Contracts
If the "Use sales contracts when creating a sales order" setting is enabled, the connector will try to match order lines to existing sales contracts for the customer. If the ordered quantity on a line is greater than the quantity available on a contract, the order line will be split. One line will be for the quantity on the contract, and a new line will be created for the remaining quantity.
Domain Specifics
Order Header Logic
The order header is built using a combination of data from the App4Sales order, the customer record in Multivers (debtor), and connector settings. The customer is identified by their `CustomerCode`. If the debtor or their associated organization cannot be found in Multivers, the process fails. The order status defaults to 'O' (Open) but can be customized. Address information is sourced from the customer's organization record in Multivers, with specific logic to select the invoice address.
Line & Pricing Logic
Order lines are created for each line in the App4Sales order. The mapping for price and discount is complex and depends on multiple connector settings. The connector can be configured to send the original price, a custom price, or no price at all. Similarly, discounts can be sent or omitted. The delivery date for each line can be parsed from the instruction field or defaulted to the order date. A default stock problem value can also be applied to all lines.
Charges & Attachments
The current implementation does not explicitly handle charges or surcharges as separate lines. However, payment details, including the paid amount, are mapped to the order header. The logic for handling attachments is present in the `OrdersService` but is not directly part of the `SendOrderToBackoffice` flow for creating the order. Attachments are retrieved separately.
Responses & Error Handling
Upon successful creation of the order in Multivers, the connector returns the new Multivers order ID. If the customer (debtor) is not found in Multivers, the process logs an error and returns `null`. If a new alternate address is provided but cannot be saved, an exception is thrown. The API call to create the order is wrapped in a template that may handle further error scenarios, but the details of this are not visible in the provided code.
Related Settings & Prerequisites
The following settings in the connector configuration can affect the behavior of the send order process:
UseSalesContracts: Enables the sales contract logic described above.DefaultStockProblemValue: Sets a default value for the `StockProblem` field on all order lines.PutCustomerDiscountOnOrderlineDuringSendOrder: If true, the customer-level discount is applied to each order line instead of the order header.DontSendOrderLineDiscountsToMultivers: If true, no discount information is sent on the order lines.SendCustomPriceAsSalesPriceOnOrderLine: If true, the `Price` from the App4Sales order line is sent as the final price, ignoring discounts.UseInstructionLineAsDeliveryDate: If true, the connector will attempt to parse a delivery date from the order line's instruction text.NeverSetDeliveryDateOnOrderlines: If true, the delivery date will not be set on order lines.SendOrderNoteInOrderInstructions: If true, the order notes are sent in the `OrderInstruction` field instead of `OrderText`.UseAlternateReference: If true, a composite reference is created from several order fields.SetDeliveryAddressAsOneOff: If true, the delivery address is marked as a one-off address and will not be saved in the customer's address book in Multivers.OrderStatusForNewOrders: Allows overriding the default order status of "O".DontSendItemDescriptionToOrderlineNote: If true, the item description is not sent on the order line.UseDeliveryAddressBeforeInvoiceOnOrder: If true, the connector will prioritize using a delivery address over an invoice address for the order.SetDeliveryLineOnOrderLines: If true, adds delivery lines to the order lines.