SAP B1 SL Connector - Send Order To Backoffice

This document details the process by which App4Sales orders, quotations, and invoices are transformed and transmitted to SAP Business One Service Layer (SAP B1 SL). It outlines the business rules, data mappings, and settings that govern this integration, ensuring that administrators and implementation consultants can understand and troubleshoot the order synchronization process.

Order Header Logic

When sending an order, quotation, or invoice to SAP B1 SL, the connector first determines the document type. Based on the document type and specific connector settings, the system routes the order to the appropriate SAP B1 SL API endpoint (Sales Orders, Sales Quotations, or Sales Invoices) and applies distinct mapping rules for header-level fields. The `DocDueDate` is always formatted as "YYYYMMDD".

Order Header Mapping (Orders, Quotations, Invoices)

App4Sales Field	Source Field (SAP B1 SL)	Logic/Notes
Customer Code	CustomerCode	Directly mapped from App4Sales Customer Code.
Sales Person Code	SalesPersonCode	Mapped from the App4Sales Customer Manager by matching against `SalesEmployeeName` in SAP B1 SL Sales Persons.
Contact Person Code	ContactPersonCode	Mapped from the `ContactId` of the customer's main contact person in App4Sales.
Document Due Date	DocDueDate	Mapped from App4Sales Order Date, formatted as "YYYYMMDD".
Comments	Comments	Orders: If 'Send order reference as BPReferenceNo' OR 'Add Reference and Your Reference to the NumAtCard field in SAP' is enabled, uses App4Sales Order Notes. Otherwise, combines 'Your Reference' and 'Notes' (e.g., "YOUR_REF - NOTES"). Quotations/Invoices: If 'Send order reference as BPReferenceNo' is enabled, uses App4Sales Order Notes. Otherwise, combines 'Your Reference' and 'Notes' (e.g., "YOUR_REF - NOTES").
Your Reference / Reference Number	NumAtCard	Orders: If 'Add Reference and Your Reference to the NumAtCard field in SAP' is enabled, combines App4Sales 'Reference' and 'Your Reference' (e.g., "REF - YOUR_REF"). If 'Send order reference as BPReferenceNo' is enabled (and 'Add Reference...' is not), uses 'Your Reference'. Otherwise, null. Quotations/Invoices: If 'Send order reference as BPReferenceNo' is enabled, uses App4Sales 'Your Reference'. Otherwise, null.
Discount Percentage (Header)	DiscountPercent	Orders: If 'Do not send prices to ERP' is disabled AND 'Send discount of 0 on order header to ERP' is enabled, sends 0. Otherwise, uses the customer's discount percentage from App4Sales. Quotations/Invoices: Uses the customer's discount percentage from App4Sales.
Document Total	DocTotal	Calculated as the sum of (Quantity * (Price - Discount)) for all order lines. Set to null if 'Do not send DocTotal to ERP' is enabled.
Custom Fields	Custom Fields (User Defined Fields)	If 'Mapping of default values for custom order fields' is configured, values are sent to specified SAP B1 SL custom fields.

Address Mapping

Shipping and billing addresses are determined based on the order's configured addresses in App4Sales. The connector first checks for alternate addresses specified on the order. If not present, it defaults to the customer's main delivery address for shipping. For ShipToCode and PayToCode, orders parse an external ID for an Address Name, while quotations and invoices directly use the AddressId from App4Sales if it's not an integer.

App4Sales Field	Source Field (SAP B1 SL)	Logic/Notes
Ship-To Code	ShipToCode	Orders: Derived from the 'ExternalId' of the alternate or customer's main delivery address. Quotations/Invoices: Derived from the 'AddressId' of the alternate or customer's main delivery address.
Bill-To Code	PayToCode	Orders: Derived from the 'ExternalId' of the order's invoice address. Quotations/Invoices: Derived from the 'AddressId' of the order's invoice address.
Ship-To Street	ShipToStreet	Mapped from AddressLine1 of the determined shipping address.
Ship-To Address 2	ShipToAddress2	Mapped from AddressLine2 of the determined shipping address.
Ship-To Address 3	ShipToAddress3	Mapped from AddressLine3 of the determined shipping address.
Ship-To City	ShipToCity	Mapped from City of the determined shipping address.
Ship-To State	ShipToState	Mapped from State of the determined shipping address.
Ship-To Zip Code	ShipToZipCode	Mapped from PostCode of the determined shipping address.
Ship-To Country	ShipToCountry	Mapped from ISO2 country code of the determined shipping address.
Bill-To Street	BillToStreet	Mapped from AddressLine1 of the determined billing address.
Bill-To Address 2	BillToAddress2	Mapped from AddressLine2 of the determined billing address.
Bill-To Address 3	BillToAddress3	Mapped from AddressLine3 of the determined billing address.
Bill-To City	BillToCity	Mapped from City of the determined billing address.
Bill-To State	BillToState	Mapped from State of the determined billing address.
Bill-To Zip Code	BillToZipCode	Mapped from PostCode of the determined billing address.
Bill-To Country	BillToCountry	Mapped from Country of the determined billing address.

