Erply API version 1.13.0 – 1.13.5

New features

Price list management

• For more fine-grained price list management, new API calls have been added to add or remove individual product prices from the price list: addProductToPriceList,editProductInPriceList, deleteProductInPriceList. Also, the product prices in a price list can be fetched page-by-page with new API call getProductsInPriceList.
  • It is still possible to define the whole price list and its contents with the savePriceList API call. The new calls offer just an alternative that may be useful on some occasions — when working with very large price lists, for instance.
• API call deletePriceList has been added.
• Filter "pricelistIDs" has been added to API call getPriceLists, for retrieving multiple price lists by ID.
• The following input parameters have been added to API call getPriceLists, to filter price lists by activity period:
  • startDateFrom
  • startDateTo
  • endDateFrom
  • endDateTo

“Store Regions” module

• This is a new extra feature. “Store regions” can be used to group stores, and apply price lists to groups of stores.
• Please contact customer support to enable it on your account.
• This feature is only available in Classic back office and requires back office version 4.5.0 or newer.
• Installing this module enables:
  • Output field and filter "storeRegionID" in API call getWarehouses;
  • Input field "storeRegionID" in API call saveWarehouse;
  • New API calls for managing store regions: getStoreRegions, saveStoreRegion, deleteStoreRegion;
  • New API calls for associating price lists with store regions, and for removing these associations: addStoreRegionPriceList, editStoreRegionPriceList,removeStoreRegionPriceList, getStoreRegionsAssociatedWithPriceList.
• Furthermore, price lists can also be associated with a combination of store region and customer group: so that the price list will only apply in that region, and only to customers belonging to the specified group. Installing this extra module enables also the following API calls: addStoreRegionCustomerGroupPriceList,editStoreRegionCustomerGroupPriceList, and removeStoreRegionCustomerGroupPriceList.

Regional or customer group-specific promotions

• This is an extra feature which allows to specify that a promotion applies only in certain regions, and/or only to specific customer groups.
• Please contact customer support to enable it on your account. It also requires the “Store Regions” module that has been mentioned above.
• This feature is only available in Classic back office and requires back office version 4.5.0 or newer.
• This module enables:
  • Filters "storeRegionIDs" and "customerGroupIDs" in API call getCampaigns.
  • Output fields "storeRegions" and "customerGroups" in API call getCampaigns.
  • Input parameters "storeRegionIDs" and "customerGroupIDs" in API call saveCampaign.

Information about applied price list discounts, and applied manual discounts

• When these extra features are enabled, Berlin POS starts reporting not only which promotions applied to each sale, but also:
  • Which price lists applied, and how much discount each price list gave;
  • How much manual discount was applied. (Manual discount is applied by the cashier in POS by editing price, specifying a discount percentage, or by clicking one of the predefined discount % buttons.)
• Both of these (applied price lists, and applied manual discounts) are extra modules. Please contact customer support to enable one or both of them on your account.
• This information does not have a user-visible output (a report) yet, but it can be retrieved with API call getAppliedPromotionRecords. The records returned from getAppliedPromotionRecords will no longer always have a field named "promotionID"; some of the records (those that indicate that a price list discount applied) have a field named "priceListID" instead, and records indicating manual discount will have neither.
• This feature also requires Classic back office, version 4.5.0 or newer. Also, Berlin POS version 3.25 or newer is highly recommended.
• With Classic back office version 4.5.0, the applied discounts (promotion, price list and manual discounts) can also be printed on a receipt.

Price list discount shown as discount, on receipt and in printouts

• Configuration parameter "treat_price_list_discount_as_discount_on_receipt" has been added. With that parameter enabled, sales made from Berlin POS are adjusted so that any discounts from price lists are displayed as discounts. The “-…%” number will include price list discounts, and the “original price”, if it has been enabled, will also show pre-price list price.
  • This only works with online receipts printed from Berlin POS.
  • Additionally, at least the “Promotion Report” and “Applied Price Lists” extra modules must be be enabled (see above), and the “Applied Manual Discounts” module is recommended as well.

“POS multicurrency” module

• This is an extra feature which allows to count the cash in the register in Berlin POS in multiple currencies.
• Please contact customer support to enable it on your account.
• It also requires Berlin POS version 3.25 or newer, and customer support must apply configuration parameter "touchpos_sale_additional_currencies" to define which currencies need to be counted in POS.
• This feature also requires Classic back office, version 4.5.0 or newer.
• When the module is enabled, the following extra fields in API can be used:
  • Input parameter "currencyCode" in API calls POSOpenDay, POSCloseDay, getPointOfSaleDayTotals and getDayClosings.
  • Output field "currencyCode" has been added to API call getDayClosings.

