Economic Connector - SendOrderToBackoffice

This function synchronizes App4Sales orders to the Economic ERP system via its REST API. It handles the creation of both order headers and individual order lines, including pricing, discounts, and customer information. The process involves retrieving product information from Economic, mapping App4Sales data to Economic's order structure, and then creating the order, optionally marking it as sent.

1. Data Source Configuration

The connector communicates with the Economic REST API at https://restapi.e-conomic.com/. Authentication is performed using the following HTTP headers:

X-AppSecretToken: Provided by the Economic application secret.
X-AgreementGrantToken: Provided by the connector settings (Agreement Grant Token).
Content-Type: Set to application/json.

Data is pushed from App4Sales to Economic.

2. Data Mapping Table

Order Header Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Customer Number	`customerNumber`	Parsed from `order.Customer.CustomerCode`.
VAT Zone	`vatZone`	Derived from the App4Sales customer's dynamic field named "VatZone" (`EconomicConstants.VatZoneElementName`). If not present, fallback logic is applied from the customer or customer group.
Payment Terms	`paymentTerms`	Derived from the App4Sales customer's dynamic field named "PaymentTerms" (`EconomicConstants.PaymentTermsElementName`). If not present, fallback logic is applied from the customer.
Sales Document Layout	`layout`	Derived from the App4Sales customer's dynamic field named "Layout" (`EconomicConstants.LayoutElementName`). If not present, fallback logic is applied from the customer, customer group, or a configurable fallback layout name.
Currency	`Currency`	Retrieved from `PriceListsContext` based on `order.Customer.UsesPriceField`. If not present, fallback logic is applied from the customer.
Order Date	`Date`	Set to the current date and time (`DateTime.Now`), formatted as "yyyy-MM-dd".
Delivery Date	`economicOrder.Delivery.DeliveryDate`	Mapped from `order.OrderDate`, formatted as "yyyy-MM-dd", unless the `DontSendDeliveryDate` setting is enabled.
Notes (Heading)	`economicOrder.Notes.Heading`	Mapped from `order.Description1`.
Notes (Text Line 1)	`economicOrder.Notes.TextLine1`	Mapped from `order.Notes`.
Notes (Text Line 2)	`economicOrder.Notes.TextLine2`	Mapped from `order.Description2`.
Your Reference	`economicOrder.References.Other`	Mapped from `order.YourReference`.
Sales Person	`economicOrder.References.SalesPerson.employeeNumber`	Derived from `order.Salesrep` (Employee ID) from `SalesRepsContext`. If not found, it attempts to use `order.Customer.CustomerManager` and then the sales person linked to the customer in Economic.
Recipient Name	`economicOrder.Recipient.name`	Mapped from `order.Customer.CustomerName`.
Recipient VAT Zone	`economicOrder.Recipient.vatZone`	Mapped from the customer's VAT zone.
Delivery Location Number	`economicOrder.DeliveryLocation.DeliveryLocationNumber`	If `order.AlternateAddress.AddressLine3` (or `customerAddress.AddressLine3` if no alternate address) contains a valid integer, it is used as an existing delivery location ID in Economic.
Delivery Address	`economicOrder.Delivery.Address`	If an alternate address is provided and valid, it's used. Otherwise, the customer's delivery/visit address is used.
Delivery City	`economicOrder.Delivery.City`	Same logic as Delivery Address.
Delivery Country	`economicOrder.Delivery.Country`	Same logic as Delivery Address.
Delivery Zip	`economicOrder.Delivery.Zip`	Same logic as Delivery Address.

