Protectedshops API Overview

Api Overview

This tutorial will introduce you to our Restful API and integration package. It consists of several endpoints for managing questionaries, answers and documents of your customers. Here is how a general urls looks like:

POST 'https://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/format/{_format}'

The POST stands for the method of the request. Curly braces(eg. {locale}) mark parameters. You will need to provide locale and partnerId in all endpoints. In the production version of the API you have to use your real partner id, provided by ProtectedShops. The _format parameter is used to specify the desired response format. Supported formats are json and xml.

Here is a short summary of how we get from registering a new customer to delivering his documents.

Register a new customer (called shop in our system)
Deliver questionary to the customer
User answers all questions in the questionary
Deliver documents to the customer

Managing Customers

The first endpoint we check is the shop endpoint. It has several actions for managing customers(shopId's) stored in our system

POST 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/format/json'              // create shop, returns shopId
GET 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/{shopId}/format/json'      // get info for the shop
PUT 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/{shopId}/format/json'      // update shop data
DELETE 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/{shopId}/format/json'   // remove shop from our system

So, let's create our first shopId in the system. We will use the first call in the above list. Let's say you partner id is "demo". We also need to post some additional data in order to create the customer. Here is example code:

var data = {
    shop: {
	// Title of the customer's shop
	title: "Some shop name",
	module: "impressum",
	partnerId: "demo",
    }
};

$.post("https://api.protectedshops.de/v2.0/de/partners/demo/shops/format/json", data, function(res) {
    console.log(res);
});

Here is the full result:

What is important for us now is shopId="". We can use it now to build the questionary

Answers

The Module

The shopId is linked to one module. The module represents a set of legal documents serving a specific use case. You specify the module with the parameter moduleKey in the previous query.

The module is versioned internally but we have hidden most of the versioning complexity so the API is easier to use. There is one specific case in which you need to care about the versions and it is explained in the section "Saving answers".

The Answers

The documents in the module contain texts which depend on conditions and variables.

Conditions can be true or false and control if a certain section will be included in the generated documents. For example SomePaymentMethod = false means that sections in the documents regarding this payment method will not be shown

Variables have string values and are used in the documents for certain properties. For example contact_email = "john.doe@johnshop.de" means that "john.doe@johnshop.de" will be used everywhere in the document where the contact email needs to be printed

The group of conditions and variables is called answers. We need their values to generate the documents.

The answers can be saved in several endpoints (explained in the next section) but always have the following structure:

{
    "answers": {
        "conditions": {
            "c1000": 1,
            "c1001": 0
        },
        "variables": {
            "v1000": "Value 1",
            "v1001": "Value 2"
        }
    }
}

Available options

This section explains how you find out what answers you need to provide, or in other words how you know the meaning of a condition or variable key.

Before you can save the answers, you need to know the available options you can choose from. There are 2 actions for this purpose:

Get questionary:

GET 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/{shopId}/questionary/format/json'      // Get Questionary

This action is used by the questionary package. It is designed for an interactive process in which the customer answers the questions one by one and answers are sent on every interaction. It has more complex output but also it does not show all available options. Only what is needed will be shown (based on the currently saved answers and the internal dependencies between the conditions and variables). The reason for this is that the questionary will not ask the customer to fill unnecessary information. For example if the customer answered in a previous question that his website does not support online payments, the questionary will not ask him to choose from a list of online payment providers.

Get module options:

GET 'https://api.protectedshops.de/v2.0/de/partners/partnerId/modules/{moduleId}/options/format/json'      // Get list of answers

This action returns a list of all available options in a simpler structure.

In the response, the conditions are grouped in questions. The question is a logical group of conditions which tells you how to treat the group. Every question has property type and there are three possible types:

radio: The group of conditions can have only one condition set to TRUE

checkbox: The group can have any number of conditions set to TRUE

yesno: The group has exactly one condition, the condition has empty title as it is the same as the question's, read the question title and description only

Note: Every condition in a question must have a value assigned in order to generate the documents.
If you determine that some condition in a radio question is TRUE, then send FALSE for the rest.
If you determine that some conditions in a checkbox question are TRUE, then send FALSE for the rest.

Saving answers

By using the following actions, you can save a new answers set:

GET 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/{shopId}/answers/format/json'                  // Get list of answers
POST 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/{shopId}/answers/format/json'                 // Add new answers
GET 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/{shopId}/answers/{answersId}/format/json'      // Get specific answers

This is the endpoint which the questionary uses to store answers provided by the customer while he is filling it. Of cource, you can manually send answers to this endpoint to prefill the questionary for the customer.

Note: In order to generate the documents you need to have answers stored via this endpoint. The reason for this is the module versioning. At the moment you store answers, the module has specific version. The version is assigned to the answers and this version will be used during the document generation. This protects the documents of your customers from braking when we publish new versions. If the answers are compatible with the new version we will automatically increment it and your customers will start receiving the new version. But if we require more conditions and variables in the new version then the customers will continue to receive the old version of the documents until you (or the customer by filling the questionary) store new valid answers in this endpoint.

You can try the storing of answers here:

Answers in shop settings

Every shop has a list of settings assigned to it. By default they are empty. You can manage the settings using the shop settings actions:

GET 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/{shopId}/settings/format/json'      // Get the settings
PUT 'https://api.protectedshops.de/v2.0/de/partners/partnerId/shops/{shopId}/settings/format/json'      // Update the settings

One of the possible values in shop settings is answers. By setting it, you pre-define values of the answers to the questionary of this customer. The end-user will not see the questions related to these answers at all in his questionary and thus will not be able to alter these values. Once you set it, it immediately overrides all the answers for this shopId, no matter which version of the module the answers are for. In short, shop settings have higher priority than answers, completely ignore module versions and their main use is to hide questions from the customer.

You can try the updating of shop settings here:

Answers in partner settings

Your partnerId has settings assigned too. They act exactly the same as shop settings, except that they immediately affect all shops you ever created

Questionary

In order to built the questionary into your page, we provide a package of javascript and css files. Press the link below to see a complete example code using this package to deliver the questionary to the user.

<!DOCTYPE html>
<html>
    <head>
        <meta charset="UTF-8" />
        <title>Questionary</title>
		<link rel="icon" type="image/x-icon" href="/favicon.ico" />
		<link rel="stylesheet" type="text/css" href="/questionary/styles/default.css" />
		<script type="text/javascript" src="/bundles/modules/js/jquery-1.10.2.js"></script>
		<script type="text/javascript" src="/dustjs/dust-full.js"></script>
		<script type="text/javascript" src="/dustjs/dust-helpers.js"></script>
		<script type="text/javascript" src="/questionary/questionary.js"></script>
	</head>
        <body>
		<div id="main-content">
			<div id="main-questionary"></div>
			<div id="loadingIndicator">Loading...</div>

			<script type="text/javascript" >
				$(document).ready(function() {
					ps.questionary({
						container: "#main-questionary",
						buildUrl: "https://api.protectedshops.de/v2.0/de/partners/demo/shops//questionary/format/json",
						saveUrl: "https://api.protectedshops.de/v2.0/de/partners/demo/shops//answers/format/json",
						beforeReload: function() {
							$('#loadingIndicator').show()
						},
						afterReload: function() {
							$('#loadingIndicator').hide()
						},
						onFinish: function() {
							window.location = "/questionary/document-list.html";
						}
					});
				});
			</script>
		</div>
	</body>
</html>

Now, using the shopId we got above, we can generate the questionary.

Retrieving Documents

You can get list of documents for a shopId with the following API call:

GET 'https://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/documents/format/{_format}'

Then you can use the result to build download URLs like:

GET 'https://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/documents/{type}/contentformat/{contentFormat}/format/{_format}'

Where contentFormat is one of: pdf, html, html-snippet, text

Alternatively, you can build small snippet which end users can paste in their page(pdf format is not supported in snippets)

<div id="document-{type}"></div>
<script src="https://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/documents/{type}/contentformat/{contentFormat}/snippet.js"></script>

Paste the html snippet here and it will be appended to the page

Protectedshops API Tutorial

Api Overview

Managing Customers

Answers

Questionary

Retrieving Documents