eAccounting Connector - Create Customer
This document details the process by which new customer data from App4Sales is transmitted to and created within the eAccounting ERP system. The process handles both the creation of new customers and the updating of existing customer records if a matching customer number is provided.
Trigger & Permissions
The customer creation/update flow is triggered by a request from the App4Sales application (e.g., when a sales representative creates a new customer on their mobile device or when backoffice sync initiates an update). This functionality is enabled when the connector is configured with `ConnectorInfoInternalIds.CreateCustomer` or `ConnectorInfoInternalIds.EditCustomer` flags.
Data Source Configuration
The App4Sales system sends customer data as an XML payload, which is then deserialized into an `XmlCustomer` object. This XML typically contains customer details such as name, addresses, contact information, and financial settings. The structure of the incoming XML is expected to conform to the `NewCustomers` root element containing one or more `Customer` elements, each representing an `XmlCustomer` object.
Payload Mapping
Customer Header Fields
App4Sales Field (XmlCustomer) | Source Field (XML Element) | Logic/Notes |
CustomerCode | debCode | Maps directly to the eAccounting `CustomerNumber`. If this field is empty, a new customer will be created. Otherwise, an existing customer with this number will be updated. |
CustomerGuid | customerGuid | Unique identifier for the customer in App4Sales. Used to update the internal code after successful creation in eAccounting. |
CustomerName | customerName | Maps directly to the eAccounting `Name` field. |
ContactFullName | contactFullName | Maps to eAccounting's `ContactPersonName`. |
contactEmail | Maps to eAccounting's `ContactPersonEmail` and `EmailAddress`. | |
CustomerEmail | customerEmail | Not directly mapped to the eAccounting Customer entity in `ConvertToEntity`. |
Fax | contactFax | Not directly mapped to the eAccounting Customer entity in `ConvertToEntity`. |
Phone | contactPhone | Maps to eAccounting's `ContactPersonPhone`. |
CustomerPhone | customerPhone | Not directly mapped to the eAccounting Customer entity in `ConvertToEntity`. |
Mobile | mobilePhone | Maps to eAccounting's `MobilePhone`. |
LanguageCode | languageCode | Not directly mapped to the eAccounting Customer entity in `ConvertToEntity`. |
CountryCode | countryCode | Maps to eAccounting's `InvoiceCountryCode` and `DeliveryCountryCode`. |
Discount | discount | Parsed as a decimal and divided by 100 to map to eAccounting's `DiscountPercentage`. Expects a percentage value (e.g., "10" for 10%). |
PaymentCondition | paymentCondition | Used to look up the external ID of the payment condition in App4Sales's `PaymentConditionsContext`. If not found, the `paymentCondition` value itself is used as `TermsOfPaymentId`. |
VatCode | vatCode | Maps to eAccounting's `VatNumber`. |
IsVatLiable | isVATLiable | Evaluated to a boolean. Not directly mapped to eAccounting Customer entity in `ConvertToEntity`. The VAT liability is determined by `Settings.SetVatLiableOnCountryCode` or `ReverseChargeOnConstructionServices` from the eAccounting entity. |
ChamberOfCommerceCode | chamberOfCommerceCode | Maps to eAccounting's `CorporateIdentityNumber`. |
Website | website | Not directly mapped to the eAccounting Customer entity in `ConvertToEntity`. |
DeliveryMethod (from UnknownElements) | Derived | If present in `XmlCustomer.UnknownElements` with the key "DeliveryMethod", it maps to eAccounting's `DeliveryMethodId`. |
IsActive | Hardcoded | Hardcoded to `true` for new/updated customers in eAccounting. |
Address Fields
App4Sales Field (XmlCustomer) | Source Field (XML Element) | Logic/Notes |
VisitAddress1 | visitAddress1 | Maps to eAccounting's `InvoiceAddress1`. |
VisitAddress2 | visitAddress2 | Maps to eAccounting's `InvoiceAddress2`. |
VisitPostCode | visitPostCode | Maps to eAccounting's `InvoicePostalCode`. |
VisitCity | visitCity | Maps to eAccounting's `InvoiceCity`. |
VisitState | visitState | Not directly mapped to the eAccounting Customer entity in `ConvertToEntity`. |
DeliveryAddress1 | deliveryAddress1 | Maps to eAccounting's `DeliveryAddress1`. |
DeliveryAddress2 | deliveryAddress2 | Maps to eAccounting's `DeliveryAddress2`. |
DeliveryPostCode | deliveryPostCode | Maps to eAccounting's `DeliveryPostalCode`. |
DeliveryCity | deliveryCity | Maps to eAccounting's `DeliveryCity`. |
DeliveryState | deliveryState | Not directly mapped to the eAccounting Customer entity in `ConvertToEntity`. |
CountryCode (from XmlCustomer) | countryCode | Used for both `InvoiceCountryCode` and `DeliveryCountryCode` in eAccounting. |
Validation & Defaults
If no customer data is received in the request, an error is returned.
`IsActive` is always set to `true` when creating or updating a customer in eAccounting.
`DiscountPercentage` is derived from the `discount` field, assuming it's a percentage (e.g., "10" for 10%), and converted to a decimal (divided by 100).
`TermsOfPaymentId` is first looked up from `PaymentConditionsContext` based on `PaymentCondition`. If not found, the raw `PaymentCondition` value is used.
If `Settings.SetVatLiableOnCountryCode` is set, `VatLiable` is determined by whether the `InvoiceCountryCode` matches this setting; otherwise, it's determined by `ReverseChargeOnConstructionServices` from the eAccounting entity (which is not directly mapped from `XmlCustomer`).
Response & Error Handling
After the eAccounting entity is prepared, the connector attempts to create or update the customer via the eAccounting API:
If `CustomerCode` in the incoming `XmlCustomer` is empty, a new customer is created using a `POST` request to the eAccounting API. The `Id` returned by eAccounting is then stored internally using `CustomersContext.Instance.UpdateInternalCode` with the `customerGuid` from the request.
If `CustomerCode` is present, an existing customer is updated using a `PUT` request to the eAccounting API, identified by its `Id` (derived from `CustomerCode` using `CustomersContext.Instance.GetInternalCode`).
Upon successful creation or update, the `CustomerNumber` from the eAccounting API response is returned.
Any exceptions during the process, including API errors, are caught, logged, and an error message is returned to the caller, prefixed with "ERROR".
Special Logic & Filters
The primary logic differentiates between creating a new customer and updating an existing one based on whether `CustomerCode` is provided in the incoming XML.
The `DeliveryMethodId` is pulled from `XmlCustomer.UnknownElements` if a key matching `EAccountingConnector.DeliveryMethod` (which is "DeliveryMethod") exists. This allows for dynamic inclusion of delivery method information.
Related Settings & Prerequisites
Set VAT Liable On Country Code: (Setting from `Administrations.ConnectorSettings.EAccounting`) If configured, this setting determines the VAT liability based on the invoice country.
Known Limitations
The incoming `XmlCustomer` contains fields like `CustomerEmail`, `Fax`, `CustomerPhone`, `VisitState`, `DeliveryState`, `LanguageCode`, and `Website` that are not currently mapped to the eAccounting Customer entity during the creation/update process.