Skip to main content

Uniconta - Send order

Uniconta Connector - Send Order to Backoffice Overview The Uniconta connector facilitates the transfer of sales orders from App4Sales to ...

Updated over a week ago

Uniconta Connector - Send Order to Backoffice

Overview

The Uniconta connector facilitates the transfer of sales orders from App4Sales to the Uniconta ERP system. This process, initiated by the SendOrderToBackoffice function, ensures that customer orders, including order headers, individual order lines, and associated attachments, are accurately transmitted. The connector handles data transformations, pricing calculations, and manages error responses from the ERP.

Data Source Configuration

The connector operates by pushing order data directly to the Uniconta ERP system via its API. There are no external files or SQL databases used as data sources for sending orders; all data originates from the App4Sales internal database and is formatted for the Uniconta API endpoints.

Data Mapping Table: Order Header

App4Sales Field

Source Field (API/Excel/DB)

Logic/Notes

Your Reference

orderDb.YourReference

Directly mapped.

Our Reference

orderDb.Salesrep, orderDb.Reference

If the setting "Add username to our reference field" (AddUsernameToReference) is enabled, the sales representative's username is prepended to the order's reference (e.g., "SALESREP - REFERENCE"). Otherwise, only the order's reference is used.

Contact Name

orderDb.ContactPerson.FullName, orderDb.Customer.MainContactPerson.FullName

Uses the full name of the order's contact person. If not available, falls back to the main contact person of the customer.

Delivery Address Line 1

deliveryAddress.AddressLine1

If the setting "Send order alternative address as delivery if exists" (SendOrderAlternativeAddressAsDeliveryIfExists) is true and an alternate address exists for the order, this address is used. Otherwise, the primary delivery address of the customer is used.

Delivery Address Line 2

deliveryAddress.AddressLine2

(See Delivery Address Line 1)

Delivery Address Line 3

deliveryAddress.AddressLine3

(See Delivery Address Line 1)

Delivery City

deliveryAddress.City

(See Delivery Address Line 1)

Delivery Zip Code

deliveryAddress.PostCode

(See Delivery Address Line 1)

Delivery Country

deliveryAddress.IsoCode, deliveryAddress.Iso2

Derived from the ISO code (IsoCode or Iso2) of the delivery address, converted to a Uniconta CountryCode.

Delivery Date

orderDb.OrderDate

Directly mapped from the order date.

Payment Condition

orderDb.Customer.PaymentConditionCode

Directly mapped from the customer's payment condition code.

Total Quantity

Derived

Sum of all quantities from individual order lines.

Remark

orderDb.Notes

Directly mapped from the order's notes.

Currency

orderDb.Customer.Currency

Directly mapped from the customer's currency.

Data Mapping Table: Order Line

App4Sales Field

Source Field (API/Excel/DB)

Logic/Notes

Note

orderLineDb.Instruction

Directly mapped.

EAN Code

orderLineDb.Item.EanCode

Directly mapped.

Item Code

orderLineDb.Item.ItemCode

If the setting "Use Variants as part of Item code" (UseVariantsAsPartOfItemCode) is enabled, the base item code is extracted as the first part of the App4Sales item code (separated by UnicontaConstants.ItemCodeVariantsSeparator). Otherwise, the full App4Sales item code is used.

Quantity

orderLineDb.Quantity

Directly mapped.

Quantity Delivered

orderLineDb.QuantityDelivered

Directly mapped.

Line Number

orderLineDb.Sequence

Directly mapped.

Unit

orderLineDb.Item.Unit

Directly mapped.

Variant 1-5

orderLineDb.Item.ItemCode

If the setting "Use Variants as part of Item code" (UseVariantsAsPartOfItemCode) is enabled, parts of the App4Sales item code (after the base item code, separated by UnicontaConstants.ItemCodeVariantsSeparator) are mapped to Variant 1 through Variant 5 in Uniconta.

Quantity Now (Lever Nu)

orderLine.Qty

If the setting "Fill in the order line quantity in the field 'Lever Nu'" (FillLeverNuForOrderLine) is enabled, this field is set to the order line quantity.

Price

customerPriceInfo.BasePrice, orderLineDb.Price, orderLineDb.Discount, orderLineDb.DiscountFromOriginalPrice

The price determination is complex:

  • If no customer price information is found for the line, a warning is logged. The price is then derived from orderLineDb.Price. If orderLineDb.Price is zero, orderLineDb.Item.SalesPrice is used as a fallback.

  • For returned items (Quantity < 0), the price is set to the BasePrice from the customer price information.

  • For lines with a manual discount percentage (Discount > 0), the price is recalculated based on the App4Sales order line price and discount percentage.

  • Otherwise (no specific discount or manual price in App4Sales), the price is set to the BasePrice from the customer price information.

Discount Percentage

customerPriceInfo.DiscountPercentage, orderLineDb.Discount

Set based on pricing logic:

  • For returned items, it uses customerPriceInfo.DiscountPercentage.

  • For manual discount percentage, it uses orderLineDb.Discount.

  • Otherwise, it uses customerPriceInfo.DiscountPercentage.

Discount Amount

customerPriceInfo.Discount, customerPriceInfo.CalculatedPrice, orderLineDb.Price

