EasyWebshop API documentation
This document describes how to connect to the EasyWebshop API and how to write your own apps. It is intended for a technical audience familiar with programming and network protocols.
- Connecting payment service providers
- Connecting delivery services
- Connecting POS software, local and cloud
- Importing products from suppliers or wholesalers via XML
- Exporting products for comparison sites
- Connecting invoicing software
- Connecting CRM software
- Connecting logistics management software
- Updating stock (inventory) in real-time
- Accepting or denying customers based on certain criteria
- Exporting orders in real-time for dropshipping
- Exporting customers for newsletter applications
- Exporting data for reports and analytics
To retrieve and send data we use REST. The data is sent and received in JSON or XML format over HTTPS. The encoding used is UTF-8. For the implementation into an application the free cURL tool can be used.
This approach has a lot of advantages:
- Easy to implement
- Secure data transfer (no more insecure FTP connections)
- Real-time communication
- No additional servers or extra databases required
- Scalable to larger volumes of data
- Can be used with any platform, framework and programming language
- No problems with firewalls
- Makes use of XML, JSON and HTTP standards
API vs API PUSH vs Apps
|Use the API for creating a custom connection for a specific customer.||Use the API PUSH for creating a custom connection for a specific customer.||Use apps for creating a connection that all EasyWebshop merchants can install themselves.|
|Ideal for importing and exporting categories, products, orders and customers.||Ideal for synchronizing stock or accepting customers in real-time.||Ideal for PSPs, delivery services, installing widgets, comparison sites, POS and invoicing applications.|
|Authentication in the backend via the API module.||Enter PUSH URL in API module.||Authentication in the backend via Apps.|
How to start?
- Use an existing shop or create a new shop
- Adjust the user level to Expert, at Settings > User experience level
- Relax! It's easier than it looks
Activate the EasyWebshop API at Settings > Modules > Easywebshop API using the activation code MODA.
You can create a separate API user at Settings > Modules > Administrator accounts. This improves security: the API user can only use the API and cannot log in into the shop management.
Test your XML code without using cURL.
Please cache your data, limit the number of API requests and limit data transfers as much as possible. Only query or update what you need. Do not use polling, use our PUSH functions instead. To prevend excessive querying, the API will automatically respond slower when many queries are sent.
Enter the URL of your application at Settings > Modules > Easywebshop API. You can test your connection using the buttons New customer and New order.
Apps can bypass the API authentication if a merchant installs them. For this, you need an App key. Contact us to receive your personal app key.
- Describe the purpose of your app
- Provide the URL where the app will be installed
The default output format is XML. You can change this by adding the query string ?format=json. Add pretty=1 to format the JSON data with whitespaces for improved human readability. Remove this to save bandwidth in automated systems.
- Retrieve all categories
- Retrieve all categories in human readable JSON format
- Retrieve a specific category
- Retrieve the last 1000 products
- Retrieve products of the last 24h
- Retrieve products within a category
- Retrieve product using the product code
- Retrieve the last 100 orders
- Retrieve orders from the last 24h
- Retrieve the last 100 customers
- Retrieve the last 10 customers
- Retrieve a specific customer
Importing products with cURL:
curl -X POST -u firstname.lastname@example.org:linktest -d @products.xml https://www.easywebshop.com/api/product
Change the log in credentials and the file to be imported so it matches your data. The XML file products.xml should have the following layout:
If your import succeeded you will see 201 Created.
Up to 1000 products can be imported at once. This limit prevents overloading our servers. If you want to import more products, you can repeat the command once per minute.
Updating products with cURL:
curl -X PUT -u email@example.com:linktest -d @update.xml https://www.easywebshop.com/api/product
Change the log in credentials and the file to be imported so it matches your data. The XML file update.xml should have the following layout:
Up to 5000 products can be updated at once. This limit prevents overloading our servers. If you want to update more products, you can repeat the command once per minute.
Updating product stock with cURL:
curl -X PUT -u firstname.lastname@example.org:linktest -d @updatestock.xml https://www.easywebshop.com/api/product
If the product is sold out, change the product status to Sold Out.
Possible product statuses:
- Available 2-3 days
- Available 7-9 days
- Available but not in stock
- Available but not online
- Request Offer
- Sold Out
- Customers only
- Price visible for customers
- Choose property
- Hide status
Adding or updating product photos with cURL:
curl -X PUT -u email@example.com:linktest -d @uploadimage.xml https://www.easywebshop.com/api/productimage
The XML file uploadimage.xml must have the following layout:
In the XML file, the URL of the product images are included. The first image always is the main photo, the next four are sub photos. When a product photo already exists, it will be replaced automatically. The images are scaled proportionally according to the standard size or, if set, according to the dimensions defined in the high quality photo module. Up to 5 photos per product can be added. The maximum file size is 5MB per photo, the supported formats are .png, .jpg and .gif. If you want to add more product photos, you can repeat the command once per 15 seconds.
If the command succeeded you will see 200 OK.
Deleting products with cURL:
curl -X DELETE -u firstname.lastname@example.org:linktest https://www.easywebshop.com/api/product/LA-B03
If the product is successfully deleted you will see 200 OK.
Updating orders with cURL:
curl -X PUT -u email@example.com:linktest -d @updateorder.xml https://www.easywebshop.com/api/order
Possible order statuses:
- Order received
- Waiting for payment
- Payment received
- Products sent
Accepting or denying customers with cURL:
curl -X PUT -u firstname.lastname@example.org:linktest -d @updatecustomer.xml https://www.easywebshop.com/api/customer
You can deny the customer by sending 1 in the XML file. To accept the customer, set 0 in the denied tag.
Deleting customers by e-mail address with cURL:
curl -X DELETE -u email@example.com:linktest https://firstname.lastname@example.org
If the command succeeded you will see 200 OK.
|Order PUSH||Customer PUSH|
|Contains an XML file with all the data of the order, the purchased products and information about the customer.||Contains an XML file with all the information about the customer.|
|Fires when a customer places an order in the shop and when an order is placed using the cash register. (POS)||Fires when a customer confirms his or her account.|
Apps live on their own server and thus have their own URL. They come in various types:
|ds||Delivery service: for implementing connections to transport services.|
This is how it works:
|invoice||Basically the same as psp, but focussed on payment on invoice. The customer details can be retrieved using this type.|
|productfeed||Retrieve product data, for example for use on comparison sites.|
|psp||Payment Service Provider: the easy way to connect a PSP to EasyWebshop.|
This is how it works:
The customer has placed an order in the shop, and is now on the page with the Pay now button. This button submits a HTML form.
How to write an app
- This is the main file where a visitor is redirected to.
- This is a script provided by us containing the code to connect to our API. Change your app key in this file.
- This XML file contains the name of your app, the URL to your server and 5 optional parameters. For example, the ID of the shop for connecting to the payment service provider.
- Only for PSPs: this script is called in the background by the payment service provider. It changes the status of the order to Payment received.
Creating an install button
<a href="https://www.easywebshop.com/software/apps/?install=http://www.webshopdata.com/app/easywebshop-psp">Install app</a>
Change the URL in the example to the URL of your app. Our backend automatically reads your settings.xml file and asks the user to enter the necessary data.