Show/hide List Operations Expand Operations

Authentication

/oauth/v2/token

GET|POST http://api.protectedshops.de/oauth/v2/token stable

Obtain access_token by using client credentials

Documentation
Sandbox

Documentation

Using this action, you can obtain an access token by providing your client credentials, which will let you call all other actions of the API.
The credentials needed to obtain an access token are provided by the ProtectedShops support team, please contact them if you have not recieved one yet. The credentials consist of client_id and client_secret.

Example request:

grant_type:    client_credentials
client_id:     7TaP8302n256i85W57d22L8z41M7TaP8302n256i85W57d22L8z41
client_secret: Zof4gsP17hdX46CKHsbGc4by64aQF89DWr4g1547wE1tv

Example Response

{
    "access_token": "ACCESS_TOKEN_STRING",
    "expires_in": 3600,
    "expires_at": "2014-06-29T14:23:01Z",
    "token_type": "bearer",
    "scope": null
}

Note the expires_in parameter in the response. This is the time-to-live of the token in seconds. After this period, the token will be invalidated and you should generate a new token.

Using the access token

As a request parameter:

?access_token=ACCESS_TOKEN_STRING

In request headers

Authorization: Bearer ACCESS_TOKEN_STRING

Parameters

Parameter	Type	Required?	Description
client_id	string	true	Your client id.
client_secret	string	true	Your client secret.
grant_type	string	true	The only supported type is 'client_credentials'

Status Codes

Status Code	Description
200	Returned when successful
401	Returned when the request is not authorized

Input

Parameters

= -

Method Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

Show/hide List Operations Expand Operations

Answers

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/format/{_format} stable

Returns all stored answers for a specific shop

Documentation
Sandbox

Documentation

Returns the list of stored answers of a specific shop.

Example response:

