Skip to main content

ExactOnlinePremium - Send order

ExactOnlinePremium Connector - Send Order to Backoffice This document describes how the ExactOnlinePremium connector processes and t...

Updated over a week ago

ExactOnlinePremium Connector - Send Order to Backoffice

This document describes how the ExactOnlinePremium connector processes and transmits App4Sales orders (including sales orders, invoices, quotations, and return orders) to the Exact Online ERP system. It details the business logic involved in preparing order headers and lines, applying pricing and discounts, handling various addresses and contacts, and managing responses and errors.

Order Header Logic

The connector determines the order type and routes the order to the appropriate Exact Online endpoint. It populates order header details based on App4Sales order data and connector settings.

App4Sales Field

Source Field (API/Excel/DB)

Logic/Notes

Order Number (YourRef)

Order.Reference or Order.YourReference

Copied from model.Reference if Settings.UseReferenceAsYourRef is true, otherwise from model.YourReference.

Send Date

Order.OrderDate or DateTime.Now

If Settings.UseDateAsDeliveryDate is true, uses the current date and time (DateTime.Now), otherwise model.OrderDate.

Ordered By (Customer GUID)

Order.CustomerGuid

Directly mapped.

Delivery Date (Sales Order)

Order.OrderDate

If Settings.UseDateAsDeliveryDate is true, uses model.OrderDate, otherwise null.

Delivery Address ID

Derived from App4Sales Addresses, or new Address creation

Derived from AddressesContext.Instance.GetAddressIdAsGuid or new address creation if Settings.CreateAlternateAddressAtCustomer is enabled.

Invoice To Customer ID

Order.Customer.InvoiceTo or new Address creation

Derived from Order.Customer.InvoiceTo or new invoice address creation if Settings.CreateInvoiceAddress is enabled.

Remarks

Order.Reference or Order.Notes

Conditional: Uses model.Reference if Settings.UseNotesAsDescription is true, otherwise model.Notes.

Deliver To (Customer GUID)

dropshipmentCustomer or Order.CustomerGuid

Uses dropshipmentCustomer if a dropshipment customer was created, otherwise model.CustomerGuid.

Currency

Price List Currency or Connector Setting

Derived from the price list currency if Settings.UseCurrencyFromPriceList is true, otherwise from Settings.CurrencyCodeIso if Settings.VariantCurrency is true.

Description

Composed from various App4Sales fields and settings

Composed from model.Notes or model.Reference. Prepended with order type name if Settings.AddOrderTypeToDescription is true. Prepended with "[Dropshipment]" if dropshipment is active. If empty and Settings.FillDescriptionWithApp4SalesOrderWhenEmpty is true, defaults to "App4Sales order by {Salesrep}".

Created Date

DateTime.Now

Hardcoded to current date and time.

Salesperson

Account Manager User ID

Derived from the Account Manager associated with the order's sales representative.

Shipping Method

Order.DeliveryMethod.Code or Settings.ShippingMethodCode

Derived from the order's delivery method code or the connector's default shipping method code.

Ordered By Contact Person

Order.ContactPerson.FullName

Derived from the contact person's full name associated with the order. If the GUID is empty, it is set to null.

Deliver To Contact Person

deliveryContactPersonId

Derived from dropshipment customer creation or alternative contact person creation.

Discount

Order.WebshopDiscountPercentage

If greater than 0, model.WebshopDiscountPercentage / 100, otherwise null.

Warehouse ID

Warehouse from Connector Settings or Order Type

Derived from Settings.WarehouseForOrder, sales representative's warehouse, or order type's warehouse code.

Warehouse Code

Warehouse from Connector Settings or Order Type

Derived from Settings.WarehouseForOrder, sales representative's warehouse, or order type's warehouse code.

Sales Channel

Settings.SalesChannelCodeToUseForOrders

Derived from the sales channel code specified in connector settings.

Status

Hardcoded (e.g., 'OrderOpen', 'InvoiceOpen', 'QuotationOpen')

For Sales Orders: Constants.OrderStatus.OrderOpen.
For Sales Invoices: Constants.OrderStatus.InvoiceOpen.
For Sales Quotations: Constants.OrderStatus.QuotationOpen.

Type (Invoice)

