FORMAT: 1A
HOST: https://pos.api.qnips.com/api/pos/v3

# qnips Profile Activation API

## General Information

The qnips Profile Activation API can be used to activate prebuilt profiles when needed.<br>
There are two different environments for this API:
* **LIVE** = production-environment (accessible at https://pos.api.qnips.com/api/pos/v3)
* **STAGING** = test-environment (accessible at https://pos.dev.qnips.com/api/pos/v3) 

To use this API, you will need a hexadecimal `DevKey`, provided by qnips. With it, the API will identify your client as a requestor. Your key is valid for both environments, **LIVE** and **STAGING**. Please ask your primary contact at qnips for your personal `DevKey`.

       
## Generating a SecurityToken

As the process of activation of a pregenerated profile is a sensible operation, the process involves a special `SecurityToken` which 
needs to be generated individually for each Call of this API. It must be generated by a special algorithm described below.

+ build a String with `profileId` + `„ac39d745a3a540a294ec46200ed3d696“` + `DevKey` with no whitespaces in between:

    + `profileId`: the Id of the profile which is to be activated. Usually, this will be the token on a given medium (e.g. a barcode printed on a gift card or a customer's QR code in an app).
    + `„ac39d745a3a540a294ec46200ed3d696“`: a constant string 
    + `DevKey`: your developer key assigned to your organisation by qnips

    Example: 
    
    with `input`=„123456“ and `DevKey`=„af87b1“ the result string should be: **„123456ac39d745a3a540a294ec46200ed3d696af87b1“**

+ now build the MD5-Hash for the result of the previous step. 

    For the example value of step 1 the Hash would be **„3f70267c85aae2d893321a68a52ae9f8“**

+ This Hash value is your individual `SecurityToken` which must be set as the Header of each activation call.


## Activating a Profile [/profileactivations/{id}/activate]

With this resource, you can set a prebuilt Profile as active by submitting the `profileId`. 
Please contact your primary qnips contact for the process of prebuilding Profiles as a precondition for working with this resource.

### /profileactivations/{id}/activate [POST]

+ Parameters
    + id (string, `'ab12345'`) ... this is the Id of the profile which is to be activated.

+ Request

    + Headers
    
            DevKey : The `DevKey` that has been provided by qnips, identifying you as requestor
            SecurityToken : This is an individual value for each `profileId`, it needs to be calculated using the algorithm described under 'Generating SecurityToken' of this API documentation

+ Response 200

    + Body
    
            in case of a successful activation, the response body will remain empty

+ Response 400 

        // HTTP-BadRequest: is returned in case you supplied an invalid profileId
        {
            "Message": "no data for your request"
        }

+ Response 401 

        // HTTP-Unauthorized: is returned in case you supplied a wrong DevKey or no DevKey at all
        {
            "Message": "unknown or wrong DevKey"
        }
            
+ Response 401 

        // HTTP-Unauthorized: is returned in case you supplied a wrong SecurityToken or no SecurityToken at all
        {
            "Message": "unknown or wrong SecurityToken"
        }

+ Response 412

        // HTTP-PreconditionFailed: is returned in case you supplied Id of an already activated profile
        {
            "Message": "this profile has already been activated"
        }

## Cancelling a Profile Activation [/profileactivations/{id}/cancellation]

With this resource, you can undo an activation of a Profile made by the previous resource. Please regard, that this resource is meant 
for cancellations only. It is not allowed to use this resource in case of returns. 

### /profileactivations/{id}/cancellation [POST]

+ Parameters
    + id (string, `'ab12345'`) ... the Id of the Profile whose activation you want to cancel.

+ Request

    + Headers
    
            DevKey : The `DevKey` that has been provided by qnips, identifying you as a requestor
            SecurityToken : This is an individual value for each `profileId`, it needs to be calculated using the algorithm described under 'Generating SecurityToken' of this API documentation

+ Response 200

    + Body
    
            in case of success, the response body will remain empty

+ Response 400 

        // HTTP-BadRequest: is returned in case you supplied an invalid profileId
        {
            "Message": "no data for your request"
        }

+ Response 401 

        // HTTP-Unauthorized: is returned in case you supplied a wrong DevKey or no DevKey at all
        {
            "Message": "unknown or wrong DevKey"
        }
            
+ Response 401 

        // HTTP-Unauthorized: is returned in case you supplied a wrong SecurityToken or no SecurityToken at all
        {
            "Message": "unknown or wrong SecurityToken"
        }

+ Response 409 

        // HTTP-Conflict: is returned in case the balance of the profile is not equal to the starting balance
        {
            "Message": "not all requirements met"
        }