Multivers Extended V2 - Send Order

This process sends an order from App4Sales to the Multivers Extended V2 backoffice. It handles both regular orders and quotations based on the order type. The connector constructs a detailed order object, including header and line information, and sends it to the Multivers SOAP API. The backoffice then processes the order and returns an order number or an error message.

Data Source Configuration

The connector communicates with the Multivers Extended V2 SOAP API. The endpoint is constructed from the administration address and is typically in the format {address}/connector/connector.svc. The communication is done via the MaintainSalesOrdersV2 (for orders) and MaintainSalesQuotation (for quotations) SOAP methods.

Order Header Logic

The order header is constructed with the following logic:

Order vs. Quotation: If the OrderType.ValueToBackoffice is "quotation", the order is sent as a quotation. Otherwise, it is sent as a regular order.
Customer: The customer is retrieved from Multivers before sending the order. If the customer is not found, the process is aborted.
Reference: The order reference is set to YourReference if the FillReferenceWithYourReference setting is enabled or if the regular Reference is empty. Otherwise, the regular Reference is used.
Notes: The order notes are mapped to the OrderText field.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
CustomerId	`Order.Customer.CustomerCode`	The customer code from the App4Sales order.
InvoiceCode	`OrganisationV2.DebtorV2.InvoiceId`	The invoice ID of the debtor, retrieved from Multivers.
Mutation	N/A	Hardcoded to `OrderheaderMutationAction.Create`.
OrderDate	N/A	Set to the current date and time (`DateTime.Now`).
DeliveryAfter	`Order.OrderDate`	The delivery date from the order.
DeliveryBefore	`Order.OrderDate`	The delivery date from the order.
OrderType	`Order.OrderType.ValueToBackoffice`	The backoffice value of the order type.
Reference	`Order.YourReference` or `Order.Reference`	Uses `YourReference` if `FillReferenceWithYourReference` setting is true or `Reference` is empty.
ConfirmOrder	N/A	Hardcoded to `true`.
IsPartialDelivery	N/A	Hardcoded to `true`.
IsUrgent	N/A	Hardcoded to `true`.
VatScenario	`OrganisationV2.DebtorV2.VatScenario`	The VAT scenario of the debtor, retrieved from Multivers.
OrderText	`Order.Notes`	The notes from the App4Sales order.
AutoRecalcOrderDiscount	`Settings.DoNotAutoRecalcOrderDiscount`	Set to `!Settings.DoNotAutoRecalcOrderDiscount`.
DiscountPerc	`Order.WebshopDiscountPercentage`	The webshop discount percentage. Only set for Portal4Sales orders.
TermsOfPaymentId	`OrganisationV2.DebtorV2.TermsOfPayment`	The terms of payment of the debtor, retrieved from Multivers.
TermsOfDeliveryId	`OrganisationV2.DebtorV2.TermsOfDelivery`	The terms of delivery of the debtor, retrieved from Multivers.
RepresentitiveId	`OrganisationV2.DebtorV2.RepresentativeId`	The representative ID of the debtor, retrieved from Multivers.
BranchId	`OrganisationV2.DebtorV2.DebtorBranchesV2.FirstOrDefault().BranchId`	The branch ID of the debtor. Only set if `SetBranchIdOnOrder` setting is true.

Line & Pricing Logic

Each order line in the App4Sales order is converted to an order line for the Multivers API.

Item Validation: The connector checks if the item description contains an error message. If it does, the process is aborted.
Price Calculation: The sales price and discount are calculated using the GetCalculatedSalesPriceAndRoundedDiscount helper method. Prices and discounts are not sent if the DontSendPricesWithOrders setting is enabled.
Delivery Date: The delivery date can be set from the order line instruction if the SendInstructionAsDeliveryDate setting is enabled for App4SalesV2 orders.

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
ProductId	`OrderLine.Item.InternalItemCode`	The internal item code of the item on the order line.
InstructionText	`OrderLine.Instruction`	The instruction from the order line. It's sent as an empty string if `SendInstructionAsDeliveryDate` is enabled and the order is from App4SalesV2.
Price	Calculated	Calculated based on the order line's price and discount. Not sent if `DontSendPricesWithOrders` is true.
DiscountPerc	Calculated	Calculated based on the order line's price and discount. Not sent if `DontSendPricesWithOrders` is true.
UnitId	`OrderLine.Item.Unit`	The unit of the item on the order line.
QtyOrdered	`OrderLine.Quantity`	The quantity of the item on the order line.
Mutation	N/A	Hardcoded to `OrderlineMutationAction.Create`.
DeliveryAfter / DeliveryBefore	`OrderLine.Instruction` or `Order.OrderDate`	Parsed from the instruction if `SendInstructionAsDeliveryDate` is true for App4SalesV2 orders; otherwise, the order date is used.

Delivery Address Logic

The connector can add a delivery address to the order lines based on the SendAddressOnOrder setting.

If an alternate address is specified in the App4Sales order, this address is used. If the address does not exist in Multivers, a new address is created.
If no alternate address is specified, the connector uses an existing address from the customer in Multivers. It prioritizes the delivery address (type 'A'), then the invoice address (type 'F'), and finally the first address available. The UseDeliveryAddressBeforeInvoiceOnOrder setting can be used to enforce using the delivery address.

Responses & Error Handling

The connector handles responses and errors as follows:

Successful Order: If the order is successfully created in Multivers, the backoffice returns an order number. This number is then saved to the order in App4Sales.
Errors: If an error occurs, the Multivers API returns one or more error messages. The connector aggregates these messages and returns them as a single error string, prefixed with "ERROR:". If the error message from the backoffice is empty, a generic error message is returned.

Related Settings & Prerequisites

The following settings influence the behavior of the send order process:

FillReferenceWithYourReference: If enabled, the YourReference field is used as the order reference.
DoNotAutoRecalcOrderDiscount: If enabled, the order discount is not automatically recalculated by Multivers.
SetBranchIdOnOrder: If enabled, the branch ID is set on the order.
SendInstructionAsDeliveryDate: If enabled, the order line instruction is used as the delivery date for App4SalesV2 orders.
DontSendPricesWithOrders: If enabled, prices and discounts are not sent to Multivers.
SendAddressOnOrder: If enabled, a delivery address is added to the order lines.
UseDeliveryAddressBeforeInvoiceOnOrder: If enabled, the delivery address is used before the invoice address when selecting an address from the customer.

Known Limitations

The documentation does not describe any specific logic for handling surcharges or attachments. It is assumed that these are not supported by this connector when sending orders.

MultiversExtendedV2 - Send order