{
  "shopId": "4e334b17ea21688d3fddf982228108c9",
  "content": {
    "answers": [
      {
        "id": 2117798,
        "createdAt": "2014-10-22 12:59:12",
        "moduleVersion": 31,
        "answersVersion": 2,
        "isValid": true
      },
      {
        "id": 2135019,
        "createdAt": "2014-11-11 15:07:16",
        "moduleVersion": 31,
        "answersVersion": 1,
        "isValid": false
      }
    ]
  }
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the answers
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the shop is not found Returned when something else is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

POST http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/format/{_format} stable

Adds new version of the answers to a specific shop

Documentation
Sandbox

Documentation

Saves the provided answers for the questionary of the specified shop. This set of answers will be used to prefill the questionary in the next generation. If the answers satisfy all questions in the questionary, then, from this point on, this set of answers will also be used to generate the documents for this shop.

Note

The answers that you send to this endpoint are saved as a completely new set of answers. Any previously saved answers will not be used and are not merged with these answers. So, in other words, these values replace the existing answers. If you want to re-use the values you have already saved, Retrieve the latest answers via the latestAnswers endpoint, merge manually the values you need from the old answers with your new answers and send the merged state instead. Check the example below (Reusing existing answers) for more details.

Example answers array:

answers[conditions][c1001]: 1
answers[conditions][c1002]: 1
answers[conditions][c1003]: 0
answers[conditions][c1004]: 1

answers[variables][v1001]: "Var 1"
answers[variables][v1002]: "Var 2"
answers[variables][v1003]: "Var 3"
answers[variables][v1004]: "Var 4"

Example responses:

// Complete Answers
{
    "shopId":"6C8CF85DDDF79FE4493AB018AD375A7C",
    "content":true, // deprecated (replaced by "success")
    "success":true, // If answers were saved
    "answersStatus": {
        // If the saved answers are valid
        "valid": true,
        // Explanation of why the answers are marked invalid
        "errorMsg": "",
        // incomplete|incorrect - we can not generate documents from these answers
        // but they were saved to be finished later
        "errorType": ""
    }
}

// Incomplete Answers (some of the answers have not been provided)
// Answers are saved so the rest of the answers can be privided later
{
    "shopId":"6C8CF85DDDF79FE4493AB018AD375A7C",
    "content":true, // deprecated (replaced by "success")
    "success":true, // If answers were saved
    "answersStatus": {
        "valid": false,
        "errorMsg": "Variable 'v2345' is missing",
        "errorType": "incomplete"
    }
}

// Wrong Answers
// Some of the answers do not follow the questionary rules
// If you recieved response like this, the answers you supplied were not saved
// You need to fix the problem explained in 'errorMsg' and make the request again
{
    "shopId":"6C8CF85DDDF79FE4493AB018AD375A7C",
    "content":true, // deprecated (replaced by "success")
    "success":false, // If answers were saved
    "answersStatus": {
        "valid": true,
        "errorMsg": "'opt0' is not an allowed option for radio variable 'v2345' (Allowed: opt1,opt2,opt3)",
        "errorType": "incorrect"
    }
}

Answers for Radio and Checkbox questions

Conditions in Radio and Checkbox questions have the following rules:

Exactly one condition in a radio question has to be true.
One or more conditions in a checkbox question have to be true.

You are allowed to send just some of the values for onditions in these quesitons and the rest of the conditions in the question will be set to false. For example if a radio question consists of c1001, c1002, c1003 and c1004, and you send this set of answers:

answers[conditions][c1001]: 1

our system will handle it automatically and the following answers will be stored:

answers[conditions][c1001]: 1
answers[conditions][c1002]: 0
answers[conditions][c1003]: 0
answers[conditions][c1004]: 0

The same applies for checkbox questions.

Example: Reusing existing answers

First, we need to retrieve some exisiting answers from the system. You can you the answers list to select which answers set you want and then retrieve it by id. However, we recommend using the latestAnswers endpoint, which will pick the correct set of answers automatically. Lets say the endpoint returns the following previously saved answers:

{
  "conditions": {
    "c1101": "0",
    "c1102": "0"
  },
  "variables": {
    "v1001": "Company name"
  }
}

We want to save c2000 with value "1". If we just save its value, in the latest answers we would have only its value. So we merge c2000=1 with the array returned by the latestAnswers endpoint. After merging c2000 in the conditions part of the answers, we have:

{
  "conditions": {
    "c1101": "0",
    "c1102": "0",
    "c2000": "1"
  },
  "variables": {
    "v1001": "Company name"
  }
}

We save these answers instead of just {"conditions": {"c2000": "1"}, "variables": {}}. In this way we have preserved the previous state of the answers and have added our new values to them. Ofcource, sometimes you dont want to preserve all values. In this case just unset the unneeded values from the answers before sending them.

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the answers
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Parameters

Parameter	Type	Required?	Format	Description
answers	array	true		Array of conditions and variables.

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Parameters

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/{id}/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/{id}/format/{_format} stable

Get set of answers by id

Documentation
Sandbox

Documentation

Retrieves detailed information for a specified answers set (by set id).

Example response:

{
  "id": 123456789,
  "shopId": "4e334b17ea21688d3fddf982228108c9",
  "partnerId": "PARTNERID",
  "isValid": true,
  "createdAt": "2014-10-22T12:59:12+0200",
  "moduleVersion": 119,
  "answersVersion": 29,
  "isDraft": false,
  "answers": {
    "conditions": {
      "c1101": "0",
      "c1102": "0",
      // ...
    },
    "variables": {
      "v1001": "Company name",
      "v1002": "Company address",
      // ...
    }
  }
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the answers
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer
id		string	Identifier of the set of answers

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/latestAnswers/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/latestAnswers/format/{_format} stable

Get latest set of answers

Documentation
Sandbox

Documentation

Retrieves the answers that are used to pre-fill the questionary

The answers returned from this action represent the latest state of the questionary. They might be valid or invalid but contain the latest answers of the customer, including partially answered questionary.

These answers are suitable when one wants to edit, add or remove a condition or variable value manually. Get the answers, edit the arrays, and save them back in the save answers action (POST /{locale}/partners/{partnerId}/shops/{shopId}/answers/format/json)

Example response:

{
  "conditions": {
    "c1101": "0",
    "c1102": "0",
    // ...
  },
  "variables": {
    "v1001": "Company name",
    "v1002": "Company address",
    // ...
  }
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the answers
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

Show/hide List Operations Expand Operations

Documents

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/documents/format/{_format}

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

List of available documents for a specific shop

Documentation
Sandbox

Documentation

Returns the list of the available documents for a specific shop.

Example response

{
  "shopId": "7d91c382c0736cad11d28bb441273373",
  "content": {
    "module": "Online Shop",
    "documents": [
      {
        "id": 9704,
        "name": "Impressum",
        "type": "Impressum",
        "updated_at": "2014-11-11 15:08:48"
      },
      {
        "id": 9705,
        "name": "Allgemeine Geschäftsbedingungen",
        "type": "AGB",
        "updated_at": "2014-11-11 15:08:48"
      }
    ]
  }
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/documents/{type}/contentformat/{contentFormat}/format/{_format}

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

Returns the specified document

Documentation
Sandbox

Documentation

Returns content of the generated document. The document is generated using the latest valid answers to the questionary of the specified shopId. Document is identified by type, which can be retrieved from the document list action. The returned content is in utf8 encoding.

Supported content formats

text - text only version of the document, only text and new-line characters

html-lite - lightweight HTML, using only <u>, <b>, <i> and <br/> tags

html - complete HTML structure. Consists of html tags with assigned css classes and IDs so the end user can style it.

html-responsive - complete HTML structure, plus styles. Note that the content is split into css and html

pdf - base64 encoded pdf data (note the contentEncoding parameter in the example response)

docx - base64 encoded docx data (note the contentEncoding parameter in the example response)

Example response (contentFormat="pdf")

{
  "shopId": "7d91c382c0736cad11d28bb441273373",
  "content": "JVBERi0xLjMKMSAwIG9iago8....ZWYKMzU2MwolJUVPRgo=",
  "updatedAt": "2014-11-11 15:08:48",
  "contentEncoding": "base64", # none or base64
  "contentType": "application/pdf"
}

Example response (contentFormat="html-responsive")

{
  "shopId": "7d91c382c0736cad11d28bb441273373",
  "content": {
    "css": "...",
    "html": "..."
  },
  "updatedAt": "2014-11-11 15:08:48",
  "contentEncoding": "none",
  "contentType": "text/html"
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json
contentFormat	html\|html-snippet\|html-lite\|html-responsive\|pdf\|text\|docx\|sdox	string	Content format of the generated document
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer
type		string	Type of the document to generate (available types can be retrieved from the document list action)

Filters

Name

Information

pluginName

Datatype	string
Description	Optional add the name of the plugin download the document

pluginVersion

Datatype	string
Description	Optional add the version of the plugin downloading the document

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Filters

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

Show/hide List Operations Expand Operations

Modules

/v2.0/{locale}/partners/{partnerId}/modules/{moduleKey}/options/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/modules/{moduleKey}/options/format/{_format} stable

Module options

Documentation
Sandbox

Documentation

Returns the list of conditions and variables needed to generate documents for a given module. You can provide the values for these fields to the POST answers action in the API.

Overview

Conditions control if a certain sections of text appear in the documents of this module and variables are just strings which will appear in the text. For example if we have a condition some_payment_method_supported and if it is true, then the generated documents will contain sections related to SomePaymentProvider. On the other hand, if we have variable called shop_owner_email, the owner's email will be shown everywhere it is needed in the text.

Every condition and variable has a key. The key is used to send the value to the answers action. The rest of the properties are here to help you decide what the value should be. The texts in titles and descriptions are the same which we display in the end user questionary.

Example Response

{
    "module": "impressum",
    "options": {
        "questions": [
            {
                "type": "radio",
                "title": "Bitte wählen Sie hier die Rechtsform Ihrer Firma aus",
                "description": "Bitte geben Sie hier die Rechtsform Ihrer Firma an",
                "conditions": [
                    {
                        "key": "c3522",
                        "title": "BV - Besloten vennootschap met beperkte aansprakelijkheid"
                    },
                    {
                        "key": "c3523",
                        "title": "Eingetragener Verein (e.V.)"
                    }
                    // More options here
                ]
            },
            // More questions here
        ],
        "variables": [
            {
                "key": "v1019",
                "title": "Firmen oder Organisationsname:"
            },
            {
                "key": "v1028",
                "title": "Straße:"
            },
            // More variables here
        ]
    }
}

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 of them:

radio: The group of confitions 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 must have a value assigned in order to generate the documents. If you determine that some conditions is not TRUE, then send FALSE.

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
moduleKey		string	Identifier of the module

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

Show/hide List Operations Expand Operations

Partners

/v2.0/{locale}/partners/{partnerId}/settings/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/settings/format/{_format} stable

Get partner's settings

Documentation
Sandbox

Documentation

Get the partner's settings.

Example response

{
    "answers": {
        "conditions": {
            "c1001": 1,
            "c1002": 0,
        },
        "variables": {
            "v1001": "Some value",
            "v1002": "Some value",
        }
    }
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner

Parameters

Parameter	Type	Required?	Format	Description
settings	array	true		Array of conditions and variables

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the partnerId is not found Returned when something else is not found

Input

Requirements

= -

Parameters

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

PUT http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/settings/format/{_format} stable

Updates partner's settings

Documentation
Sandbox

Documentation

Updates partner's settings.

Settings are a single array resource e.g. every time you call this action with array of settings, all current settings are replaced with the new values. The array consists of key-value pairs. All settings are optional and have a special meaning in the DocumentServer.

Note: If the same entry exists for both partner and shop, the value in partner's settings has bigger priority
Note: You need to provide the whole array of settings every time.

Below you will find the list of the available settings for partners:

Answers

Answers are used during generation of documents and questionaries. Think of the answers in settings as answers to the questionary provided by you, instead of the customer. By setting this option, you pre-define values of the answers to the questionary for all of your customers. The end-user will not see the questions related to these answers at all in his questionary and therefore will not be able to alter these values. Presence of a certain value, e.g. settings[answers][conditions][c1001] = 1, means it overrides the specified value from the customer's answers. You are not required to define values for all conditions and variables, the values are searched in partner settings, shop settings and answers, if it is not found anywhere it is treated as undefined and the customer will be asked in the questionary to answer it.
Note: Use store answers action to store answers which vary per customer.

Format - Answers are stored in the settings as single array with sub-arrays of conditions and variables.
Example request (http parameters)

settings[answers][conditions][c1001] = 1
settings[answers][conditions][c1002] = 0
settings[answers][variables][v1001] = "Some Value"
settings[answers][variables][v1002] = "Some Value"

Example response

{
    "answers": {
        "conditions": {
            "c1001": 1,
            "c1002": 0,
        },
        "variables": {
            "v1001": "Some value",
            "v1002": "Some value",
        }
    }
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner

Parameters

Parameter	Type	Required?	Format	Description
settings	array	true		Array of settings

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the partnerId is not found Returned when something else is not found

Input

Requirements

= -

Parameters

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

Show/hide List Operations Expand Operations

Questionary

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/questionary/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/questionary/format/{_format} stable

questionary of a specific shop

Documentation
Sandbox

Documentation

Returns the questionary structure of a specific shop. Questions are structured by documents and their sections.

The questions vary depending on the latest stored answers. Only the questions needed to generate the documents will be shown.

Note

In most cases you will not use this action. We provide a frontend integration package which can be used to show the questionary to the end user. For more information on using the integration package in your website, check out the tutorial and our questionary integration guide

Example Response

{
  "shopId": "4e334b17ea21688d3fddf982228108c9",
  "content": {
    "documents": [
      {
        "id": "d1012",
        "title": "Impressum",
        "sections": [
          {
            "id": "s1535",
            "title": "E-Mail",
            "questions": [
              {
                "id": "q36",
                "title": "Verkaufen Sie Batterien oder Produkte, welche Batterien enthalten?",
                "type": "yesno",
                "description": "Bitte geben Sie an, ob Sie entweder Produkte verkaufen, welche Batterien enthalten, oder Batterien selbst.",
                "options": [
                  {
                    "key": "c3127",
                    "title": "",
                    "value": "0"
                  }
                ]
              }
            ],
            "variables": [
              {
                "id": "v1987",
                "title": "Shop-E-Mail-Adresse",
                "description": "Bitte geben Sie hier die E-Mail-Adresse an, unter welcher Ihr Shop erreichbar sein soll.",
                "type": "singleline",
                "options": [],
                "value": "nothelferonline@web.de"
              }
            ]
          }
        ]
      }
    ]
  }
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

Show/hide List Operations Expand Operations

Shop credentials

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/credentials/format/{_format}

DELETE http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/credentials/format/{_format} stable

Deletes a shop api client

Documentation
Sandbox

Documentation

Deletes a shop api client.

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Status Codes

Status Code	Description
204	Returned when successful
400	Returned when client shop cannot be deleted
403	Returned when the request is not authorized
404	Returned when shop api client is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/credentials/format/{_format} stable

Returns shop api client detailed info

Documentation
Sandbox

Documentation

Returns shop api client detailed info.

Example response:

{
        "clientId": "1_2i6bvb14k5eswg08gskw4owoo4ok488k88okokso8ck8o48s4k",
        "secret": "2hjf7m3iz6yo04ow8w4so0gsg00gg0sgk48kcog80gck4gsosw",
        "createdAt": "2015-05-26T07:47:52+0000",
        "updatedAt": "2015-05-26T07:47:52+0000"
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when no active shop is found for shopId Returned when shop api client is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

POST http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/credentials/format/{_format} stable

Creates api client from existing shop

Documentation
Sandbox

Documentation

Creates api client from existing shop.

#### Example response:
{
        "clientId": "1_2i6bvb14k5eswg08gskw4owoo4ok488k88okokso8ck8o48s4k",
        "secret": "2hjf7m3iz6yo04ow8w4so0gsg00gg0sgk48kcog80gck4gsosw",
        "createdAt": "2015-05-26T07:47:52+0000",
        "updatedAt": "2015-05-26T07:47:52+0000"
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the answers
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Status Codes

Status Code	Description
201	Returned when successful
400	Returned when shop is already a client Returned when client shop cannot be created
403	Returned when the request is not authorized
404	Returned when active shop found for shopId is not foundis not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

Show/hide List Operations Expand Operations

Shops

/v2.0/{locale}/partners/{partnerId}/shops/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/format/{_format} stable

List of shops of a partner

Documentation
Sandbox

Documentation

Returns the list of registered shops of a partner. The list is limited to 500 results.

Example Response

[
  {
    "shopId": "4B0250793549726D5C1EA3906726EBFE",
    "expireDate": "2014-04-27 00:00:00",
    "bundleId": 801,
    "answersValid": 1,
    "partnerId": "partner1",
    "module": "ec_it_DE_impressum",
    "hasDraftAnswers": 0,
    "templateId": 4
  },
  {
    "shopId": "F57A2F557B098C43F11AB969EFE1504B",
    "expireDate": "2014-03-29 00:00:00",
    "bundleId": 800,
    "answersValid": 0,
    "partnerId": "partner1",
    "module": "ec_it_DE_impressum",
    "hasDraftAnswers": 0,
    "templateId": 6
  }
]

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner

Filters

Name

Information

bundleId

Datatype	integer
Description	Filter by bundleId property

answersValid

Datatype	bool
Format	1\|0
Description	This filter is DEPRECATED

shopIds

Datatype	array
Description	Returns information for certain set of shopIds of the partner or bundle

includeDocumentInfo

Datatype	array
Description	Adds information about the available documents

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Filters

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

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

Creates a shop

Documentation
Sandbox

Documentation

Creates a shop

Example request (http form)

shop[module] = "impressum"
shop[title] = "Shop Title"
shop[url] = "http://www.theshop.com/"
shop[bundleId] = "23424"
shop[username] = "JohnDoe
shop[firstName] = "John"
shop[lastName] = "Doe"
shop[salutation] = "Herr"
shop[email] = "ps@de.de"
shop[partnerId] = "protectedshops
shop[description] = "Some test shop"
shop[templateId] = "22"

Example response

{
    module = "impressum"
    title = "Shop Title"
    url = "http://www.theshop.com/"
    bundleId = "23424"
    username = "JohnDoe
    firstName = "John"
    lastName = "Doe"
    salutation = "Herr"
    email = "ps@de.de"
    partnerId = "protectedshops
    description = "Some test shop"
    templateId = "22"
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner

Parameters

Parameter	Type	Required?	Format	Description
shop[module]	string	true	alphanumeric	Module for the shopId
shop[title]	string	false	alphanumeric	Customer's shop title
shop[url]	string	false	url	Customer's shop url
shop[expireDate]	datetime	false	alphanumeric	Is used to limit access or quit the contract to a specific datetime
shop[bundleId]	integer	false	numeric	Unique order/contract ID. Will be generated automatically if not specified.
shop[username]	string	false	alphanumeric	Username
shop[firstName]	string	false	alphanumeric	First Name of the user for notification email.
shop[lastName]	string	false	alphanumeric	Last Name of the user for notification email.
shop[salutation]	string	false	alphanumeric	Salutation of the user for notification email.
shop[email]	string	false	alphanumeric	Email of the user for notification email. If not provided notification will be sent to partners contact email
shop[partnerId]	string	true	alphanumeric	Partner id of the creating partner, given by protectedshops
shop[description]	string	false	alphanumeric	Email of the user
shop[templateId]	integer	false	numeric	Id of PS template used to create shop with predefined answers

Status Codes

Status Code	Description
201	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Parameters

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/format/{_format}

DELETE http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/format/{_format} stable

Deletes a shop

Documentation
Sandbox

Documentation

Deletes a shop

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Status Codes

Status Code	Description
204	Returned when successful
403	Returned when the request is not authorized
404	Returned when the shop is not found Returned when something else is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/format/{_format} stable

Returns a shop

Documentation
Sandbox

Documentation

Returns detailed information for a specified shop

Example response

{
    "partnerId": "protectedshops"
    "shopId": "DAE8E2C2FAA3A9EA9886793B61281965",
    "bundleId": 1055,
    "answersValid": 1,
    "title": "The Shop",
    "url": "http://someshop.com/",
    "description": "",
    "module": "ec_it_DE_impressum",
    "hasDraftAnswers": 0,
    "templateId": 5
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

PUT http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/format/{_format} stable

Updates a shop

Documentation
Sandbox

Documentation

Updates a shop.

Example request (http form)

shop[title] = "Shop Title"
shop[url] = "http://www.theshop.com/"

Example response

{
    "partnerId": "protectedshops"
    "shopId": "DAE8E2C2FAA3A9EA9886793B61281965",
    "answersValid": 0,
    "title": "The Shop",
    "url": "http://someshop.com/",
    "expireDate": "2016-01-19 14:47:20"
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Parameters

Parameter	Type	Required?	Format	Description
shop[title]	string	false	alphanumeric	Customer's shop title
shop[url]	string	false	url	Customer's shop url
shop[expireDate]	datetime	false	alphanumeric	Is used to limit access or quit the contract to a specific datetime
shop[bundleId]	integer	false	numeric	Unique order/contract ID. Will be generated automatically if not specified.
shop[username]	string	false	alphanumeric	Username
shop[firstName]	string	false	alphanumeric	First Name of the user for notification email.
shop[lastName]	string	false	alphanumeric	Last Name of the user for notification email.
shop[salutation]	string	false	alphanumeric	Salutation of the user for notification email.
shop[email]	string	false	alphanumeric	Email of the user for notification email. If not provided notification will be sent to partners contact email
shop[description]	string	false	alphanumeric	Email of the user

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the answer is not found Returned when something else is not found

Input

Requirements

= -

Parameters

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/settings/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/settings/format/{_format} stable

Get shop's settigns

Documentation
Sandbox

Documentation

Get the shop's settings.

Example response

{
    "answers": {
        "conditions": {
            "c1001": 1,
            "c1002": 0,
        },
        "variables": {
            "v1001": "Some value",
            "v1002": "Some value",
        }
    }
}

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Parameters

Parameter	Type	Required?	Format	Description
settings	array	true		Array of settings

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the shopId is not found Returned when something else is not found

Input

Requirements

= -

Parameters

= -

Headers

= -

Content

= Replaces header if set

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

PUT http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/settings/format/{_format} stable

Updates shop's settings

Documentation
Sandbox

Documentation

Updates shop's settings.

Settings are a single array resource e.g. every time you call this action with array of settings, all current settings are replaced with the new values. The array consists of key-value pairs. All settings are optional and have a special meaning in the DocumentServer.

Note: If the same entry exists for both partner and shop, the value in partner's settings has bigger priority
Note: You need to provide the whole array of settings every time.

Below you will find the list of the available settings for shops:

Answers

Answers are used during generation of documents and questionaries. By setting this option, 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. Presence of a certain value, e.g. settings[answers][conditions][c1001] = 1, means it overrides the specified value from the customer's answers. You are not required to define values for all conditions and variables, the values are searched in partner settings, shop settings and answers, if it is not found anywhere it is treated as undefined and the customer will be asked in the questionary to answer it.
Note: Use store answers action to store answers which vary per customer.

Format - Answers are stored in the settings as single array with sub-arrays of conditions and variables.
Example request (http parameters)

settings[answers][conditions][c1001] = 1
settings[answers][conditions][c1002] = 0
settings[answers][variables][v1001] = "Some Value"
settings[answers][variables][v1002] = "Some Value"

Example response

{
    "answers": {
        "conditions": {
            "c1001": 1,
            "c1002": 0,
        },
        "variables": {
            "v1001": "Some value",
            "v1002": "Some value",
        }
    }
}

See also documentation for partner's settings

Requirements

Name	Requirement	Type	Description
_format	xml\|json	string	Format of the response
locale	de	string	Language locale of the documents
partnerId		string	Identifier of the partner
shopId		string	Identifier of the customer

Parameters

Parameter	Type	Required?	Format	Description
settings	array	true		Array of settings

Status Codes

Status Code	Description
200	Returned when successful
403	Returned when the request is not authorized
404	Returned when the shopId is not found Returned when something else is not found

Input

Requirements

= -

Parameters

= -

Headers

= -

Content

= Replaces header if set

Protected Shops Document Server API

Authentication

/oauth/v2/token

GET|POST http://api.protectedshops.de/oauth/v2/token stable

Documentation

Example request:

Example Response

Using the access token

Parameters

Status Codes

Parameters

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

Answers

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/format/{_format} stable

Documentation

Example response:

Requirements

Status Codes

Requirements

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

POST http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/format/{_format} stable

Documentation

Note

Example answers array:

Example responses:

Answers for Radio and Checkbox questions

Example: Reusing existing answers

Requirements

Parameters

Status Codes

Requirements

Parameters

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/{id}/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/{id}/format/{_format} stable

Documentation

Example response:

Requirements

Status Codes

Requirements

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/latestAnswers/format/{_format}

GET http://api.protectedshops.de/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/latestAnswers/format/{_format} stable

Documentation

Example response:

Requirements

Status Codes

Requirements

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

Documents

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/documents/format/{_format}

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

Documentation

Example response

Requirements

Status Codes

Requirements

Request URL

Response Headers [Expand] [Profiler]

Response Body [Raw]

/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/documents/{type}/contentformat/{contentFormat}/format/{_format}

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

Documentation

Supported content formats

Example response (contentFormat="pdf")

Example response (contentFormat="html-responsive")

Requirements

Filters

Status Codes