Order.OrderType.ValueToBackoffice

Determines if it's a direct sales invoice or a regular sales invoice/credit note based on OrderType.GetInvoiceTypeId().

Line & Pricing Logic

Each order line from App4Sales is transformed into a corresponding Exact Online order, invoice, or quotation line. Pricing, discounts, and delivery dates are calculated based on various settings.

App4Sales Field

Source Field (API/Excel/DB)

Logic/Notes

Description

OrderLine.Description

If Settings.SetItemDescriptionWhenSendingOrder is true, the order line description is mapped, otherwise it is null.

Line Number (Sequence)

OrderLine.Sequence

Directly mapped.

Item GUID

OrderLine.Item.InternalItemCode

Parsed to GUID.

Net Price

OrderLine.Price, VAT settings, discount settings

Calculated based on OrderLine.Price, adjusted for VAT liability (Settings.NetPriceBasedOnVatLiability), VAT inclusion (Settings.NetPriceIncludingVat), and whether discount is sent without price (Settings.UseDiscountWithoutPriceOnOrder). Rounded to two decimals if Settings.RoundOrderLinePricesToTwoDecimals is true.

Unit Price

OrderLine.Price or original item price

If Settings.SetUnitPrice is true, uses OrderLine.Price. If Settings.SetOriginalPriceOnUnitPrice is true, uses the original item price from ItemPricesContext.

Quantity

OrderLine.Quantity

Directly mapped.

Delivery Date (Line)

OrderLine.Instruction or Order.OrderDate

If Settings.UseDateAsDeliveryDate is true, derived from parsing OrderLine.Instruction or falling back to Order.OrderDate. Otherwise, null.

Amount (FC)

OrderLine.Price

If Settings.VariantCurrency is true, uses OrderLine.Price, otherwise null.

Notes

OrderLine.Instruction

The instruction from the order line. If empty, then null.

Discount

OrderLine.Discount or OrderLine.DiscountFromOriginalPrice

Calculated by dividing by 100. Uses OrderLine.DiscountFromOriginalPrice if Settings.UseDiscountWithoutPriceOnOrder is true, otherwise OrderLine.Discount. Falls back to customer discount if no line discount is specified when Settings.UseDiscountWithoutPriceOnOrder is true.

Cost Center

Settings.CostCenterCodeForOrdersBySalesRep or Settings.CostCenterCodeForOrders

Derived from the sales representative's cost center or the connector's default cost center.

Cost Unit

Settings.CostUnitForOrdersBySalesRep or Settings.CostUnitForOrders

Derived from the sales representative's cost unit or the connector's default cost unit.

Price List (Line)

PriceList.ExternalId

Used if Settings.DeterminePriceListOnOrderLineWhenPriceOrDiscountIsNotChanged is true and specific conditions are met (no discount, price matches original).

Quantity Delivered

OrderLine.Quantity

Directly mapped.

GL Account (Invoice Line)

Settings.GLAccountCodeForOrders

Derived from the GL account code specified in connector settings. Only for Invoice Lines.

Charges & Attachments

The connector handles additional charges as part of order lines. It also supports sending attachments related to orders.

Return Orders - Charges and Attachments

App4Sales Field

Source Field (API/Excel/DB)

Logic/Notes

Delivered To (Customer GUID)

order.CustomerGuid

Directly mapped.

Warehouse

order.OrderType.WarehouseCode or from Goods Deliveries

Determined from the order's preferred warehouse or the warehouse associated with the original goods delivery.

Item GUID

ExactOnlineGoodsDeliveryLine.Item

Derived from the original goods delivery line item.

Good Delivery Line ID

ExactOnlineGoodsDeliveryLine.Id

The ID of the original goods delivery line associated with the return.

Received Quantity

ExactOnlineGoodsDeliveryLine.QuantityDelivered

The quantity originally delivered for the specific line.

Planned Return Quantity

OrderLine.Quantity

The quantity specified for return in the App4Sales order line.

Create Credit Note

Settings.AlwaysCreateCreditNoteForReturnOrders

Set to 1 (true) if Settings.AlwaysCreateCreditNoteForReturnOrders is true, otherwise 0 (false).

Responses & Error Handling

