SnelStart Connector - Item Update

This function synchronizes item data from SnelStart to the App4Sales platform. It retrieves items and their associated item groups and custom fields from the SnelStart API, applies transformations, and then updates the App4Sales item database. Items are processed in batches (if applicable) and can be filtered based on their active status.

Data Source Configuration

Item data is sourced directly from the SnelStart B2B API (https://b2bapi.snelstart.nl/v2). Authentication is performed using an OAuth2 password grant type, requiring a Subscription Key (Ocp-Apim-Subscription-Key header) and a base64 encoded username/password pair configured in the connector's settings (EnvironmentKey).

Items: Retrieved from the /artikelen endpoint. Supports OData filtering and pagination.
Item Groups: Retrieved from the /artikelomzetgroepen endpoint.
Custom Fields: Retrieved on a per-item basis from the /artikelen/{item_id}/customFields endpoint.

Data Mapping Table: Items

App4Sales Field	Source Field (API/Excel/DB)	Logic/Notes
ItemCode	SnelStart Item: `artikelcode`	The SnelStart item code, with leading/trailing whitespace removed.
Description	SnelStart Item: `omschrijving`	Direct mapping of the item's description.
InternalItemCode	SnelStart Item: `id`	The unique identifier (GUID) of the SnelStart item, converted to a string.
SalesPrice	SnelStart Item: `verkoopprijs`	Direct mapping of the item's sales price.
LastAvailableStock	SnelStart Item: `vrijeVoorraad` OR `technischeVoorraad`	Mapped conditionally based on the Use free stock setting. If enabled, `vrijeVoorraad` (Free Stock) is used; otherwise, `technischeVoorraad` (Technical Stock) is used. Free Stock requires the SnelStart 'inControle' module.
CreatedDate	SnelStart Item: `modifiedOn`	The date the item was last modified in SnelStart.
VatPercentage	Connector Setting: `DefaultVatPercentage`	The VAT percentage is not provided by the SnelStart item API and is set from a connector configuration setting.
ItemClasses	SnelStart Item Group: `omschrijving`	Derived from the SnelStart item group linked to the item (`artikelOmzetgroep`). The description of the item group (`omschrijving`) is used as an `ItemClassValue`. The `ItemClass` itself is hardcoded with "Artikelgroep" as its description and ID 1.
ItemCategories	SnelStart Item: `extraVelden` (Free Fields)	Each SnelStart free field (`extraVelden`) is mapped to an `ItemCategory`. The name of the free field (`name` from `definition`) becomes the `ItemCategory`, and its value (`value`) becomes the `TranslateableValue`.
EanCode	SnelStart Item: `extraVelden` (Custom Free Field)	If the Use custom field for EAN code setting is configured, the value of the specified custom free field is used. Otherwise, the EAN code is not mapped.
PurchasePackageSize	SnelStart Item: `extraVelden` (Custom Free Field)	If the Use custom field for purchase package size setting is configured, the value of the specified custom free field is parsed as a decimal and used. Otherwise, it is not mapped.

Special Logic & Filters

Inactive Item Synchronization: Items marked as inactive in SnelStart (isNonActief = true) are only synchronized if the Sync inactive items connector setting is enabled.
Stock Indicator Calculation: After mapping, the StockIndicator for each item is calculated. This can either be based on a formula defined in the connector's base settings (GetStockIndicatorByFormula) or by querying the Portal Server Provider (GetStockIndicator) using the item's LastAvailableStock.
API Request Handling: The connector includes retry logic for API calls (up to 5 retries), specifically handling rate limit (HTTP 429) and call volume quota errors by pausing execution.

Domain Specifics

Price Logic

The base sales price is mapped directly from verkoopprijs. The SnelStart API does not directly provide a VAT percentage on an item level; therefore, the App4Sales VatPercentage is populated from the Default VAT percentage connector setting.

Image Handling

The current implementation of the ItemUpdate method does not include logic for synchronizing product images from SnelStart to App4Sales.

Stock & Availability

The item's LastAvailableStock in App4Sales is populated from either the vrijeVoorraad (Free Stock) or technischeVoorraad (Technical Stock) fields in SnelStart, depending on the Use free stock connector setting. If Free Stock is used, it's important to note that this functionality relies on the 'inControle' module within SnelStart (FreeStock = TechnicalStock - reserved stock). A StockIndicator is then calculated based on the available stock, either via a predefined formula or an external service.

Matrix & Attributes

Item Classes: A single ItemClass named "Artikelgroep" is created, with its value derived from the omschrijving (description) of the SnelStart item group (artikelOmzetgroep) linked to the item.
Item Categories / Free Fields: All custom free fields (extraVelden) configured in SnelStart for an item are mapped to App4Sales ItemCategories. The name of the custom field becomes the category name, and its value is stored.
EAN Code: Can be mapped from a SnelStart custom free field if the Use custom field for EAN code setting specifies the name of the custom field.
Purchase Package Size: Can be mapped from a SnelStart custom free field if the Use custom field for purchase package size setting specifies the name of the custom field. The value of this custom field must be a valid decimal number.

Related Settings & Prerequisites

Sync inactive items: (Boolean) Controls whether inactive items from SnelStart are synchronized.
Default VAT percentage: (Decimal) The VAT percentage to apply to items, as it's not provided by the SnelStart item API.
Use free stock: (Boolean) If enabled, the connector uses vrijeVoorraad (Free Stock) from SnelStart for LastAvailableStock; otherwise, technischeVoorraad (Technical Stock) is used.
Use custom field for EAN code: (Text) Specifies the name of a SnelStart custom free field to use for the item's EAN code.
Use custom field for purchase package size: (Text) Specifies the name of a SnelStart custom free field to use for the item's purchase package size. The value of this field must be a valid decimal.
EnvironmentKey: (Encrypted Text) Contains the base64 encoded username and password for SnelStart API authentication.
SnelStartSubscriptionKey: (Text) The API subscription key required for accessing the SnelStart B2B API.

Known Limitations

The SnelStart API does not provide VAT percentage directly on the item, so a default value from connector settings is used.
Retrieval of custom fields is performed by making a separate API call for each item (/artikelen/{item_id}/customFields), which could impact performance for a very large number of items with custom fields.
Image synchronization is not implemented in this version of the connector.

SnelStart - Item sync