Set based on pricing logic:

  • For returned items, it uses customerPriceInfo.Discount.

  • For manual discount percentage, it uses the difference between customerPriceInfo.CalculatedPrice and orderLineDb.Price.

  • Otherwise, it uses customerPriceInfo.Discount.

Charges & Attachments

The connector supports sending attachments associated with an order to Uniconta. The GetOrderAttachments method retrieves documents that have been linked to the order in App4Sales. These attachments are converted into a format suitable for Uniconta, including their caption, base64 encoded content, and a derived filename.

Note: There is a limit of 5 attachments processed per order.

No specific logic for "charge lines" (e.g., freight, payment fees) was found within the SendOrder or SendOrderLines methods; these would typically be handled as separate order lines if supported.

Domain Specifics

Order Header Logic

The order header captures essential metadata for the order. Key logic includes:

  • Reference Generation: The ERP reference (OurRef) can be prefixed with the sales representative's username if configured by the AddUsernameToReference setting. This helps in identifying the originator of the order within Uniconta.

  • Contact Person: The primary contact person for the order is determined first by an order-specific contact, falling back to the customer's main contact person if no order-specific contact is available.

  • Delivery Address Selection: The delivery address sent to Uniconta is dynamically selected. If an alternate delivery address is provided for the order in App4Sales and the setting SendOrderAlternativeAddressAsDeliveryIfExists is enabled, this alternate address will be used. Otherwise, the default delivery address associated with the customer in App4Sales is utilized. The country code for the delivery address is derived from its ISO code.

Line & Pricing Logic

Order line processing is critical for accurate item, quantity, and pricing transfer:

  • Item Code Variants: The connector supports item variants. If the UseVariantsAsPartOfItemCode setting is active, the App4Sales item code is parsed to separate the base item code from its variants. The base code is mapped to the Uniconta Item field, while up to five variant values are mapped to Uniconta's Variant1 through Variant5 fields.

  • Quantity Now (Lever Nu): The FillLeverNuForOrderLine setting, if enabled, will populate the Uniconta order line's "Quantity Now" field with the ordered quantity.

  • Pricing Determination: Pricing is determined through a multi-tiered approach:

    • The system first attempts to retrieve customer-specific price information.

    • If no specific customer price is found, a warning is logged, and pricing defaults to the order line's price in App4Sales. If that is also zero, the item's standard sales price is used.

    • For returned items (negative quantities), the original base price is applied, and any discounts are reversed.

    • For order lines with manually applied discount percentages in App4Sales, the price is recalculated to reflect this discount, and the discount percentage is explicitly set.

    • Otherwise, the connector applies the determined base price and associated discount percentage and amount from the customer's price information.

    • The setting CalculateDiscountForOrderLinesWhenSendingOrderToBackoffice determines whether discount calculation happens during the order sending process.

Charges & Attachments

The connector can transfer various types of documents attached to an order from App4Sales to Uniconta. These documents are processed and encoded for transmission, appearing as attachments within the Uniconta order. The system currently supports a maximum of 5 attachments per order. No explicit functionality for separate "charge lines" (e.g., handling for shipping costs or payment surcharges as distinct line types) was identified; such charges would typically need to be represented as standard order lines if desired.

Responses & Error Handling

After sending an order, the connector processes the response from Uniconta:

  • Order Number Retrieval: Upon successful order creation in Uniconta, the assigned Uniconta order number is retrieved and used to update the corresponding order within the App4Sales database.

  • Error Conditions:

    • If the customer associated with the order is not found in Uniconta, the order creation will fail, and an error message indicating the missing customer will be logged and returned to App4Sales.

    • If Uniconta does not return an order number after successful processing, an error is logged.

    • Any general exceptions during order creation or line item insertion in Uniconta will result in an error message being logged and returned to App4Sales.

    • Transaction Rollback: Critically, if the order lines fail to be sent to Uniconta after the order header has been successfully created, the entire order in Uniconta is automatically deleted to maintain data integrity.

Related Settings & Prerequisites

The following settings influence the behavior of the Uniconta Send Order process:

  • Add username to our reference field (AddUsernameToReference): If enabled, the sales representative's username is prepended to the order's reference in Uniconta.

  • Send order alternative address as delivery if exists (SendOrderAlternativeAddressAsDeliveryIfExists): If enabled, and an alternate address is present on the App4Sales order, that address will be used as the delivery address in Uniconta.

  • Use Variants as part of Item code (UseVariantsAsPartOfItemCode): When enabled, the App4Sales item code is parsed to extract and map item variants to corresponding Uniconta variant fields.

  • Fill in the order line quantity in the field 'Lever Nu' (FillLeverNuForOrderLine): If enabled, the 'Quantity Now' field in Uniconta order lines will be populated with the ordered quantity.

  • Calculate discount for order lines when sending order to backoffice (CalculateDiscountForOrderLinesWhenSendingOrderToBackoffice): This setting determines whether the system performs discount calculations on order lines during the send order process.

Known Limitations

  • Only a maximum of 5 attachments per order are currently supported for transfer to Uniconta.

  • Explicit handling for "charge lines" (e.g., separate line types for freight, payment fees) is not present; these would need to be integrated as standard order lines if required.

Did this answer your question?