MultiversExtendedV3 - Item Update

This document describes the process of synchronizing item data from Multivers Extended V3 to the App4Sales platform. The connector retrieves product information, pricing, stock levels, and various attributes from the Multivers API and maps them to the App4Sales data model.

Data Source Configuration

The connector retrieves data from a Multivers Extended V3 environment. The base URL for the API is configured in the administration settings. The following API endpoints are used to retrieve item-related data:

Products: /api/product - Retrieves the main product data. Filtered by inactive=false and blocked=false.
Product Groups: /api/productgroup - Used for item categorization.
Product Categories: /api/productcategory - Used for item categorization.
Product Attributes: /api/productattribute and /api/productattributevalue - To retrieve item attributes (item classes/free fields).
Product Notes: /api/productnote, /api/productlanguagenote, and /api/productextendedlanguagenote - To retrieve item descriptions and notes.
VAT Rates: /api/vatrate - To retrieve VAT information.
Stock: /api/stock - To retrieve stock information. Can be filtered by warehouse.
Price Lists: /api/pricelist - To retrieve price lists.
Price List Prices: /api/pricelistprice or /api/pricelistpriceV2 - To retrieve prices for price lists. Filtered by StartDate and EndDate to get current prices.
Tier Prices (Discounts): /api/discountproductdiscount - To retrieve tier prices.
Customer Specific Prices: /api/customerspecificprice - To retrieve prices specific to a customer.
Customer Group Discounts: /api/discountproductgroupdebtor and /api/discountproductgrouppricelist - To retrieve discounts for customer groups.
Unit Relations: /api/unitrelation - Used to determine the purchase package size.

Data Mapping Table: Items

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
ItemCode	ProductCode, UnitCode	Generated by combining ProductCode and UnitCode, separated by an underscore, if the setting 'ItemCodeIncludesUnitCode' is enabled. Otherwise, it's just the ProductCode.
InternalItemCode	ProductCode	The original product code from Multivers.
Description	Description	The main description of the product. Can be overridden by a language-specific description from ProductLanguageNotes.
Description2-5	ProductLanguageNotes.Text	Additional descriptions from language-specific notes. The mapping is based on the language code.
SearchDescription	SearchName, SearchKeys, ProductEanSynonyms.EanCode	A semicolon-separated string of search name, search keys, and EAN synonyms.
EanCode	EanCode	The EAN code of the product.
Unit	UnitCode	The unit of measure for the item.
PurchasePackageSize	- UseProductAttributeForPurchasePackageSize (Setting) - UnitRelations.relationFactor	Determined either by a specific product attribute (defined in settings) or from a unit relation between the packing unit and the sales unit.
VatPercentage	VatRates.VatPercentage	The VAT percentage for the item, derived from the item's VAT group.
Currency	ProductBaseCurrencySymbol (Setting)	The currency for the item's base sales price. This is a hardcoded value from the connector settings.
VatIncluded	'E'	Hardcoded to 'E' (Excluded).
IsActionItem	- RetrieveActionPriceLists (Setting) - BasePriceListCodeForItemSalesPrice (Setting)	Boolean flag indicating if the item is part of a promotion. True if action price lists are retrieved and the item exists on a special 'Action' price list.
AcceptsDefaultDiscount	- IsActionItem	Boolean flag that is the inverse of IsActionItem.
ItemStatus	- ItemStatusFieldName (Setting) - ProductCategories.ProductCategoryCode - ProductAttributes.Value	The item status (e.g., 'Verwacht', 'Nieuw'). The source is determined by the 'ItemStatusFieldName' setting, which can point to either a product category or a product attribute.
ItemGroupLinks	ProductGroups	Links the item to one or more item groups.
ItemCategories	ProductGroups, ProductAttributes, ProductExtendedLanguageNotes, UnknownElements	Item attributes, free fields, and classifications are mapped to App4Sales item categories. This includes product groups, product attributes, extended language notes, and any other "unknown" fields from the API response.

Data Mapping Table: Item Prices

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
SalesPrice	ProductSalesPrices.Price, PriceListPrices.Price	The default sales price for the item. The connector first tries to get the price from the ProductSalesPrices endpoint. It can be filtered by currency using the 'CurrencyToRetrieveDefaultPrice' setting. As a fallback, it can also use a specific price list defined in the 'BasePriceListCodeForItemSalesPrice' setting. If 'DivideSalesPriceByPricePer' is enabled, the price is divided by the 'PricePer' field.

Data Mapping Table: Price Lists

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
PriceList.Code	PriceList.PriceListCode, PriceListPrice.CurrencyCode	The code of the price list. If 'RetrieveMultipleCurrencyPricelists' is enabled, the currency code is appended to the price list code (e.g., 'PL01_EUR').
PriceList.Description	PriceList.Description	The description of the price list.
PriceList.Currency	PriceListPrice.CurrencyCode, BaseCurrencyCode (Setting)	The currency of the price list. If not present in the price list price, the 'BaseCurrencyCode' from the settings is used.
PriceListPrice.Price	PriceListPrice.Price, PriceListPrice.LadderLines.Price	The price for an item on a specific price list. If the price on the main price list price is 0, the price from the first tier (ladder line) is used.

