QuickBooksOnline Connector - Send Order To Backoffice

This function synchronizes App4Sales orders to QuickBooks Online, converting them into either Estimates or Invoices based on the order type defined in App4Sales. The process involves transforming order headers, lines, pricing, and associated customer and item data into the corresponding QuickBooks Online structures. After successful transmission, the App4Sales order is updated with the QuickBooks Online document number.

Data Source Configuration

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Transaction Date	`order.OrderDate`	Maps the order date from App4Sales to the transaction date in QuickBooks Online.
Transaction Tax Code Reference	`order.Customer.VatCode`	Uses the customer's VAT code from App4Sales as the transaction tax code reference in QuickBooks Online.
Bill Email Address	`order.Customer.MainContactPerson.Email`	Uses the email address of the customer's main contact person from App4Sales.
Customer Reference Value	`order.Customer.CustomerCode`	Maps the customer code from App4Sales.
Customer Reference Name	`order.Customer.CustomerName`	Maps the customer name from App4Sales.
Customer Memo	`order.YourReference`	Maps the 'Your Reference' field from App4Sales as a memo for the customer in QuickBooks Online.
Shipping Address	`order.Customer.Addresses (Type: Delivery)`	The delivery address from App4Sales is mapped to the shipping address in QuickBooks Online.

Data Mapping Table - Order Header (specific to Estimates)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Total Amount	Derived	Calculated as the sum of (Price * Quantity) for all order lines.
Due Date	`order.OrderDate`	Maps the order date from App4Sales as the due date for the estimate.
Private Note	`order.Notes`	Maps general notes from the App4Sales order to a private note in QuickBooks Online.
Accepted By	`order.Salesrep`	Maps the sales representative's name from App4Sales.
Billing Address	`order.Customer.Addresses (Type: Invoice)`	The invoice address from App4Sales is mapped to the billing address in QuickBooks Online.

Data Mapping Table - Order Lines (for both Estimates and Invoices)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
Line Number	`orderLine.LineNumber`	Maps the order line number.
Amount	Derived	Calculated as `orderLine.Price * orderLine.Quantity`. This represents the total amount for the line, excluding line-specific discounts.
Item Reference Value	`orderLine.Item.InternalItemCode`	Maps the internal item code from App4Sales.
Item Reference Name	`orderLine.Item.Description`	Maps the item description from App4Sales.
Service Date	`orderLine.DeliveryDate`	Maps the delivery date of the order line.
Quantity	`orderLine.Quantity`	Maps the quantity of the item in the order line.
Discount Rate	`orderLine.DiscountFromOriginalPrice`	Maps the discount percentage applied to the original price of the item.
Unit Price	`orderLine.Price`	Maps the unit price of the item.
Description	`orderLine.Description`, `orderLine.Instruction`	Combines the item description and instruction. If an instruction is present, the format is "Description - Instruction"; otherwise, it's just the "Description".
Tax Code Reference Value	Derived	If `UseGlobalCompany` setting is enabled: If customer is VAT liable, uses the `TaxId` from the item's FreeItemFields. If customer is not VAT liable, uses the `TaxCodeIdForNoVatCustomersInGlobalCompany` setting. If `UseGlobalCompany` setting is disabled: If customer is VAT liable, uses "TAX". If customer is not VAT liable, uses "NON".

Special Logic & Filters

Order Type Routing: The connector checks the App4Sales order's type (order.OrderType.ValueToBackoffice). If it is "Estimate" (from Constants.OrderTypes.Estimate), the order is sent to QuickBooks Online as an Estimate. Otherwise, it is sent as an Invoice.
Order Number Update: After successfully sending an order to QuickBooks Online, the returned document number (DocNumber) from QuickBooks Online is used to update the OrderNumber in the App4Sales database for the corresponding order.
Error Handling: In case of an error during the sending process, the connector returns a generic error message (Core.Constants.Error.ERROR) concatenated with the exception message. If no document number is returned, it indicates an error with Core.Constants.Error.ERRORORDERNR.

Domain Specifics / Extension Section

Order Header Logic

Customer Selection: The customer associated with the App4Sales order is identified by their CustomerCode and CustomerName for mapping to QuickBooks Online's CustomerRef.
Order-Type Routing: As described above, the App4Sales order type determines whether a QuickBooks Online Estimate or Invoice is created.
Address Handling: The delivery address from App4Sales is used as the shipping address for both Estimates and Invoices. For Estimates only, the invoice address from App4Sales is used as the billing address.

Line & Pricing Logic

Item Lookup: App4Sales order lines are mapped to QuickBooks Online sales item lines using the InternalItemCode and Description from the App4Sales item.
Quantity and Pricing: Quantity and unit price are directly mapped. The line amount is calculated as Price * Quantity.
Discount Adjustments: The DiscountFromOriginalPrice from App4Sales is mapped as the DiscountRate in QuickBooks Online.
VAT Adjustments:
- If the Use Global Company setting is enabled:
  - If the customer is VAT liable, the tax ID is retrieved from the item's free fields (specifically, the field with caption `TaxId`).
  - If the customer is not VAT liable, the TaxCodeIdForNoVatCustomersInGlobalCompany setting value is used.
- If the Use Global Company setting is disabled:
  - If the customer is VAT liable, the tax code is set to "TAX".
  - If the customer is not VAT liable, the tax code is set to "NON".

Charges & Attachments

There is no specific logic for charges (freight, payment surcharges) or attachments identified in the SendOrderToBackoffice method for direct mapping to QuickBooks Online. These may be handled outside of this specific function or not supported by the connector.

Responses & Error Handling

Returned Order Numbers: Upon successful creation in QuickBooks Online, the DocNumber (Document Number) of the created Estimate or Invoice is returned and used to update the corresponding order in App4Sales.
Duplicate Detection: No explicit duplicate order detection logic is present within the SendOrderToBackoffice method itself. This may be handled by QuickBooks Online's API or a higher-level App4Sales mechanism.
Retry/Backoff Strategies: No specific retry or backoff strategies are implemented within the SendOrderToBackoffice method. Error handling is limited to catching exceptions and returning an error message.

Related Settings & Prerequisites

Use Global Company: This setting influences how tax codes are determined for order lines. When enabled, the connector looks for a `TaxId` in the item's free fields; otherwise, it uses predefined "TAX" or "NON" codes.
Tax Code Id For No Vat Customers In Global Company: If Use Global Company is enabled and the customer is not VAT liable, this setting defines the tax code to be used for order lines.

Known Limitations

No specific limitations regarding the Send Order to Backoffice process were identified within the analyzed code. Any limitations would typically stem from the capabilities of the QuickBooks Online API itself or higher-level App4Sales configurations not covered in this connector's implementation.

QuickBooksOnline - Send order