MultiversExtendedV3 - SendOrderToBackoffice
This document describes the process of sending an order from App4Sales to the MultiversExtendedV3 backoffice. The process involves mapping App4Sales order data to the Multivers sales order format, applying business logic and settings, and then creating the order in Multivers.
Data Source Configuration
The connector interacts with the Multivers API to create sales orders. The specific endpoints are determined by the repository implementations, but the primary objects involved are `MultiversV3SalesOrder` and `MultiversV3SalesOrderLine`.
Order Header Logic
The order header is constructed based on the App4Sales order and customer data. The following table details the mapping of fields.
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
CustomerCode | a4sOrder.Customer.CustomerCode | The customer code from the App4Sales order. |
OrderTypeCode | a4sOrder.OrderType.ValueToBackoffice | The order type from App4Sales. If not provided, it defaults to "NOR". |
OrderDate | DateTime.Now | The current date in "yyyy-MM-dd" format. |
CurrencyCode | a4sOrder.Customer.Currency | The currency from the App4Sales customer. |
CalculateVat | debtor.CalculateVat | The VAT calculation setting from the Multivers debtor. |
DiscountPercentage | a4sOrder.Customer.Discount | The customer's discount percentage. This is not sent if PutCustomerDiscountOnOrderlineDuringSendOrder is enabled. |
InvoiceAddressCode | organisation.Addresses | The first active invoice address from the Multivers organisation. |
Reference | a4sOrder.YourReference | The reference from the App4Sales order. Can be modified by the UseAlternateReference setting. |
InvoiceTypeCode | debtor.InvoiceTypeCode | The invoice type code from the Multivers debtor. |
PaymentConditionCode | debtor.PaymentConditionCode | The payment condition code from the Multivers debtor. |
SalesRepCode | debtor.RepresentativeCode | The sales representative code from the Multivers debtor. |
VatScenario | debtor.VatScenarioCode | The VAT scenario code from the Multivers debtor. |
OrderStatus | connectorSettings.OrderStatusForNewOrders | The order status for new orders. Defaults to "O" if not specified in the settings. |
OrderText / OrderInstruction | a4sOrder.Notes | The notes from the App4Sales order. The destination field depends on the SendOrderNoteInOrderInstructions setting. |
PaidOnlineAmount | paymentDetails.AmountPaid | The amount paid online, if payment details are available. |
PaidOnlineMerchantTransactionId | paymentDetails.PaymentId | The payment transaction ID, if payment details are available. |
Line & Pricing Logic
Order lines are mapped from the App4Sales order lines. The following table details the mapping for each line.
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
Discount | a4sOrderLine.Discount | The line discount. Not sent if DontSendOrderLineDiscountsToMultivers is enabled or if SendCustomPriceAsSalesPriceOnOrderLine is enabled. |
InstructionText | a4sOrderLine.Instruction | The instruction from the order line. Not sent if UseInstructionLineAsDeliveryDate is enabled. |
OrderLineNumber | (generated) | A sequential number for each order line. |
Price | a4sOrderLine.Price / originalPrice | The line price. The source depends on the DontSendOrderLineDiscountsToMultivers and SendCustomPriceAsSalesPriceOnOrderLine settings. |
PricePer | a4sOrderLine.Item.PurchasePackageSize | The purchase package size of the item. Defaults to 0 if not specified. |
QtyOrdered | a4sOrderLine.Quantity | The quantity of the item. Defaults to 0 if not specified. |
ProductDescrText | a4sOrderLine.Item.Description | The item description. Not sent if DontSendItemDescriptionToOrderlineNote is enabled. |
UnitCode | a4sOrderLine.Item.Unit | The unit of the item. |
ProductIdentifier.ProductCode | a4sOrderLine.Item.InternalItemCode | The internal item code. |
DeliveryAddress | a4sOrder.AlternateAddress / organisation.Addresses | The delivery address. Uses the alternate address if provided, otherwise determines the address based on connector settings. |
DeliveryAddressOneOff | connectorSettings.SetDeliveryAddressAsOneOff | A boolean value from the connector settings. |
VatGroup | a4sOrderLine.VatGroup | The VAT group from the order line. |
DeliveryDateAfter / DeliveryDateBefore | a4sOrderLine.Instruction / a4sOrder.OrderDate | The delivery date. Can be parsed from the instruction line if UseInstructionLineAsDeliveryDate is enabled. |
Special Logic & Filters
Alternate Address
If an alternate address is provided in the App4Sales order and it does not have an ID, it will be saved as a new address in Multivers. The new address ID is then used for the order.
Sales Contracts
If the UseSalesContracts setting is enabled, the connector will attempt to link order lines to existing sales contracts for the customer. If an order line's quantity exceeds the available quantity on a contract, the line will be split into multiple lines to consume the contract quantity and the remaining quantity will be placed on a new line without a contract reference.
Default Stock Problem Value
If a DefaultStockProblemValue is configured in the connector settings, this value will be set on all order lines.
Related Settings & Prerequisites
The following settings in the MultiversExtendedV3 connector configuration affect the SendOrder process:
UseSalesContracts: Enables the sales contract logic described above.
DefaultStockProblemValue: Sets a default stock problem value for order lines.
OrderStatusForNewOrders: Sets the status for new orders.
SendOrderNoteInOrderInstructions: Determines whether the order notes are sent in the `OrderText` or `OrderInstruction` field.
DontSendOrderLineDiscountsToMultivers: Prevents sending line discounts to Multivers.
SendCustomPriceAsSalesPriceOnOrderLine: Sends the custom price from App4Sales as the sales price on the order line.
OnlySendCustomDiscount: A setting passed to calculate price and discount.
DontSendItemDescriptionToOrderlineNote: Prevents sending the item description to the order line note.
UseInstructionLineAsDeliveryDate: Parses the delivery date from the order line instruction.
SetDeliveryLineOnOrderLines: When enabled, delivery lines are added to the sales order lines.
NeverSetDeliveryDateOnOrderlines: Prevents setting the delivery date on order lines.
UseAlternateReference: Modifies the logic for generating the order reference.
DefaultReference: A default reference value used when UseAlternateReference is enabled.
PutCustomerDiscountOnOrderlineDuringSendOrder: Determines if the customer discount is applied at the line level.
SetDeliveryAddressAsOneOff: Indicates if the delivery address should be marked as a one-off.