Protectedshops API Overview

Prerequisites

Understanding of how to use our API (docs)
Valid credentials to obtain an access token
Our questionary integration package (download)

Overview

Questionary

In order to generate the documents for your customer, we need answers to a number of questions. We call the visual representation of the questions questionary. This package lets you embed the questionary in your website and show it to the customer.

Workflow

First, you initialize the questionary on your page. The questionary is rendered to the user. When the customer answers a question, the current answers are stored and the questionary is re-rendered. When the whole questionary is fulfilled, the customer can click the Finish("Beenden") button.

API Credentials

Storing answers and getting the questionary from our API requires your credentials. Of course, you can not expose this information in the customer's web browser. You will need to call these endpoints in your server-side code and pass the result to the client-side. (more)

Using the questionary integration package

Make sure you have DustJS and jQuery included on the page. These are the versions we recommend:

<!-- jQuery -->
<script type="text/javascript" src="//code.jquery.com/jquery-1.11.2.min.js"></script>
<!-- DustJS -->
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/dustjs-linkedin/2.6.1/dust-full.min.js"></script>
<script type="text/javascript" src="//cdnjs.cloudflare.com/ajax/libs/dustjs-helpers/1.6.1/dust-helpers.min.js"></script>

Extract the contents of the folder called "public" somewhere in your web root, so it can be accessed using a browser. Add the following to the head section of the page where you want to include the questionary ("/protectedshops/" is the folder where you extracted the questionary integration package).

<!-- Default Questionary Style -->
<link rel="stylesheet" type="text/css" href="/protectedshops/css/default.css" />
<!-- Default Questionary Style -->
<script type="text/javascript" src="/protectedshops/js/questionary.js"></script>

Place the following snippet where you want the questionary to appear on your page.

<div id="main-questionary"></div>

<script type="text/javascript" >
    $(document).ready(function() {
        var options = {
            container: "#main-questionary",
            buildUrl: "/build-questionary", // Explained in the next section
            saveUrl: "/save-answers" // Explained in the next section
        };
        ps.questionary(options);
    });
</script>

You are free to alter the files in the package to match your design. It is not recommended however to alter /js/questionary.js. If you want different functionality, please email your suggestions or bug reports to eng@protectedshops.de

Building the questionary

In the example, we provided options.buildUrl = "/build-questionary"

The questionary will call this url every time it needs to (re-)render the questionary.

This action is mapping to our get questionary endpoint:

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

You have to make an authenticad call to it and return the response to the questionary. You also have to specify for which customer you need the questionary, e.g. the customer's ShopId. In the server-side you can identify the customer and the shopId from the session or by adding some variables to the url For example:

options.buildUrl = "/build-questionary?shopId=SHOPID&customerId=100000"

Example:

<?php
namespace Your\Bundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class QuestionaryController extends Controller
{
	public function buildAction(Request $request)
	{
                // Gather request paramters
		$shopId = $request->get('shopId');
                $accessToken = $this->get("protectedshops")->getAccessToken();

		// Open connection
		$ch = curl_init();

                // Set URL
		curl_setopt($ch, CURLOPT_URL, "https://api.protectedshops.de/v2.0/de/partner/MYPARTNERID/shop/{$shopId}/questionary/format/json");

                // Set Access Token
		curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
		curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

                // Get Response
		$response = curl_exec($ch);

		//close connection
		curl_close($ch);

                // Return the reponse as is
		return new Response($remoteResponse, 200, array('Content-Type' => 'application/json'));
	}
}

Saving the answers

In the example above, we provided options.saveUrl = "/save-answers"

The questionary will call this url every time it needs to save the answers. You can implement this similar to buildUrl

This action is mapping to our store answers endpoint:

POST '/v2.0/{locale}/partners/{partnerId}/shops/{shopId}/answers/format/json'

Example

<?php
namespace Your\Bundle\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\Controller;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;

class QuestionaryController extends Controller
{
	public function storeAnswersAction(Request $request)
	{
                // Gather request paramters
		$shopId = $request->get('shopId');
                $answers = $request->get('answers');
                $accessToken = $this->get("protectedshops")->getAccessToken();

		// Open connection
		$ch = curl_init();

                // Set URL
		curl_setopt($ch, CURLOPT_URL, "https://api.protectedshops.de/v2.0/de/partner/MYPARTNERID/shop/{$shopId}/answers/format/json");

                // Set Access Token
		curl_setopt($ch, CURLOPT_HTTPHEADER, array("Authorization: Bearer " . $accessToken));
		curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

                /**** Add answers to the request *****/
                curl_setopt($ch, CURLOPT_POST, 1);
		curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query(array('answers' => $answers)));

                // Get Response
		$response = curl_exec($ch);

		//close connection
		curl_close($ch);

                // Return the reponse as is
		return new Response($remoteResponse, 200, array('Content-Type' => 'application/json'));
	}
}

Questionary hooks

The questionary also allows you to hook to some of the events so you are notified when they happen. Currently you can provide callbacks for the following events:

beforeReload - The questionary is about to be re-rendered
afterReload - The questionary has been re-rendered
onFinish - User has pressed the finish button of the questionary

Here is an example which hooks to beforeReload and afterReload to display a loading indicator. When the questionary begins reload, the indicator will be shown and after reload, it will be hidden:

<div id="main-questionary"></div>
<div id="loadingIndicator">Loading...</div>

<script type="text/javascript" >
    $(document).ready(function() {
        var options = {
            container: "#main-questionary",
            buildUrl: "/build-questionary", // Explained in the next section
            saveUrl: "/save-answers", // Explained in the next section
            beforeReload: function() {
                $('#loadingIndicator').show()
            },
            afterReload: function() {
                $('#loadingIndicator').hide()
            }
        };
        ps.questionary(options);
    });
</script>