Getting Started

Content

Introduction
Authentication
Making a request
XML, JSON
Handling errors
Check the request and responses
Result limiting
Rate limiting

Getting started with the API documentation and wrappers for VersaCommerce.

Introduction

The VersaCommerce API follows the principals of a restful Webservice. It´s implemented as XML OR JSON over HTTP using all four verbs (GET/POST/PUT/DELETE). Every resource, like product, collection, page or order, has its own URL.

Authentication

To use the VersaCommerce API you will need an application registration for your store.

SignUp as an developer: https://app.versacommerce.de/developer/signup
Login to your developer account: https://app.versacommerce.de/developer
Register your app:

Your applications name
A short description
A redirect url, where your shop should send the token parameter to.
An optional URL where your customers can configure their settings
Several optional URL´s of actions in your App, the title of the link poiting to each action and the location of the link in the VersaCommerce Backend
If you need only read or also write access
Authentication is managed via HTTP Basic authentication. Every request must include the Authorization HTTP Header.

Every VersaCommerce API-Call will look like this:

https://api_key:password@your-store.versacommerce.d/...

Making a request

All URLs start with https://shopdomain.versacommerce.de/api/. If we change the API in backward-incompatible ways, we’ll add a version marker and maintain stable support for the old URLs.

In curl, that looks like:

$ curl -u user:pass -H 'User-Agent: MyApp (yourname@example.com)' <a href="https://APPLICATION_KEY:PASSWORD@shopdomain.versacommerce.de/api/any-resource.xml">https://APPLICATION_KEY:PASSWORD@shopdomain.versaco/...</a>

XML, JSON

To create something, it’s the same deal except you also have to include the Content-Type header and the JSON/XML data:

We support XML and JSON for serialization of data. Our format is to have no root element and we use snake_case to describe attribute keys (JSON). This means that you have to send Content-Type: application/json; charset=utf-8 when you’re POSTing or PUTing data into VersaCommerce. All API URLs end in .json to indicate that they accept and return JSON. All API URLs end in .xml to indicate that they accept and return XML.

Handling errors

If VersaCommerce is having trouble, you might see a 5xx error. 500 means that the app is entirely down, but you might also see 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout. It’s your responsibility in all of these cases to retry your request later.

Check the request and responses

Use Fiddler for Windows, or Charles for OS X to debug your HTTP requests and responses.

Result limiting

You can receive max 250 records per request. The default limit is 150. If you need to handle more records, you should request them in batches. Use the query params “limit” and “offset” to batch through your results.

https://api_key:password@your-store.versacommerce.de/api/any-resource.xml?limit=200&offset=600

Rate limiting

You can perform up to 360 requests within 2 minutes period from the same IP address for the same account.