eAccounting Connector - Send Order to Backoffice
Overview
This function synchronizes App4Sales orders to the Visma eAccounting ERP system. When an order is sent from App4Sales, it is transformed into an eAccounting order entity, including header details and individual order lines, and then transmitted via the eAccounting API. The ERP's response, including the assigned order number, is then used to update the App4Sales order.
Data Source Configuration
The connector retrieves order data from the internal App4Sales order object. Configuration settings within the connector determine specific behaviors, such as currency handling and how order dates are mapped.
Data Mapping Table (Order Header)
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
Amount | TotalAmount | Total amount of the order, retrieved from the App4Sales order. Defaults to 0 if null. Rounded to 2 decimal places. |
CustomerId | Customer.InternalCode | The internal code of the customer is parsed as a GUID. This field is required by eAccounting. |
CurrencyCode | Customer.CustomerCode / Connector Setting: CurrencyCode | First attempts to retrieve currency code specific to the customer. If not found, falls back to the 'CurrencyCode' specified in the connector settings. This field is required by eAccounting and has a maximum length of 3 characters. |
VatAmount | TotalVat | Total VAT amount of the order, retrieved from the App4Sales order. Defaults to 0 if null. Rounded to 2 decimal places. This field is required by eAccounting. |
RoundingsAmount | Hardcoded | Hardcoded value of 2. This field is required by eAccounting and rounded to 2 decimal places. |
InvoiceCity | Customer.Addresses | City from the customer's main or first available "vis" (visit) address. This field is required by eAccounting. |
InvoiceCountryCode | Customer.Addresses | ISO2 country code from the customer's main or first available "vis" (visit) address. This field is required by eAccounting and has a maximum length of 2 characters. |
InvoiceAddress1 | Customer.Addresses | Address line 1 from the customer's main or first available "vis" (visit) address. |
InvoiceCustomerName | Customer.CustomerName | Customer's name. This field is required by eAccounting. Maximum length is 50 characters. |
InvoicePostalCode | Customer.Addresses | Postal code from the customer's main or first available "vis" (visit) address. This field is required by eAccounting and has a maximum length of 10 characters. |
EuThirdParty | Hardcoded | Hardcoded to `true`. This field is required by eAccounting. |
OrderDate | OrderDate / DateTime.Now | If the 'Use order date as delivery date' setting is enabled, the current date and time is used; otherwise, the App4Sales order date is used. This field is required by eAccounting and is formatted to the API's date standard. |
OrderStatus | Hardcoded | Hardcoded to 'Ongoing'. Mapped to eAccounting's 'Status' field (integer representation). |
InvoicingType | Hardcoded | Hardcoded to 'None'. Mapped to eAccounting's 'RotReducedInvoicingType' field (integer representation). |
ReverseChargeOnConstructionServices | Customer.VatLiable | Set to `true` if the customer is not VAT liable; otherwise `false`. This field is required by eAccounting. |
YourReference | YourReference | Your reference from the App4Sales order. Maximum length is 50 characters. |
OurReference | Reference | Our reference from the App4Sales order. Maximum length is 50 characters. |
DeliveryDate | OrderDate / null | If the 'Use order date as delivery date' setting is enabled, the App4Sales order date is used; otherwise, it is set to null. Formatted to the API's date standard. |
Data Mapping Table (Order Lines)
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
LineNumber | OrderLine.Sequence | Sequence number of the order line. |
IsTextRow | Hardcoded | Hardcoded to `false`. |
Text | OrderLine.Description, OrderLine.Instruction | If an instruction is provided for the order line, the description and instruction are combined in the format "Description (Instruction)". Otherwise, only the description is used. |
IsWorkCost | Hardcoded | Hardcoded to `false`. |
EligibleForReverseChargeOnVat | Customer.VatLiable | Set to `true` if the customer is not VAT liable; otherwise `false`. |
ArticleId | OrderLine.Item.InternalItemCode | Internal item code from the App4Sales order line item. |
ArticleNumber | OrderLine.ItemCode | Item code from the App4Sales order line item. |
DiscountPercentage | OrderLine.Discount | Discount percentage from the App4Sales order line. It is divided by 100 before sending to eAccounting (e.g., a 10% discount in App4Sales becomes 0.10 in eAccounting). Defaults to 0 if null. |
Quantity | OrderLine.Quantity | Quantity of the item in the App4Sales order line. Rounded to 2 decimal places. Defaults to 0 if null. |
DeliveredQuantity | OrderLine.Quantity | Delivered quantity of the item in the App4Sales order line. Rounded to 2 decimal places. Defaults to 0 if null. |
UnitPrice | OrderLine.Price, OrderLine.Discount | Calculated unit price. If the order line discount is 100%, the unit price is set to 0. Otherwise, it is calculated as |
Special Logic & Filters
Order Header Logic
Customer Selection: The customer for the order is identified by their internal code which is converted to a GUID for eAccounting.
Address Selection: When determining the invoice address details, the connector prioritizes the customer's main address. If no main address is found, it uses the first available address with the type "vis" (visit).
Currency Determination: The currency code for the order is first attempted to be retrieved based on the customer's specific price lists. If a customer-specific currency is not found, the connector's default 'CurrencyCode' setting is used.
Line & Pricing Logic
Item Identification: Order lines are mapped using both an internal item code (`ArticleId`) and a display item code (`ArticleNumber`).
Quantity Handling: All quantities (`Quantity`, `DeliveredQuantity`) are rounded to two decimal places.
Discount Calculation: Discounts are converted from a percentage (e.g., 10 for 10%) to a decimal value (0.10) for the eAccounting system. The unit price calculation accounts for 100% discounts.
VAT Liability: Both the order header and individual order lines determine eligibility for reverse charge VAT based on the customer's VAT liability status.
Charges & Attachments
The current implementation primarily focuses on transferring order header and line item data. There is no explicit code in the analyzed sections for handling separate charge lines (e.g., freight, payment fees) or attachments (e.g., PDFs, images) beyond what is included in the standard order line item descriptions.
Responses & Error Handling
API Communication: Orders are sent to eAccounting via RESTful HTTP POST requests to the `/v2/orders` endpoint. Authentication uses OAuth 2.0 with a Bearer token, which is automatically refreshed by the connector.
Order Number Retrieval: Upon successful submission, the eAccounting ERP returns an order number. This number is then used to update the original order within the App4Sales system.
Error Detection: If eAccounting does not return an order number (or returns "0"), it is considered an error, and an error message is returned to App4Sales.
Exception Handling: The connector catches API-related errors (
RestException) and logs detailed error messages from the eAccounting API. These errors are then re-thrown asFatalPostExceptionto the calling function in App4Sales.
Domain Specifics
Order Header Logic
Customer selection, numbering, order-type routing, payment/shipping fields.
Customer Identification: The
CustomerIdin eAccounting is populated from theInternalCodeof the App4Sales customer, which is expected to be a valid GUID.References: Both 'YourReference' and 'OurReference' from the App4Sales order are directly mapped to their eAccounting counterparts.
Date Handling: The
OrderDateandDeliveryDatesent to eAccounting are influenced by the 'Use order date as delivery date' setting. If enabled,OrderDateis set to the current date and time, andDeliveryDateis set to the App4Sales order date. Otherwise,OrderDateuses the App4Sales order date andDeliveryDateis null.
Line & Pricing Logic
Source fields for items, quantities, prices, discounts, VAT adjustments.
Item Descriptions: If an instruction is present for an order line, it's appended to the item description in parentheses.
Pricing Accuracy: Unit prices are carefully calculated to correctly reflect discounts, with a specific handling for 100% discounted items. All monetary values are rounded to two decimal places to maintain accuracy in the ERP system.
Charges & Attachments
As noted in the "Special Logic & Filters" section, the analyzed code does not contain specific mappings for additional charge lines or attachment uploads. Any charges or attachments would need to be incorporated into the order lines as descriptive text or handled by other connector functionalities not covered in this 'Send Order' process.
Responses & Error Handling
Order Number Update: After a successful order creation in eAccounting, the ERP-assigned order number is critical and is used to update the corresponding App4Sales order record.
Detailed Error Messages: The connector attempts to provide detailed error messages from the eAccounting API in case of failure, which can aid in troubleshooting.
Related Settings & Prerequisites
Currency Code: (Connector Setting) Defines the default currency code to be used for orders if a customer-specific currency cannot be determined.
Use order date as delivery date: (Connector Setting) A boolean setting that, when enabled, modifies how the
OrderDateandDeliveryDateare sent to eAccounting.
Known Limitations
Validation Details: The specific validation rules applied by the `Validate()` methods on order and order line entities are not explicitly defined in the analyzed code. It is assumed these perform standard data integrity checks.
Charges and Attachments: The current implementation of the 'Send Order to Backoffice' function does not explicitly support sending separate charge lines or attachments. These would need to be communicated outside of this process or manually handled.