PCS. Documentation

API description: code validation, prize allocation, coin toss mechanism, quiz mechanism

General information

The response format can be changed to suit your requirements by agreement of the parties. This documentation contains only the names of end points for the test environment, you will receive the names of end points for the live environment separately. All properties listed below for each endpoint are required, unless otherwise specified in the endpoint description.

Authentication

Authorization takes place using an api key, for a live environment and for a test environment there is a separate API key that will be sent to you separately.

The api key you received must be applied to all the requests described below.

To get data for your campaign, you will need to use the campaign ID in some requests, you will also receive this ID separately along with the API key. Campaign ID does not change and always remains the same. Campaign ID on test environment and live environment can be different, so for live environment you will get a new campaign ID.

Start barcode validation with check all restrictions on the email

To check the validity of the barcode and at the same time check all restrictions on the email, you need to use the following end point:

Method End point
POST https://test-code-validation.tn-rechenzentrum1.de/api/ValidateCode

Request-Body
HTTP/1.1 200 OK
Content-Type: application/json

Key Value
data {“code”:”xxxxx”, “campaign_id”: “xx”, “country”: “xx”, “email”:”xxxxx@xxxx”}
api_key xxxxxx

Where

Property Type Comment
code int Barcode
campaign_id int Campaign ID
country ISO 3166-1 alpha-2 Country ISO
email email Email address

Expected response

//barcode correct
{
    "valid": "true"
}
//barcode wrong
{
    "valid": "false"
}

The campaign may have certain restrictions, for example, checking for the number of participations of one email per day, if the check is not passed, a response will be received:

{
    "valid": "already_played"
}

Start barcode validation without check all restrictions on the email

To check only barcode validity use this endpoint:

Method End point
POST https://test-code-validation.tn-rechenzentrum1.de/api/ValidateBarCode

Request-Body
HTTP/1.1 200 OK
Content-Type: application/json

Key Value
data {“code”:”xxxxx”, “campaign_id”: “xx”, “country”: “xx”}
api_key xxxxxx

Where

Property Type Comment
code int Barcode
campaign_id int Campaign ID
country ISO 3166-1 alpha-2 Country ISO

Expected response

//barcode correct
{
    "valid": "true"
}
//barcode wrong
{
    "valid": "false"
}

Run coin toss mechanism

To start the “coin toss” mechanism, you must use the following end point:

Method End point
POST https://test-code-validation.tn-rechenzentrum1.de/api/CoinResult
The probability of winning/losing is 50/50

Request-Body
HTTP/1.1 200 OK
Content-Type: application/json

Key Value
data {“country”:”xxx”, “campaign_id”: xxxx}
api_key xxxxxx

Where

Property Type Comment
campaign_id int Campaign ID
country ISO 3166-1 alpha-2 Country ISO

Expected response

//Win
{
    "result": "1"
}
//Lose
{
    "result": "0"
}

Get prize allocation

With this end point you can get one of the prizes. With each request, one random prize will be issued with a number of characteristic. Each request reduces the prize amount by one until it reaches 0.

Method End point
POST https://universal-prize-allocation.hosting5-p.tn-rechenzentrum1.de/api/allocatePrize

Request-Body
HTTP/1.1 200 OK
Content-Type: application/json

Key Value
data {“campaign_id”: “xx”, “country”: “xx”}
api_key xxxxxx

Where

Property Type Comment
campaign_id int Campaign ID
country ISO 3166-1 alpha-2 Country ISO

Expected response