Data Mapping Table: Tier Prices (StafflePrice)

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
ItemCode	DiscountProductDiscount.ProductIdentifier.ProductCode, UnitCode	The item code for the tier price.
CustomerCode	CustomerSpecificPrice.DebtorCode, DiscountProductGroupDebtor.DebtorCode	The customer code for customer-specific tier prices or discounts.
ItemGroup	DiscountProductGroupDebtor.ProductGroupCode, DiscountProductGroupPriceList.ProductGroupCode	The item group for item group-based discounts.
MinQuantity	DiscountProductDiscount.LadderLines.QuantityFrom	The minimum quantity for the tier price to apply.
Price	CustomerSpecificPrice.Price, DiscountProductDiscount.LadderLines.Price	A fixed price for a certain quantity.
Discount	DiscountProductDiscount.LadderLines.DiscountPercentage, DiscountProductGroupDebtor.DiscountPercentage, DiscountProductGroupPriceList.DiscountPercentage	A discount percentage for a certain quantity, item group, or customer.
PriceListId	-	The ID of the price list the tier price belongs to. This can be a standard price list or a dynamically generated one for customer discounts.

Data Mapping Table: Stock

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
LastAvailableStock	-	The calculated available stock. By default, this is calculated based on a formula using other stock fields. If 'UseAvailableStockFromME' is enabled, it uses the 'AvailableStock' from the API directly.
ShelfStock	FreeStock, ActualStock	The physical stock on the shelf. Can be based on either 'FreeStock' or 'ActualStock' from the API, depending on the 'UseActualStockAsShelfStock' setting.
NextDelivery	StockOverview.DateOfEvent, NextDateAvailable	The next expected delivery date for the item. Can be sourced from the 'NextDateAvailable' field or calculated as the minimum 'DateOfEvent' where there is a positive stock mutation.
StockIndicator	StockOverview.AvailableAtDate	A stock indicator (-1 for out of stock, 1 for in stock). If the setting 'StockIndicatorBasedOnEvents' is true, it is set to -1 if the available stock at any point in the future drops to or below 0.

Special Logic & Filters

Partial Sync: The connector supports partial synchronization of items based on a 'change number'. If enabled, only items that have been modified since the last sync are retrieved.
Item Filtering: The item sync can be filtered by product classification or product group using the 'SyncOnlyItemsFromProductClassification' and 'ProductGroupCodeForItemSync' settings. It can also be filtered by items having a specific attribute value with the 'SyncOnlyItemsWithAttributeValue' setting.
Action Prices: If 'RetrieveActionPriceLists' is enabled, the connector creates special "Action" price lists for items with promotions. These price lists are selectable in the app.
Customer Discounts: The connector can create separate price lists for different customer discount percentages. This is determined by the 'CustomerDiscountProductGroupCode' setting.
Tier Price Sync: The synchronization of tier prices can be enabled or disabled with the 'SyncTierPrices' setting.

Domain Specifics

Price Logic

The connector has a multi-layered approach to pricing. The base sales price is determined first. Then, price lists are synchronized, which can have different prices per item and currency. Tier prices (staffle prices) are also supported, which can be based on quantity, customer, or item group. Finally, customer-specific prices can override all other prices.

Stock & Availability

Stock is retrieved from the /api/stock endpoint and can be aggregated from multiple warehouses if no specific warehouse is configured in the settings. The final 'Available Stock' figure can be calculated using a formula that combines shelf stock, reserved stock, and incoming/outgoing goods. The connector can also show various other stock fields like blocked stock, and stock to be delivered/received.

Matrix & Attributes

The connector maps product attributes from Multivers to App4Sales item classes and free fields. Product groups and categories are used to create a hierarchical structure, which is represented as item groups and item categories in App4Sales. The connector also supports multi-level item categories.

Related Settings & Prerequisites

ItemCodeIncludesUnitCode: If true, the unit code is included in the App4Sales item code.
SyncTierPrices: Enables or disables the synchronization of tier prices.
BasePriceListCodeForItemSalesPrice: Defines the price list to be used for the default sales price of an item.
UseProductAttributeForPurchasePackageSize: Specifies a product attribute to be used for the purchase package size.
ItemStatusFieldName: The name of the product category or attribute that holds the item status.
RetrieveMultipleCurrencyPricelists: If true, creates separate price lists for each currency.
Warehouse: The warehouse to get stock from. If empty, stock is aggregated from all warehouses.
UseAvailableStockFromME: If true, the 'AvailableStock' from Multivers is used directly, otherwise a formula is used.
SyncOnlyItemsFromProductClassification: Filters items based on a product classification.

MultiversExtendedV3 - Item sync