Fortnox - SendOrderToBackoffice
This document describes the process of sending an order from App4Sales to the Fortnox backoffice. The process involves converting the App4Sales order object to a Fortnox order object and sending it to the Fortnox API.
Data Source Configuration
The connector sends order data to the Fortnox API. The API endpoint for creating and updating orders is used. Authentication is done using OAuth.
Data Mapping Table
Order Header
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
YourOrderNumber | portalOrder.YourReference | Used if 'UseYourReferenceAsYourOrderNumber' setting is enabled. The value is sanitized to be valid ISO-8859-1. |
YourReference | portalOrder.Notes or portalOrder.YourReference | If 'UseNotesAsYourReference' is enabled, the cleaned notes are used. Otherwise, it uses `portalOrder.YourReference` unless 'UseYourReferenceAsYourOrderNumber' is also on. The value is sanitized. |
OurReference | portalOrder.Reference or salesrep | Defaults to the sales representative's name if the order reference is empty or 'webshop order'. Otherwise, it uses the order reference. The value is sanitized. The sales representative is determined by the 'UseCustomerManagerAsSalesRep' setting. |
OrderDate | DateTime.Now or portalOrder.OrderDate | If 'UseOrderDateAsDeliveryDate' is enabled, the current date is used. Otherwise, the order date from the portal is used. Formatted as 'yyyy-MM-dd'. |
DeliveryDate | portalOrder.OrderDate | Used if 'UseOrderDateAsDeliveryDate' is enabled. Formatted as 'yyyy-MM-dd'. Otherwise, it is null. |
CustomerName | portalOrder.Customer.CustomerName | Direct mapping. |
CustomerNumber | portalOrder.Customer.CustomerCode | Direct mapping. |
Language | "SV" | Hardcoded to Swedish. |
Remarks | portalOrder.Notes or portalOrder.GetDescriptionsAsText() | If 'StoreNotesInComments' is enabled, this field gets the concatenated `Description1`, `Description2`, and `Description3`. Otherwise, it gets the sanitized order notes. |
Comments | portalOrder.GetDescriptionsAsText() or portalOrder.Notes | If 'StoreNotesInComments' is enabled, this field gets the sanitized order notes. Otherwise, it gets the concatenated `Description1`, `Description2`, and `Description3`. |
VATIncluded | false | Hardcoded to false. |
Currency | portalOrder.Customer.Currency | The currency is retrieved from the customer's price list and converted to an ISO code. If no currency is found, it is set to null, and Fortnox's logic is followed. |
WayOfDelivery | portalOrder.DeliveryMethod.Code | Direct mapping from the delivery method code. |
CostCenter | settings.DefaultCostCenter | Uses the 'DefaultCostCenter' setting if it's configured. |
EmailInformation.EmailAddressTo | portalOrder.ConsumerEmail | Mapped if `ConsumerEmail` is present. |
Phone1 | portalOrder.ConsumerPhoneNumber | Mapped if `ConsumerPhoneNumber` is present. |
NotCompleted | true | Set to true if 'SendOrderAsNotCompleted' setting is enabled. |
Alternate Address
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
DeliveryName | portalOrder.ConsumerName or portalOrder.Customer.CustomerName | Uses `ConsumerName` if available, otherwise falls back to the customer's name. |
DeliveryAddress1 | portalOrder.AlternateAddress.AddressLine1 | Direct mapping. |
DeliveryAddress2 | portalOrder.AlternateAddress.AddressLine2 | Direct mapping. |
DeliveryCity | portalOrder.AlternateAddress.City | Direct mapping. |
DeliveryCountry | portalOrder.AlternateAddress.Iso2 | The ISO2 country code is converted to the Swedish country name. |
DeliveryZipCode | portalOrder.AlternateAddress.PostCode | Direct mapping. |
Order Lines
App4Sales Field | Source Field (API/Excel/DB) | Logic/Notes |
ArticleNumber | portalOrderLine.ItemCode | Direct mapping. |
DeliveredQuantity | portalOrderLine.Quantity or portalOrderLine.QuantityDelivered | If 'DeliveredQuantitySameAsOrderedQuantity' is enabled or `QuantityDelivered` is null, it uses the ordered quantity. Otherwise, it uses the delivered quantity. |
Price | portalOrderLine.Price | Mapped to null if 'SendDiscountInsteadOfPrice' setting is enabled. If the item is free (price is 0), the price is set to 0. |
OrderedQuantity | portalOrderLine.Quantity | The quantity is converted to a string in invariant culture. |
Unit | portalOrderLine.Item.Unit | Direct mapping from the item's unit. |
DiscountType | "PERCENT" or "AMOUNT" | If the item is free, the discount type is 'AMOUNT'. Otherwise, it is 'PERCENT'. |
Discount | portalOrderLine.DiscountFromOriginalPrice | If 'SendDiscountInsteadOfPrice' is enabled, the discount is calculated from the original price. Otherwise, it is 0. If the item is free, the discount is 0. |
Description | portalOrderLine.Instruction | Mapped if 'SendInstructionAsItemDescriptionOnOrder' is enabled and the instruction is not empty. |
Special Logic & Filters
Order Creation vs. Update: If the order has a `DocumentNumber`, the connector updates the existing order in Fortnox. Otherwise, it creates a new one.
Notes Sanitization: Pipe characters ('|') in order notes are replaced with hyphens ('-'), and full-width commas are replaced with standard commas.
Character Encoding: String fields like `YourOrderNumber`, `YourReference`, `OurReference`, and `Notes` are converted to be valid ISO-8859-1 strings.
Domain Specifics / Extension Section
Order Header Logic
The connector populates the Fortnox order header with data from the App4Sales order, customer, and connector settings. It determines fields like `YourOrderNumber` and `OurReference` based on specific settings. The delivery address is mapped from the alternate address on the App4Sales order, with the country code being converted to its Swedish equivalent.
Line & Pricing Logic
For each order line, the connector maps the item code, quantity, and price. It can be configured to send the discount percentage instead of the final price. Free items (price is 0) are handled specially, with the discount type set to 'AMOUNT'. The delivered quantity can be configured to be the same as the ordered quantity.
Responses & Error Handling
The `SendOrder` method in the `OrdersManager` returns the `DocumentNumber` of the created or updated order. This number is then used to update the order number in the App4Sales database.
Related Settings & Prerequisites
UseYourReferenceAsYourOrderNumber: If enabled, the `YourReference` from the order is used as the `YourOrderNumber` in Fortnox.
UseNotesAsYourReference: If enabled, the order notes are used as the `YourReference` in Fortnox.
UseCustomerManagerAsSalesRep: If enabled, the customer manager's name is used as the sales representative.
UseOrderDateAsDeliveryDate: If enabled, the current date is used as the order date, and the portal order date is used as the delivery date.
StoreNotesInComments: If enabled, order notes are stored in the `Comments` field, and descriptions are stored in the `Remarks` field. Otherwise, the behavior is reversed.
SendOrderAsNotCompleted: If enabled, the order will be sent with the `NotCompleted` flag set to true.
DefaultCostCenter: Allows specifying a default cost center for all orders.
SendDiscountInsteadOfPrice: If enabled, the connector sends the discount percentage instead of the calculated price per line.
DeliveredQuantitySameAsOrderedQuantity: If enabled, the delivered quantity is always the same as the ordered quantity.
SendInstructionAsItemDescriptionOnOrder: If enabled, the line instruction is sent as the item description on the order line.