Package support on documents

• API calls saveSalesDocument, savePurchaseDocument, saveInventoryRegistration, and saveInventoryTransfer now support packages and package quantities for each document row. It is possible to specify, for example, that the item was sold/purchased/received not only in a quantity of 150, but as 15 boxes of 10 pcs. each.
• Each of these API calls has the following new input parameters (“#” signifies document row number):
  • packageID#
  • amountOfPackages#
• API calls getSalesDocuments, getPurchaseDocuments, getInventoryRegistrations, and getInventoryTransfers output the same information. Each of these API calls has the following new fields for each document row:
  • packageID
  • amountOfPackages
  • amountInPackage
  • packageType
  • packageTypeID
• Note that package support on Inventory Registrations and Inventory Transfers is not enabled by default. You might need to contact customer support to have it enabled.

Management of “locations in warehouse”

• For managing the classification of “warehouse locations”, new API calls getLocationsInWarehouse, saveLocationInWarehouse, and deleteLocationInWarehouse have been added.
• Filters "locationInWarehouseIDs" and "locationInWarehouseText" have been added to API call getProducts.
• Output fields "locationInWarehouseID", "locationInWarehouseName" and "locationInWarehouseText" have been added to API call getProducts.
• Input parameters "locationInWarehouseID" and "locationInWarehouseText" have been added to API call saveProduct.

New promotion type

• New promotion type has been added: buying a predefined quantity or more of a product, or from a set of products, will reduce the price of all units by a discount amount, or a discount percentage.
• For example: “Buy 3 soups or more and get $2 off each”. If customer buys 3, 4, 5, 6, … soups, all the items (the first three as well as all subsequent ones) will get the discount.
• API call calculateShoppingCart will apply this promotion, and fields "percentageOffMatchingItems" and "sumOffMatchingItems" have been added to API calls getCampaignsand saveCampaign.
• To be able to specify this type of promotion in back office, you need Classic back office version 4.5.0 or newer.

“Assortments” module

• This API version adds preliminary support for “assortments”, ie. ability to specify different product selections for different stores.
• This feature is not functional yet; it is only possible to define the assortments and modify their contents, but they are not being enforced yet. All products can be sold and purchased as usual in POS and in back office, regardless of whether they belong to the particular store’s assortment or not.
• The exact way how assortments are going to work, and what features they are going to provide, has not been fully specified yet.
• Please contact customer support to enable it on your account.
• This module enables:
  • New API calls: getAssortments, saveAssortment and deleteAssortment.
  • For retrieving and modifying the contents of an assortment, the following new API calls: getAssortmentProducts, addAssortmentProducts, editAssortmentProducts,removeAssortmentProducts.
  • Field "assortmentID" in API calls getWarehouses and saveWarehouse.

“Price list types” module

• This is an extra feature for classifying price lists into store price lists and retail chain-wide price lists — and applying more specific user rights.
• With this extra module activated, users without the right to “Create and edit price lists with other types besides “Store Price List”” are not able to edit, or delete, a price list whose type is not “Store Sale Price List”.
• Please contact customer support to enable it on your account.
• This feature is only available in Classic back office and requires back office version 4.5.0 or newer.
• Installing this module enables:
  • Field "type" in API calls getPriceLists and savePriceList. Please note that when the “Price list types” module gets activated, field “type” becomes a required field in savePriceList. For ERPLY to be able to enforce user rights, it is important that all price lists be classified into categories.
  • Input parameter "types" in API call getPriceLists, to filter price lists by type. This parameter accepts a comma-separated list of type codes.
  • Flag "rightEditRetailChainPriceLists" in API call getUserRights.

“Price list row subsidy and other fields” module

• This is an extra feature for storing more information attached to a price list row, or a promotion. These additional fields are customer-specific and ERPLY’s standard functionality does not rely on these fields.
• Please contact customer support to enable it on your account.
• This feature is only available in Classic back office and requires back office version 4.5.0 or newer.
• Installing this module enables:
  • New API calls getSubsidyTypes, saveSubsidyType and deleteSubsidyType.
  • Fields "subsidy", "subsidyTypeID", "page", "positionOnPage" and "forecastUnits" in API calls getProductsInPriceList, addProductToPriceList, andeditProductInPriceList.
  • The same fields in API calls saveCampaign and getCampaigns.

Customer’s “associations” and “professionals”

• A customer can have two types of related customers: “associations” and “professionals”. This feature, and this terminology, is specific to one customer and ERPLY’s standard functionality does not rely on this information.
• New API calls saveCustomerAssociation, deleteCustomerAssociation, saveCustomerProfessional, and deleteCustomerProfessional have been added.
• A list of linked customers can be retrieved with API call getCustomers. Specify input flag getAssociationsAndProfessionals = 1. The returned records will have blocks named associations and professionals.

Dashboard API calls

• New API calls getSalesTotalsByEmployeeAndMonth, getSalesTotalsByWarehouseAndMonth, getSalesTotalsByEmployeeAndDay, and getSalesTotalsByWarehouseAndDay have been added.

Other new features

• API call getConfParameters reports the status of more modules (whether these extra modules are installed or not).
• New API calls convertPOSLanguageIdentifier and convertAPILanguageIdentifierForPOS have been added. These are used by Berlin POS.
• It is now possible to set up a new franchise chain so that the HQ account will see all locations (warehouses), but each franchisee account will see only its own locations. This will also require Classic back office version 4.5.0 or newer.
• New API call getTaxOffices has been added, and field "taxOfficeID" has been added to API calls saveCustomer and getCustomers. This is a Greece-specific feature.
• New API call getHomeStores has been added. In a franchise, the list of “home stores” or “sign-up stores” may not be the same as the list of account’s own stores. Therefore, when populating a “Home Store” / “Sign-up store” drop-down list with options — regardless of whether it is a franchise account or a regular account — it is recommended to use API call “getHomeStores”, instead of “getWarehouses”.
  • The call will also omit any locations that have been designated as “offline warehouses” for returns.
• Canada-specific field "gstExemptTaxRateID" has been added to API calls getVatRates and saveVatRate.
• API call saveSalesDocument can now create invoices that are associated with a recurring billing. The following input fields have been added:
  • billingStatementID#
  • billingStartDate#
  • billingEndDate#
• The same fields can also be retrieved through getSalesDocuments. The following output fields have been added to each document row: billingStatementID, billingStartDateand billingEndDate.

Improvements

• A few improvements have been made to the customer and product search indexes which were added in version 1.12.1.
• New partner keys have been added.
• A few deprecated and undocumented calls have been removed.
• When a location (warehouse) does not have a name in a particular language, API calls getWarehouses and getAllowedWarehouses will return it as-is (an empty string), not the name in English instead.
• Input parameter "code" has been added to API call getWarehouses, to look up one specific warehouse by its code.
• Location code can now be modified with API call saveWarehouse.
• Fields "promotionName" and "priceListName" have been added to API call getAppliedPromotionRecords. These return the name of the price list or promotion that applied to a sale (in addition to the promotion / price list ID, which was already available before).
• Output field "rowID" has been added to API calls getSalesDocuments (to each invoice row) and getAppliedPromotionRecords. This allows you to map applied promotion discounts and price list discounts to exact invoice rows.
  • Note, however, that row IDs on an invoice change every time an invoice is saved (as a sales document is a versioned object, and on each saving we create a new set of rows in the database), so you should not rely on these IDs when synchronizing data.
• API calls verifyUser, switchUser, and changePassword now return the endpoint URL and authentication token for “transaction history registry”. These can be found in the "transactionRegistryURLs" block. This is a special integration for one customer. There can be multiple endpoints and tokens configured; if that is the case, API clients must pick one.
• Fields "addedByUserName" and "lastModifiedByUserName" have been added to API calls getUserRights and getUserGroups.
• Field "lastModifiedByUserName" has been added to API call getEmployees.
• API call getUserOperationsLog can be queried for deleted user groups, using input parameter tableName = "userGroups".

Fixes

• The endpoint and authentication token of customer registry (added in version 1.12.4) are no longer returned as “customerRegistryURL” and “customerRegistryToken”. Instead, in the response of API calls verifyUser, switchUser, and changePassword, there is now a block named "customerRegistryURLs" which can define multiple available endpoints.
• Fixed: API call getSalesReport returned an empty response when configuration parameter "users_can_see_only_own_warehouse_documents" = 1 had been applied.
• Fixed: all purchase orders created with savePurchaseDocument were assigned the same number.
• Fixed: it must not be possible to change the type of a confirmed purchase document with API call savePurchaseDocument.
• Input parameters "recordsOnPage" and "pageNo" in all API calls are now validated. A non-integer value will return an API error code.
• Fixed: API call getPriceLists with input parameter "getHeadersOnly" = 1 must still return price list attributes.