Line & Pricing Logic

Order, quotation, and invoice lines are processed with specific mappings for item details, quantities, pricing, and VAT. The `VatGroup` is sourced from a free item field if available.

Order Line Mapping (Orders, Quotations, Invoices)

App4Sales Field	Source Field (SAP B1 SL)	Logic/Notes
Item Code	ItemCode	Directly mapped from App4Sales Order Line Item Code.
Item Description	ItemDescription	Combines App4Sales Order Line Description and Instruction (e.g., "DESCRIPTION - INSTRUCTION").
Quantity	Quantity	Directly mapped from App4Sales Order Line Quantity. Adjusted for orders and quotations if UoM logic is enabled.
Unit of Measure Entry	UoMEntry	Orders/Quotations Only: If 'UOM Entry value for not complete package sizes' is configured and the quantity is not a multiple of the item's purchase package size, this value is sent.
Currency	Currency	Customer's currency (only if 'Do not send prices to ERP' is disabled).
Price	Price	Mapped from App4Sales Order Line Price (only if 'Do not send prices to ERP' is disabled).
Discount Percentage (Line)	DiscountPercent	Mapped from App4Sales Order Line 'Discount From Original Price' (only if 'Do not send prices to ERP' is disabled).
Line Total	LineTotal	Calculated as Quantity * (Price - Discount) (only if 'Do not send prices to ERP' is disabled).
VAT Group	VatGroup	If 'Country codes that are VAT liable' setting is empty, sourced from 'VatGroup' field within the item's FreeItemFields (XML). If 'Country codes that are VAT liable' is configured and the delivery address country is in the list, it's also sourced from 'VatGroup' field within the item's FreeItemFields (XML).
Tax Percentage Per Row	TaxPercentagePerRow	Set to App4Sales Order Line VatPercentage if 'Country codes that are VAT liable' is configured and the delivery address country is in the list.

Charges & Attachments

The provided code snippets do not show explicit handling for separate charge lines (freight, payment fees) or attachments (PDF, images, custom payloads). Surcharges are likely incorporated into the line totals or header totals in App4Sales before being sent, but no specific mapping for individual charge lines is observed.

Responses & Error Handling

The connector processes responses from SAP B1 SL to confirm successful order creation and retrieve the assigned document number (`DocNum`) and external ID (`DocEntry`).

If successful, the App4Sales internal order number is updated with the SAP B1 SL generated order number and external ID.
If no order number is retrieved from SAP B1 SL, an error message "No order number retrieved from SAPB1 SL backoffice" is logged, and an error string is returned.
Any exceptions during the order creation process are caught, logged with details, and an error message is returned to App4Sales.
If 'Create drafts during send order call' is enabled, the external ID will include a `SapDraft.DraftSuffix` for identification.

Related Settings & Prerequisites

The following connector settings influence the 'Send Order To Backoffice' process:

Create drafts during send order call: (Boolean) If enabled, regular orders are sent as drafts to SAP B1 SL.
Send order reference as BPReferenceNo: (Boolean) Influences how 'Your Reference' and 'Notes' are mapped to 'NumAtCard' and 'Comments' in SAP B1 SL.
Use CustomerRefNo as order description: (Boolean) Influences the description used when displaying orders retrieved from SAP B1 SL in App4Sales.
Add Reference and Your Reference to the NumAtCard field in SAP: (Boolean) If enabled, combines App4Sales 'Reference' and 'Your Reference' into the 'NumAtCard' field for orders.
Default custom order field values: (JSON) Allows mapping of default values to custom fields (User Defined Fields) in SAP B1 SL for orders.
Do not send prices to ERP: (Boolean) If enabled, price, discount, and line total information is not sent to SAP B1 SL.
Send discount of 0 on order header to ERP: (Boolean) If enabled and 'Do not send prices to ERP' is disabled, forces the order header discount to 0.
Do not send DocTotal to ERP: (Boolean) If enabled, the calculated document total is not sent to SAP B1 SL.
Send VAT number in FederalTaxID field: (Boolean) If enabled, the VAT number is sent in the FederalTaxID field instead of the default VATRegistrationNumber.
Country codes that are VAT liable: (CSV) A semicolon-separated list of country codes. If the delivery address country is in this list, `TaxPercentagePerRow` and `VatGroup` are explicitly set on the order line.
UOM Entry value for not complete package sizes: (Integer) Specifies a Unit of Measure Entry value to use for order and quotation lines when the quantity is not a complete package size.

Known Limitations

The connector does not explicitly handle separate charge lines for freight, payment fees, or other surcharges when sending to SAP B1 SL. These amounts are expected to be incorporated into order line prices or header totals within App4Sales before transmission.
No explicit handling or mapping for attachments (PDF, images, custom payloads) is observed in the `SendOrderToBackoffice` process.
The logic for `NumAtCard` and `Comments` differs between orders and quotations/invoices.
The UoM (Unit of Measure) logic for `Quantity` and `UoMEntry` is only applied to orders and quotations, not invoices.

SAPB1SL - Send order