NewBaseV4 - Send Order to Backoffice

Overview

This document details the process by which App4Sales orders are sent to the NewBaseV4 ERP system. The connector handles the preparation and transfer of order headers, order lines, and related information, ensuring data integrity and proper communication with the ERP.

Data Source Configuration

The NewBaseV4 connector retrieves order data from the internal App4Sales database objects (Models.ObjectsDb.Order) and sends it to the NewBaseV4 API. Authentication details and specific endpoint configurations are managed internally by the connector.

Data Mapping Table - Order Header

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Order Number	`order.OrderNr` / `orderResponse.OrderNr`	If 'Use A4S Order Number As Our Ref' setting is enabled, the App4Sales generated order number is sent as 'Our Reference' (`our_ref`) and NewBase is expected to generate its own order number. Otherwise, the App4Sales generated order number is sent as the 'Order Number' (`serial`) to NewBase. If 'Use A4S Order Number As Our Ref' is not enabled, the connector will attempt to update the App4Sales order number with the order number returned by NewBase. App4Sales generates order numbers based on a configurable prefix and a running sequence, padded with leading zeros based on 'Order Number Generation Num Digits' setting.
Our Reference	`order.Reference` / `order.PaymentDetails.PaymentReference` / `order.OrderNr`	If 'Send Payment Reference As Order Reference' setting is enabled and a payment reference exists, it is used. Otherwise, if 'Use A4S Order Number As Our Ref' setting is enabled, the App4Sales generated order number (`order.OrderNr`) is used. Otherwise, the order's reference (`order.Reference`) is used.
Your Reference	`order.YourReference`	Mapped directly.
Order Notes	`order.Notes`	Mapped directly to the NewBase remark field.
Customer Code	`order.Customer.CustomerCode` / `order.Customer.InternalCode`	If 'Add Organisations That Are Linked To Debtors To The Customers' setting is enabled, the connector checks if the customer is of type 'Debtor' (from a customer free field 'CustomerType'). If so, `order.Customer.CustomerCode` is used; otherwise, `order.Customer.InternalCode` is used. If the setting is disabled, `order.Customer.CustomerCode` is always used.
Contact Serial	`mainContact.ContactId`	The `ContactId` of the main contact person associated with the customer.
Organisation Serial	Derived from Customer Free Fields	The content of the customer free field with caption 'OrganisationSerial'.
Contact Id	Derived from Customer Free Fields	The content of the customer free field with caption 'DebtorId'.
Organisation Id	Derived from Customer Free Fields	The content of the customer free field with caption 'OrganisationId'.
Delivery City	`order.AlternateAddress.City`	Mapped directly from the alternate delivery address.
Delivery Country	`order.AlternateAddress.Country`	Mapped directly from the alternate delivery address.
Delivery Zipcode	`order.AlternateAddress.PostCode`	Mapped directly from the alternate delivery address.
Delivery Street	Derived from `order.AlternateAddress.AddressLine1`	The street name is parsed from the `AddressLine1` of the alternate delivery address.
Delivery Number	Derived from `order.AlternateAddress.AddressLine1`	The house number is parsed from the `AddressLine1` of the alternate delivery address.
Delivery Number Addition	Derived from `order.AlternateAddress.AddressLine1`	The house number addition is parsed from the `AddressLine1` of the alternate delivery address.
Delivery State	`order.AlternateAddress.State`	Mapped directly from the alternate delivery address.
Delivery Label	`order.AlternateAddress.FormattedsOrderAddress`	Mapped directly from the formatted order address of the alternate delivery address.
Delivery Email	`order.ConsumerName` / `order.Customer.Email`	Uses `order.ConsumerName` if available, otherwise falls back to `order.Customer.Email`.
Delivery Attention	`order.ConsumerName` / `mainContact.FullName`	Uses `order.ConsumerName` if available, otherwise falls back to the full name of the main contact person.
Delivery Phone	`order.ConsumerPhoneNumber` / `order.Customer.Phone`	Uses `order.ConsumerPhoneNumber` if available, otherwise falls back to `order.Customer.Phone`.
Payment Method	`settings.DefaultPaymentMethodForPaidOrders`	If the order's payment status is 'accepted', and the setting 'Default Payment Method For Paid Orders' can be parsed as an integer, this value is used. Otherwise, no payment method is sent.
Payment Terms	`settings.DefaultPaymentTermsForPaidOrders`	If the order's payment status is 'accepted', and the setting 'Default Payment Terms For Paid Orders' can be parsed as an integer, this value is used. Otherwise, no payment terms are sent.