//if prize available
{

    "prize_id": "e214ce9c-b2a4-f120-69c8-9882d867ed59",

    "name": "Cinema Tickets Pairs",

    "translate": "Kinokarten ",

    "description": "Kinokarten Paris",

    "image": "https://universal-prize-allocation.hosting5-p.tn-rechenzentrum1.de/uploads/164033977545.82.png"

{
//if prize not available
{

    "error": "404",

{

Where

Property Type Comment
prize_id int Unique prize ID
name string Prize name
translate string Local translation of the prize
description string Prize description
image string Prize image url
The translation of the prize name will match the country in the request. There can only be one translation per country

Quiz. One random question

With this end point, you can get one random question and answers to it

Method End point
POST https://test-code-validation.tn-rechenzentrum1.de/api/getQuestion

Request-Body
HTTP/1.1 200 OK
Content-Type: application/json

Key Value
data {“campaign_id”: “xx”, “country”: “xx”}
api_key xxxxxx

Where

Property Type Comment
campaign_id int Campaign ID
country ISO 3166-1 alpha-2 Country ISO

Expected response

//If question is added for a country (In example - Belgium "be")
{
    "question": "Combien de Mikado y-a-t'il dans le format \"pocket\" ?,
    "answers": [
        {
            "name": "24",
            "is_correct": "1"
        },
        {
            "name": "32",
            "is_correct": "0"
        },
        {

            …..

        },
    ],
    "translates": {
        "be": {
            "translate": "Hoeveel Mikado-koekjes bevat het pocketformaat? ",
            "answers": [
                  {
                        "name": "24",
                        "is_correct": 1
                  },
                  {
                        "name": "32",
                        "is_correct": 0
                  },
                  {
                                                 .....,
                  },
            ]
        }
    }
}
//If no questions have been added for a country
{
    "error": "no question found"
}
Where
Property Type Comment
question string Quiz question
translate string Question translation
answer arrow Set of answers
name string Answer name
is_correct int [0,1] 1 – right answer, 0 – wrong answer
error string
If the question and answers have a translation, then you will get a complete array with all available translations by country. There can be several translations for one country, for example Belgium with French and Belgian

 

Quiz. Get all question and answers in one request

With this end point, you can get with one request all questions and answers

Method End point
POST https://test-code-validation.tn-rechenzentrum1.de/api/getQuestions

Request-Body
HTTP/1.1 200 OK
Content-Type: application/json

Key Value
data {“campaign_id”: “xx”, “country”: “xx”}
api_key xxxxxx

Where

Property Type Comment
campaign_id int Campaign ID
country ISO 3166-1 alpha-2 Country ISO

Expected response

//If question is added for a country (In example - Belgium "be")
{
    "questions": {
      "1":  {
           "language": "fr",{
           "question": "Combien de Mikado y-a-t'il dans le format \"pocket\" ?,
           "answers": [
                 {
                    "name": "24",
                    "is_correct": "1"
                 },
                 {
                    "name": "32",
                    "is_correct": "0"
                 },
                 {

                    …..

                 },
    ],
           "translates": {
                 "be": {
                    "translate": "Hoeveel Mikado-koekjes bevat het pocketformaat? ",
                    "answers": [
                          {
                               "name": "24",
                               "is_correct": 1
                          },
                          {
                               "name": "32",
                               "is_correct": 0
                          },
                          {
                                                               .....,
                          },
                     ]
                 }
             }
         }
      "2":  {
           "language": "fr",{
           "question": "Quelle est la recette d'un Mikado ?,
           "answers": [
                 {
                    "name": "Biscuit + Chocolat",
                    "is_correct": "1"
                 },
                 {
                    "name": "Glace + Fraise",
                    "is_correct": "0"
                 },
                 {

                    …..

                 },
    ],
           "translates": {
                 "be": {
                    "translate": "Hoeveel Mikado-koekjes bevat het pocketformaat? ",
                    "answers": [
                          {
                               "name": "Biscuit + Chocolat",
                               "is_correct": 1
                          },
                          {
                               "name": "Glace + Fraise",
                               "is_correct": 0
                          },
                          {
                                                               .....,
                          },
                     ]
                 }
             }
         }
        }
}
//If no questions have been added for a country
{
    "error": "no question found"
}
Where
Property Type Comment
question string Quiz question
translate string Question translation
language string Main language in which the question is written
answer arrow Set of answers
name string Answer name
is_correct int [0,1] 1 – right answer, 0 – wrong answer
error string
If the question and answers have a translation, then you will get a complete array with all available translations by country. There can be several translations for one country, for example Belgium with French and Belgian

Get information if there is an available prize

With this endpoint, you can check if there is still any prize available for the requested campaign

Method End point
POST https://universal-prize-allocation.hosting5-p.tn-rechenzentrum1.de/api/allocatePrizeCheck

Request-Body
HTTP/1.1 200 OK
Content-Type: application/json

Key Value
data {“campaign_id”: “xx”, “country”: “xx”}
api_key xxxxxx

Where

Property Type Comment
campaign_id int Campaign ID
country ISO 3166-1 alpha-2 Country ISO

Expected response

//if the prize is available
{

    "result": "available",

{
//if the prize is not available
{

    "error": "404",

{

Check email restrictions

With this endpoint, you can check if this email meets any campaign restrictions. For example, an email can only participate 2 times a day

Method End point
POST https://test-code-validation.tn-rechenzentrum1.de/api/checkEmailLimit

Request-Body
HTTP/1.1 200 OK
Content-Type: application/json

Key Value
data {“code”:”xxxxx”, “campaign_id”: “xx”, “country”: “xx”, “email”:”xxxxx@xxxx”}
api_key xxxxxx

Where

Property Type Comment
code int Barcode
campaign_id int Campaign ID
country ISO 3166-1 alpha-2 Country ISO
email email Email address

Expected response

//If the sent email passes the restrictions and can take part in the draw
{

    "valid": "Allowed",

{
//If the sent email does not pass the restrictions and can take part in the draw
{

    "error": "Request limit exceeded with this email",

{

Send receipt

Using this endpoint, you can send a photo of the receipt for further verification

Method End point
POST https://test-code-validation.tn-rechenzentrum1.de/api/getImage

Request-Body
HTTP/1.1 200 OK
Content-Type: application/json

Key Value
data {“country”: “xx”, “receipt_number”:”xxxxx”, “out_id”: “xxxxxx”, “out_hash”: “xxxx”, “campaign_id”: “xx”, “image_url”: “xxxx”}
api_key xxxxxx

Where

Property Type Comment
country ISO 3166-1 alpha-2 Country ISO
campaign_id int URL to the uploaded image of the receipt
receipt_number int Receipt number as entered by the user
out_id int Unique participation ID of our application
out_hash int SHA512 hash of the unique identified
image_url string URL to the uploaded image of the receipt

Expected response

//if the check passed the check
{
    "value:out_id": {
                                     “id”: xxxx,
                                       “result”: true
    {
{
//if the check did’nt pass the check
{
    "value:out_id": {
                                     “id”: xxxx,
                                       “result”: false
    {
{

In response, you will receive an array with your unique participation ID, which will contain our unique ID and the result of the validation