Erply's main focus is to be a good transaction system, not a content delivery network (CDN). Therefore, any content shown to the user must be served from the web shop's local database, or from an actual CDN. Do not implement a solution where product listings are displayed directly from API. This is also why we enforce an API rate limit: at most 1000 requests every hour.
For a web shop integration, the product catalog, prices, quantities in stock, and other data sets need to be downloaded to web shop database. After the catalog has been fully downloaded, you can regularly pull incremental updates to keep the catalog in sync.
Only the following operations can be implemented as "live queries" to Erply API:
Use getProducts for both the full download and incremental updates. See our guide for data synchronization.
To retrieve names of the product classifiers (groups, categories etc.), see: getProductGroups, getProductCategories, getBrands, getProductPriorityGroups, getProductUnits, getSuppliers.
For matrix products, getProducts gives a reasonably complete set of information (eg. what is a particular variation's parent, what is its size and color). To get a full list of matrix dimensions and the list of values within each dimension, see getMatrixDimensions.
Use getProductStock to sync inventory quantities. If you want to factor in the amounts already ordered from suppliers (but not yet received), see getAmountsOnOrder.
getVatRates returns the list of tax rates defined in Erply.
Here you can read more about how the product catalog works.
For the sync to work correctly, you need to query for ALL changed products. It is OK to write only a subset of the products into the web shop's database (eg. only products with status "active", or products with check box "Web shop product"), but your synchronization procedure must nevertheless ask for all changes.
This ensures that you will correctly handle all status changes. (A product changed from "archived" to "active" needs to be added to web shop database; a product changed from "active" to "archived" must be deleted from web shop database.)
getProducts can return a lot of different information: inventory quantities, costs, price list prices etc. However, be careful: this information is just provided as a reference, and is not part of the product's description. When a quantity in stock, or item's cost, or price list price changes, this does not mean that the product itself has changed! getProducts will not notify you about these changes, and you cannot sync them.
The following concepts are an inseparable part of a product's definition. Whenever these properties change, the product's "last modified" timestamp updates as well:
The following concepts are independent of products. Whenever these properties change, the product's "last modified" timestamp DOES NOT update:
Additionally, if product's group (or category, brand, supplier) stays the same, but you change the NAME of that particular category, brand, or supplier, the product's "last modified" timestamp does not change. Therefore, you need to synchronize product groups and categories separately.
A product's "store price" is a result of all regional price lists and store price lists applied on top of each other in order of priority. The resulting "store prices" cannot, unfortunately, be synced directly. For webshop pricing, you can consider the following options:
Sync customers to webshop, or query the information of one specific customer, with API calls getCustomers and getAddresses.
See getCustomerGroups if needed.
Use saveCustomer, deleteCustomer, saveAddress, and deleteAddress to update customer information.
To record any data processing activities done with the customer, as required by General Data Protection Regulation (GDPR), use logProcessingOfCustomerData.
If customer's web shop user name and password are stored in Erply, use verifyCustomerUser to log them in.
For more elaborate solutions, you may need:
If you have configured reward point earning in back office, then confirming a sales transaction will add a respective amount of points to customer's account automatically; you do not need to issue any API calls for that to happen. Should you need to adjust their balance manually in other cases, there is also addCustomerRewardPoints.
Contents of the user's in-progress shopping cart (items and quantities selected) should be held in user's session data and not saved to Erply.
Use calculateShoppingCart to get up-to-date customer- and store-specific prices and taxes for the shopping cart, and to retrieve the cart's total value.
Use API call saveSalesDocument.
Typically, you should save the transaction as a Sales Order (type = ORDER) — even if the customer pays for the items immediately. Sales Order makes it much easier to handle partial shipping (if it happens that the item customer wanted is not actually in stock), and a Sales Order only "reserves" the items in stock, instead of subtracting the quantities immediately, thus more accurately reflecting the actual state of the warehouse.
If Sales Order, for some reason, is not suitable, create an Invoice-Waybill (type = INVWAYBILL).
To attach a payment to the document, use savePayment. Sales Orders can have payments, too.