EasyWebshop API documentation

The new API will be implemented during the weekend of May 24th. Consider this documentation as outdated.

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.

Feature overview

• 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
• Creating apps that install HTML/Javascript widgets with the click of a button

Technology overview

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

Useful links:

• W3Schools XML Tutorial
• HTTP Status Codes (Wikipedia)

API vs API PUSH vs Apps

API	API PUSH	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?

1. Use an existing shop or create a new shop
2. Adjust the user level to Expert, at Settings > User experience level
3. Relax! It's easier than it looks

API

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.

Section	categorylist category productlist product orderlist order customerlist customer
Request method	GET POST PUT DELETE
Segment
XML file

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.

API PUSH

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

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

API

Retrieving data

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

https://easywebshop.com/api/categorylist

Retrieve all categories in human readable JSON format

https://easywebshop.com/api/categorylist?format=json&pretty=1

Retrieve a specific category

https://easywebshop.com/api/category/Cocktails

Retrieve the last 1000 products

https://easywebshop.com/api/productlist

Retrieve the last 1000 products, but skip the first 1000 products

https://easywebshop.com/api/productlist?offset=1000

Retrieve products of the last 24h

https://easywebshop.com/api/productlist/86400

Retrieve products within a category

https://easywebshop.com/api/productlist/Cocktails

Retrieve product using the product code

https://easywebshop.com/api/product/C001

Retrieve the last 100 orders

https://easywebshop.com/api/orderlist

Retrieve orders from the last 24h

https://easywebshop.com/api/orderlist/86400

Retrieve the last 100 orders, but skip the first 100 orders

https://easywebshop.com/api/orderlist?offset=100

Retrieve the last 100 customers

https://easywebshop.com/api/customerlist

Retrieve the last 10 customers

https://easywebshop.com/api/customerlist/10

Retrieve a specific customer

https://easywebshop.com/api/customer/email@address.com

Sending data

Importing products with cURL:
curl -X POST -u linktest@mailinator.com:linktest -d @products.xml https://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:

<?xml version="1.0" encoding="UTF-8" ?> <productlist> <product> <code>LA-B03</code> <category lang="en">Ambiance</category> <category lang="nl">Ambiance</category> <name lang="nl">Levis Ambiance C03</name> <description lang="nl">Plaats hier de beschrijving van het product</description> <price>49.99</price> <old_price>75</old_price> <stock>0</stock> <weight>5</weight> <status>Available</status> <last_update>2011-03-31 14:49:40</last_update> <vat_code>0</vat_code> <colors>Blue,Red,Violet</colors> <promotion>1</promotion> </product> <product> <code>LA-C05</code> <category lang="en">Ambiance</category> <category lang="nl">Ambiance</category> <name lang="nl">Levis Ambiance C05</name> <description lang="nl">Beschrijving van het tweede product</description> <price>79</price> <stock>0</stock> <weight>0</weight> <status>Available</status> <last_update>2011-03-31 14:57:40</last_update> <vat_code>0</vat_code> <property> <code>LA-C05A</code> <name lang="nl">Product eigenschap, variatie of dimensie</name> <description>Beschrijving van de eerste eigenschap van het tweede product. Wanneer niet ingevuld zal de beschrijving van het originele product overgenomen worden</description> <status>Available</status> <colors>LightCoral</colors> </property> <property> <code>LA-C05B</code> <name lang="nl">Eigenschap 2</name> <name lang="en">Second property</name> <price>89</price> <status>Sold Out</status> <params>T,en,Example parameter,,,</params> <brand>Apple</brand> <mpn>Iphone</mpn> </property> </product> </productlist>

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 linktest@mailinator.com:linktest -d @update.xml https://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:

<?xml version="1.0" encoding="UTF-8" ?> <productlist> <product> <code>LA-C05</code> <price>15</price> <status>Available</status> <stock>5</stock> <promotion>1</promotion> <name lang="en">Test name</name> <description lang="en">Test description</description> <name lang="nl">Test naam</name> <description lang="nl">Test beschrijving</description> </product> <product> <code>SI-V55</code> <price>28</price> <status>Sold Out</status> <stock>0</stock> <weight>2</weight> <old_price>43</old_price> </product> </productlist>

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 linktest@mailinator.com:linktest -d @updatestock.xml https://easywebshop.com/api/product