Data Mapping Table - Order Lines

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Item Code	`orderLine.ItemCode`	Mapped directly.
Quantity	`orderLine.Quantity`	Mapped directly.
Sales Price	`orderLine.Price`	Mapped directly. If 'Send Base Price For Item Order Lines' setting is enabled, the price is reset to the item's base sales price before sending, and any discount is recalculated.
Discount	`orderLine.Discount`	Mapped directly. If 'Send Base Price For Item Order Lines' setting is enabled, this discount is recalculated based on the difference between the original line price and the item's base sales price.
Discount Type	Hardcoded value	Always sent as `1`.

Special Logic & Filters

Reset Order Lines Prices to Base Prices

If the connector setting 'Send Base Price For Item Order Lines' is enabled, the connector adjusts the order line prices before sending them to NewBase. For each order line, it retrieves the base sales price of the item. If a discount was applied (i.e., the line price is less than the item's base sales price), the discount percentage is recalculated, and the line's price is reset to the item's base sales price. This ensures that NewBase receives the base price and the corresponding discount, rather than an already discounted price.

Domain Specifics

Order Header Logic

Order numbers can be generated either by App4Sales or by NewBase, controlled by the 'Use A4S Order Number As Our Ref' setting. Contact person details and customer-specific free fields (e.g., 'OrganisationSerial', 'DebtorId', 'OrganisationId') are included in the order header. Delivery address information is derived from the alternate address on the order, with street, number, and addition parsed from AddressLine1. Payment method and terms are conditionally applied based on the order's payment status and specific connector settings.

Line & Pricing Logic

Order lines include the item code, quantity, and sales price. Discounts are also passed. A specific setting, 'Send Base Price For Item Order Lines', can alter the pricing logic: if enabled, the connector ensures that the base sales price of an item is sent to NewBase, recalculating any applied discounts to reflect this base price. The 'Discount Type' is always sent as 1.

Charges & Attachments

No explicit handling for separate charge lines (surcharges, freight, payment fees) or attachments (PDFs, signature images) was found within the examined connector code for the order sending process. It is assumed that such information, if required by NewBase, would need to be embedded within the existing order header or line item structures, or handled by a different mechanism not covered in the SendOrder logic.

Responses & Error Handling

Upon sending an order, the connector expects a response from the NewBaseV4 API. If no response is received, or if the response indicates an error (Success property is false), the order number in App4Sales is reset, and an error message is returned to the user. If the 'Use A4S Order Number As Our Ref' setting is disabled, the connector expects NewBase to return an order number, which is then used to update the order in App4Sales. If NewBase does not return an order number in this scenario, an error is reported. Any exceptions during the order sending process are logged, and an error message is returned.

Related Settings & Prerequisites

Use A4S Order Number As Our Ref: Boolean setting. If enabled, the App4Sales generated order number is sent as the 'our_ref' to NewBase, and NewBase is expected to generate its own 'serial' order number.
Send Payment Reference As Order Reference: Boolean setting. If enabled, and a payment reference exists, it will be used as the order's reference (our_ref) to NewBase.
Order Number Generation Prefix: String setting. A prefix to be used when App4Sales generates order numbers.
Order Number Generation Num Digits: Integer setting. The minimum number of digits for the order number sequence, padded with leading zeros if necessary. Defaults to 5 if less than 2.
Add Organisations That Are Linked To Debtors To The Customers: Boolean setting. Influences whether CustomerCode or InternalCode is used for the NewBase debtor field, based on a 'CustomerType' free field.
Default Payment Method For Paid Orders: Integer setting. If the order is paid, this value is sent as the payment method to NewBase.
Default Payment Terms For Paid Orders: Integer setting. If the order is paid, this value is sent as the payment terms to NewBase.
Send Base Price For Item Order Lines: Boolean setting. If enabled, order line prices are reset to the item's base sales price, and discounts are recalculated before sending the order to NewBase.

Known Limitations

The connector does not appear to support sending separate surcharge or charge lines (e.g., for freight, payment fees) to NewBaseV4.
The connector does not appear to support sending attachments (e.g., PDFs, signature images) alongside the order to NewBaseV4.
The parsing of street, number, and addition from AddressLine1 assumes a specific format for the address line.

NewBaseV4 - Send order