After sending an order, the connector processes the response from Exact Online to update the App4Sales database and provide feedback.

  • Order Number/Invoice Number/Quotation Number: The ERP-generated number is stored back into the App4Sales database (OrdersContext.Instance.UpdateOrderNumber).

  • External Order ID: The Exact Online internal ID for the order is stored in App4Sales.

  • Duplicate Order Detection: Before sending, the connector checks if an order with the same App4Sales Order ID already exists in Exact Online. If it does, the existing ERP order number is used, and the order is marked as delivered in App4Sales without creating a new one.

  • Rate Limit Handling: TooManyRequestsException from the Exact Online API is caught and logged, but the process continues. This means order existence checks might be skipped under heavy load.

  • Error Logging: Detailed errors from API calls (RestException) and general exceptions are logged, and an error message is returned to App4Sales.

  • Stock Synchronization: After a sales order is successfully sent, if the last stock synchronization was more than 15 minutes ago, a full stock synchronization is triggered (AdministrationSession.CurrentSession.CustomerPortalProvider.SyncFullStock()).

  • Quotation Line Delivery Date: For quotations, if Settings.UseDateAsDeliveryDate is true, the quotation header's delivery date is updated to reflect the latest delivery date among its lines.

Domain Specifics / Extension Section

Order Header Logic

  • Customer Selection: The OrderedBy and DeliverTo fields are primarily mapped from Order.CustomerGuid. For dropshipments, a new customer might be created, and its GUID used for DeliverTo.

  • Numbering: The YourRef field is populated from either Order.Reference or Order.YourReference based on the Settings.UseReferenceAsYourRef.

  • Order-Type Routing: The SendOrderToBackoffice method acts as a dispatcher, calling SendSalesOrderToExactOnline, SendSalesInvoiceToExactOnline, SendSalesQuotationToExactOnline, or SendReturnOrderToExactOnline based on the Order.OrderType.

  • Payment/Shipping Fields:

    • Shipping Method: Determined from Order.DeliveryMethod.Code or Settings.ShippingMethodCode.

    • Contact Persons: OrderedByContactPerson is mapped from the order's contact person. DeliverToContactPerson is derived from alternative contact person creation if enabled via Settings.CreateAndLinkAlternativeContactPerson and Order.ConsumerName is present.

Line & Pricing Logic

  • Source fields for items: OrderLine.Item.InternalItemCode is used to identify the item.

  • Quantities: OrderLine.Quantity is directly mapped.

  • Prices: Unit prices are derived from OrderLine.Price, or the original item price from ItemPricesContext based on Settings.SetUnitPrice or Settings.SetOriginalPriceOnUnitPrice. Net prices are calculated considering VAT settings.

  • Discount Adjustments: Discounts are applied from OrderLine.Discount or OrderLine.DiscountFromOriginalPrice. The Settings.UseDiscountWithoutPriceOnOrder influences whether the discount is sent with or without the net price.

  • VAT Adjustments: Net price calculations take into account Settings.NetPriceIncludingVat and Settings.NetPriceBasedOnVatLiability, adjusting for VAT percentages and customer VAT liability.

Charges & Attachments

  • Freight/Payment Surcharges: Surcharges are implicitly handled as part of the total order value or integrated into line items through the pricing logic. Explicit surcharge lines are not directly observed as a separate mapping.

  • PDF/JSON Exports: The connector's OptA4SGetOrderAttachments and OptA4SGetInvoiceAttachments methods can retrieve document attachments from Exact Online. The OptA4SGetAttachment method fetches the actual attachment data.

  • Signature/Image Uploads: No explicit mapping for signature or image uploads to Exact Online is identified within the send order process.

Responses & Error Handling

  • Returned Order Numbers: Upon successful submission, the Exact Online order/invoice/quotation number is returned and updated in the App4Sales database.

  • Duplicate Detection: The connector attempts to prevent duplicate orders by checking for existing orders in Exact Online with the same App4Sales Order ID before creating a new one.

  • Retry/Backoff Strategies: No explicit retry or backoff strategies are observed within the immediate scope of the send order methods. Rate limit exceptions are logged, but processing continues.

Related Settings & Prerequisites