<?xml version="1.0" encoding="UTF-8" ?> <productlist> <product> <code>LAA-X33</code> <stock>2</stock> </product> <product> <code>SI-V55</code> <status>Sold Out</status> <stock>0</stock> </product> </productlist>

If the product is sold out, change the product status to Sold Out.

Possible product statuses:

• Available
• Available but not online
• Pre-order
• Sold Out
• Invisible
• Customers only
• Price visible for customers
• Choose property
• Hide status
• custom0, custom1, ..., custom9

Adding or updating product photos with cURL:
curl -X PUT -u linktest@mailinator.com:linktest -d @uploadimage.xml https://easywebshop.com/api/productimage

The XML file uploadimage.xml must have the following layout:

<?xml version="1.0" encoding="UTF-8" ?> <product> <code>LA-C05</code> <image>https://www.ewimg.com/img/logos/easywebshop-200-whitebg.png</image> <image>https://www.ewimg.com/img/logos/easywebshop-300-whitebg.png</image> </product>

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 linktest@mailinator.com:linktest https://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 linktest@mailinator.com:linktest -d @updateorder.xml https://easywebshop.com/api/order

<?xml version="1.0" encoding="UTF-8" ?> <orderlist> <order> <code>20140-00544-27497-22264</code> <status>Complete</status> </order> <order> <code>20140-00544-62141-77454</code> <status>Cancelled</status> <reference>Test reference 12345</reference> </order> </orderlist>

Possible order statuses:

• Order received
• Waiting for payment
• Payment received
• Processing
• Products sent
• Complete
• Cancelled
• custom0, custom1, ..., custom9

Accepting or denying customers with cURL:
curl -X PUT -u linktest@mailinator.com:linktest -d @updatecustomer.xml https://easywebshop.com/api/customer

<?xml version="1.0" encoding="UTF-8" ?> <customerlist> <customer> <email>buddy@mailinator.com</email> <denied>1</denied> </customer> </customerlist>

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 linktest@mailinator.com:linktest https://easywebshop.com/api/customer/buddy@mailinator.com

If the command succeeded you will see 200 OK.

API limits

To prevend excessive querying, the API will automatically respond slower when many queries are sent. There is a limit of 48 requests per 24 hours in order to prevent continues polling.

API PUSH

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

Apps live on their own server and thus have their own URL. They come in various types:

Type	Description
ds	Delivery service: for implementing connections to transport services. This is how it works: The customer is on the checkout page and selects a shipping method. Because your app is connected to a shipping method, this triggers a popup with iframe within. The customers address data is sent to the page in the iframe. (Your app URL) In your app, the customer can choose a shipping method or select a pick-up point from a map. Your app sends the shipping method name, price, description and a logo to our confirmation URL. The data is added to the order and the customer gets a confirmation.
html	Provide the HTML/Javascript code. The merchant can choose on which pages of the shop he or she wants to install this code. Basically the same as copy and paste, but more user friendly.
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. You receive the POST data from the previous page on your server. Using the order code (POST data) and your personal app key you can safely retrieve all the data of the order. You send the order data to the payment service provider. If the payment is executed successfully, the payment service provider requests the report url. The status of the order gets changed to Payment received. The customer is redirected to the payment ok or to the payment failed URL, depending on the success or failure of the payment. If multiple payment methods are set, the customer can choose another payment after a failed payment.

How to write an app

index.php

This is the main file where a visitor is redirected to.

easywebshop.php

This is a script provided by us containing the code to connect to our API. Change your app key in this file.

settings.xml

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.

report.php

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://easywebshop.com/software/apps/?install=https://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.

Examples

Coding examples can explain our API better than words. Feel free to use them in your own project.

Function	Download	Size
API	easywebshop-api.zip	168KB
API PUSH	easywebshop-push.zip	1.6KB
Apps	easywebshop-app.zip	175KB
Delivery service	easywebshop-deliveryservice.zip	26.1KB
HTML5 Widget	easywebshop-html.zip	167KB