Order Line Mapping

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Product	`product`	The Economic Product entity retrieved based on `orderLine.ItemCode`.
Description	`Description`	Mapped from `orderLine.Description`.
Quantity	`Quantity`	Mapped from `orderLine.Quantity`.
Discount Percentage	`DiscountPercentage`	Mapped from `orderLine.Discount` (as a percentage).
Unit Net Price	`UnitNetPrice`	Calculated as `orderLine.Price.Value / (100 - orderLine.Discount.GetValueOrDefault()) * 100`. If discount is 100%, price is 0.
Unit Number	`Unit` (from `Item.ExtraData`)	Retrieved from the item's `ExtraData` field with the key "Unit" (`EconomicConstants.Unit`) and parsed as an integer. If not found or invalid, no unit is assigned.
Unit Cost Price	`CostPrice` (from `Item.ExtraData`)	Retrieved from the item's `ExtraData` field with the key "CostPrice" (`EconomicConstants.CostPrice`) and parsed as a decimal. Defaults to 0 if not found or invalid.

3. Special Logic & Filters

SOAP vs. REST API: The connector can be configured to use either a SOAP-based or REST-based API for sending orders. The choice is determined by the UseSoapSendOrderProcess setting. This document describes the REST API process.
Missing Properties Fallback: If critical order header properties (Layout, Payment Terms, VAT Zone, Currency) are missing after initial mapping from customer dynamic fields, the connector attempts to retrieve them from the customer, customer group, or a fallback layout name setting in Economic.
Product Validation: Before creating order lines, the connector verifies that all items in the App4Sales order exist as products in Economic. If any products are missing, a MissingProductsException is thrown, preventing the order from being sent.
Optional Order Sending: Orders are initially created as drafts in Economic. Based on the MarkNewlyCreatedOrdersAsSent setting, the drafted order can be automatically marked as "sent" in Economic immediately after creation.
Batching Product Retrieval: Product information from Economic is retrieved in batches of 200 items to optimize API calls.

4. Domain Specifics

Order Header Logic

Customer selection is based on the order.Customer object passed to the function. The order date is always the current date. Delivery date is mapped from the App4Sales order date unless configured otherwise. References, notes, and sales person assignments are mapped as detailed in the Order Header Mapping table. The recipient name and VAT zone are derived from the App4Sales customer. Delivery address information is prioritized from an alternate address, then from the customer's delivery/visit address. If AddressLine3 contains a valid integer, it's interpreted as an existing Economic delivery location ID.

Line & Pricing Logic

Each order line in App4Sales is converted to an Economic order line. The unit net price for each line is calculated considering any discounts. Unit number and unit cost price are extracted from the Item.ExtraData JSON field within App4Sales. Products are looked up in Economic based on their item codes.

Charges & Attachments

This specific SendOrderToBackoffice method (REST API) does not explicitly handle charge lines (freight, payment fees) or attachments (PDF, JSON exports, images). If these are required, they would need to be managed by other processes or settings not covered in this function.

Responses & Error Handling

Upon successful order creation, the Economic order number is returned and used to update the App4Sales order via OrdersContext.Instance.UpdateOrderNumber. If products referenced in the App4Sales order are not found in Economic, a MissingProductsException is thrown. Errors during API calls (e.g., network issues, invalid data) are handled by the underlying IRestService and may result in exceptions.

5. Related Settings & Prerequisites

UseSoapSendOrderProcess: (Boolean) If set to true, the connector will use the SOAP API for sending orders instead of the REST API.
AgreementGrantToken: (String) Required for authenticating with the Economic API.
MarkNewlyCreatedOrdersAsSent: (Boolean) If set to true, orders created as drafts in Economic will immediately be marked as "sent".
DontSendDeliveryDate: (Boolean) If set to true, the delivery date will not be sent to Economic.
FallbackSalesDocumentLayoutName: (String) If a layout is not found from the customer or customer group, this setting specifies a fallback layout name to search for in Economic.

6. Known Limitations

An alternative SOAP-based implementation (SendOrderToBackofficeSoap) exists, enabled by the UseSoapSendOrderProcess setting. While functionally similar in its goal of sending order data, it uses a different technical approach for API communication and may have subtle differences in data handling (e.g., VAT zone defaulting, exchange rate setting) compared to the detailed REST API documentation provided here.

Economic - Send order