The following connector settings influence the behavior of sending orders to Exact Online:

  • Use notes as description: (Settings.UseNotesAsDescription) - Determines whether order notes or reference are used for the Exact Online description and remarks.

  • Use reference as your ref: (Settings.UseReferenceAsYourRef) - Determines whether Order.Reference or Order.YourReference is mapped to the Exact Online YourRef field.

  • Add order type to description: (Settings.AddOrderTypeToDescription) - If true, the order type name is prepended to the Exact Online order description.

  • Fill description with App4Sales order when empty: (Settings.FillDescriptionWithApp4SalesOrderWhenEmpty) - If the generated Exact Online description is empty, a default "App4Sales order by {Salesrep}" description is used.

  • Create alternate address at customer: (Settings.CreateAlternateAddressAtCustomer) - Controls whether alternate delivery addresses are created as new addresses in Exact Online.

  • Create and link alternative contact person: (Settings.CreateAndLinkAlternativeContactPerson) - Controls whether a new contact person is created and linked for alternative addresses.

  • Create invoice address: (Settings.CreateInvoiceAddress) - Controls whether a new invoice address is created in Exact Online.

  • Shipping method code: (Settings.ShippingMethodCode) - Default shipping method code to use if not specified in the order.

  • Contact person to backoffice: (Settings.ContactPersonToBackoffice) - Controls whether contact person information is sent to Exact Online.

  • Cost unit for orders by salesrep: (Settings.CostUnitForOrdersBySalesRep) - If true, the sales representative's cost unit is used for order lines.

  • Cost unit for orders: (Settings.CostUnitForOrders) - Default cost unit for order lines.

  • Cost center code for orders by salesrep: (Settings.CostCenterCodeForOrdersBySalesRep) - If true, the sales representative's cost center is used for order lines.

  • Cost center code for orders: (Settings.CostCenterCodeForOrders) - Default cost center for order lines.

  • Determine price list on order line when price or discount is not changed: (Settings.DeterminePriceListOnOrderLineWhenPriceOrDiscountIsNotChanged) - Influences how price lists are assigned to order lines.

  • Check stock and set delivery date on order line: (Settings.CheckStockAndSetDeliveryDateOnOrderLine) - Enables logic to check stock and adjust delivery dates for order lines.

  • Only set delivery date for unchanged order date: (Settings.OnlySetDeliveryDateForUnchangedOrderDate) - Used in conjunction with CheckStockAndSetDeliveryDateOnOrderLine to limit delivery date adjustments.

  • Warehouse for stock: (Settings.WarehouseForStock) - Specifies the warehouse to use for stock checks.

  • Set item description when sending order: (Settings.SetItemDescriptionWhenSendingOrder) - Determines if the App4Sales item description is sent to Exact Online for order lines.

  • Set unit price: (Settings.SetUnitPrice) - If true, the unit price from App4Sales is sent.

  • Set original price on unit price: (Settings.SetOriginalPriceOnUnitPrice) - If true, the original item price is sent as the unit price.

  • Use discount without price on order: (Settings.UseDiscountWithoutPriceOnOrder) - Changes how discounts and net prices are sent.

  • Round order line prices to two decimals: (Settings.RoundOrderLinePricesToTwoDecimals) - If true, order line net prices are rounded to two decimal places.

  • Store package size in instruction line: (Settings.StorePackageSizeInInstructionLine) - If true, the item's purchase package size is stored in the instruction line.

  • Use date as delivery date: (Settings.UseDateAsDeliveryDate) - If true, uses current date for SendDate and OrderDate for DeliveryDate (for sales orders). For quotation lines, updates the header delivery date to the latest line delivery date.

  • Disable instruction as order line delivery date: (Settings.DisableInstructionAsOrderLineDeliveryDate) - If true, prevents parsing delivery dates from order line instructions.

  • Use currency from price list: (Settings.UseCurrencyFromPriceList) - If true, uses the currency from the price list.

  • Variant currency: (Settings.VariantCurrency) - If true, uses Settings.CurrencyCodeIso for currency.

  • GL account code for orders: (Settings.GLAccountCodeForOrders) - Specifies the GL account code to use for invoice lines.

  • Always create credit note for return orders: (Settings.AlwaysCreateCreditNoteForReturnOrders) - If true, a credit note is always created for return orders.

Did this answer your question?