Quarticon API API Reference

Error handling

Each method available in the API returns an error message and an error code, if an error appears.

In case of an error, a message like this should be expected:

{
  "status": "ERROR",
  "timestamp": 1486987017,
  "data":
  {
    "error_code": "http.status.405",
    "error_message": "Invalid data"
  }
}

Where:

Field Description
status Request status
timestamp Response timestamp
data
error_code Error code
error_message Error description

Structure

Each response object is contained in an envelope. Thanks to this, each response has a common key set we can expect:

{
  "status": "OK",
  "timestamp": 1486987017,
  "data": [
    ...
  ]
}

Where:

Field Description
status Request status
timestamp Response timestamp
data Additional response data
API Endpoint
https://restapi.quartic.pl/store/
Request Content-Types: application/json
Response Content-Types: application/json
Schemes: https
Version: 1.0.6

Authentication

api_key

User's API key which should be sent when modyfing user's catalog data.

type
apiKey
name
x-api-key
in
header

CollectProfile

POST /collectprofile

The collectProfile Endpoint enable sending information about User email, which will be use in our mailing image api. To this end, you should send a POST request according to the scheme below:

{
        "userId": "samp1eUs3r1d",
        "cookie": "sampleUserC00kie",
        "email": "valid@email.com",
        "agreement": true,
    }

This method should be called every time profile data changes. We can send only one single profile object per request.

Where:

Field Type Is required Description
userId String yes ID of the User
cookie String yes Latest user cookie
email String no Valid user email
agreement Boolean no, dafault false Informs us if Quartic should send emails on Your behalf

Example Answer:

{
  "status": "OK",
  "timestamp": "2017-01-01 13:00:00"
}

User object

x-api-key: string
in header

(no description)

Request Example
{
  "userId": "string",
  "email": "string",
  "cookie": "string",
  "agreement": "boolean"
}
200 OK

OK

405 Method Not Allowed

Invalid input

500 Internal Server Error

Unexpected error

Response Example (200 OK)
{
  "status": "string",
  "timestamp": "string"
}
Response Example (405 Method Not Allowed)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}
Response Example (500 Internal Server Error)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}

Contact

POST /contact

The contact Endpoint enable sending information about User email, which will be use in our system to marketing automation. To this end, you should send a POST request according to the scheme below:

{
        "cookie": "test_cookie",
        "email": "email@test.com",
        "agreements": [{
                "t": "term",
                "c": "The content of the consent registration",
                "s": true
            },
            {
                "t": "newsletter",
                "c": "The content of the newsletter consent",
                "s": true
            },
            {
                "t": "personalization",
                "c": "Content of personalization consent",
                "s": false
            }
        ],
        "tags": [{
                "n": "firstname",
                "v": "Test user first name 1"
            },
            {
                "n": "lastname",
                "v": "Test user last name 1"
            }
        ]
    }

This method should be called every time profile data changes. We can send only one single profile object per request.

Where:

Field Type Is required Description
cookie String no Latest user cookie
email String yes Valid user email
agreements array no An array of user consents that tells us if Quartic can send emails to user

structure of agreements:

Field Type Is required Description
t String yes Agreement type identifier, e.g. newsletter, terms etc.
c String yes Agreement text
s boolean yes Is agreement given?

structure of tags:

Field Type Is required Description
n String yes Tag name
v String yes Tag value

We only accept existing tags (they must first be created in control panel).

Example Answer:

{
  "status": "OK",
  "timestamp": "2017-01-01 13:00:00"
}
x-api-key: string
in header

(no description)

Request Example
{
  "email": "string",
  "cookie": "string",
  "agreements": "array",
  "tags": "array"
}
200 OK

OK

405 Method Not Allowed

Invalid input

500 Internal Server Error

Unexpected error

Response Example (200 OK)
{
  "status": "string",
  "timestamp": "string"
}
Response Example (405 Method Not Allowed)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}
Response Example (500 Internal Server Error)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}

GET /contact

It allows you to retrieve information about user. To this end, you should send a GET request according to the scheme below:

{
        "email": "valid@email.com"
    }

In a single query you can retrieve only one contact.

Where:

Field Type Is required Description
email String yes Valid user email

Example Answer:

{
  "status": "OK",
  "timestamp": "2017-01-01 13:00:00",
  "data": {
      "email": "test@email.com",
      "agreements": [{
              "t": "term",
              "c": "Content of registration consent",
              "s": true
          },
          {
              "t": "newsletter",
              "c": "The content of the newsletter consent",
              "s": true
          }
      ],
      "tags": [
          {
              "n": "firstname",
              "v": "user name"
          },
          {
              "n": "lastname",
              "v": "user last name"
          }
      ]
  }
}

User object

x-api-key: string
in header

(no description)

Request Example
{
  "email": "string"
}
405 Method Not Allowed

Invalid input

500 Internal Server Error

Unexpected error

Response Example (200 OK)
{
  "email": "string",
  "cookie": "string",
  "agreements": "array",
  "tags": "array"
}
Response Example (405 Method Not Allowed)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}
Response Example (500 Internal Server Error)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}

Event

POST /track/event

Enables sending event description objects to the API. To do this, send a POST request formatted like this:

{
  "customer": "quartic_account",
  "eventType": "eventClick",
  "userId": "1",
  "userEmail": "test@example.com",
  "deviceId": "android-12",
  "timestamp": 1482840417,
  "referrer": "http://facebook.com/?id=85004932",
  "cookie": "8sjfe8fh",
  "productId": "101",
  "trackingString": "ew0KCSJxcmlkIjogImFkXzU4NzRkOTk5ZDE2MTMiLA0KCSJxZHBpIjogImcxcGsiLA0KCSJwaWQiOiAiNCIsDQoJImNpIjogIjU0ODE2IiwNCgkic3MiOiAicnR"
}

Where:

Field Type Required field Description
customer string yes Quartic customer symbol
eventType string yes Event type. Possible values:
  1. [eventClick](#definition-EventClick)
  2. [eventProductView](#definition-EventProductView)
  3. [eventTransaction](#definition-EventTransaction)
userId string no User ID (for logged users)
deviceId string no Unique device id
timestamp integer yes UNIX formatted event timestamp
cookie string no Cookie value

An expected response example:

{
  "status": "OK",
  "timestamp": 1486987017
}

All event type objects have a common set of properties. To send in a specific event type object, pay attention to its unique properties.

Event object

x-api-key: string
in header

(no description)

accept-version: string
in header

(no description)

Request Example
{
  "eventType": "string",
  "userId": "string",
  "userEmail": "string",
  "deviceId": "string",
  "timestamp": "integer",
  "referrer": "string",
  "cookie": "string"
}
200 OK

OK

405 Method Not Allowed

Invalid input

500 Internal Server Error

Unexpected error

Response Example (200 OK)
{
  "status": "string",
  "timestamp": "string"
}
Response Example (405 Method Not Allowed)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}
Response Example (500 Internal Server Error)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}

Product

POST /data/product

Enables sending product info (catalog update) to the API. To do this, send a POST request formatted like this:

{
  "id": 2,
  "title": "Title example",
  "image": "http:\/\/exampledomain.com\/image\/hp_1-228x228.jpg",
  "description": "Lorem ipsum dolor...",
  "url": "http:\/\/exampledomain.com\/8ef8y8ef",
  "price": "99.00",
  "priceOld": "199.00",
  "custom1": "",
  "custom2": "",
  "custom3": "",
  "status": true,
  "categories": [
    {
      "id": 1,
      "name": "Category1"
    },
    {
      "id": 2,
      "name": "Category2"
    }
  ],
  "catalogSymbol": ""
}

Product object

x-api-key: string
in header

(no description)

accept-version: string
in header

(no description)

Request Example
{
  "id": "string",
  "title": "string",
  "image": "string",
  "description": "string",
  "url": "string",
  "price": "number (float)",
  "priceOld": "number (float)",
  "custom1": "string",
  "custom2": "string",
  "custom3": "string",
  "status": "boolean",
  "categories": [
    {
      "id": "integer",
      "name": "string"
    }
  ],
  "catalogSymbol": "string"
}
200 OK

OK

405 Method Not Allowed

Invalid input

500 Internal Server Error

Unexpected error

Response Example (200 OK)
{
  "status": "string",
  "timestamp": "string"
}
Response Example (405 Method Not Allowed)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}
Response Example (500 Internal Server Error)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}

Recommendation

GET /recommendation

To download recommended products, send a GET method request using described URL QUERY parameters.

A response example:

{
  "status": "OK",
  "timestamp": 1486987017,
  "qrId": "ad_58a19f08ce6b6",
  "duplicatesCount": 0,
  "data": [
    {
      "id": "10",
      "title": "Title example 10...",
      "image": "http://placehold.it/350x150",
      "description": "Lorem ipsum dolor...",
      "url": "",
      "price": "19.99",
      "priceOld": 24.50,
      "custom1": "",
      "custom2": "",
      "custom3": "",
      "status": true,
      "trackingString": "IjoiNGI2ZDEwNzZjNzFkMGM4ZCIsInAiOiIyMDIiLCJzcyI6InJ0Yl8xMjg0MyJ9"
    },
    {
      "id": "202",
      "title": "Title example 202...",
      "image": "http://placehold.it/350x150",
      "description": "Lorem ipsum dolor...",
      "url": "",
      "price": "100.00",
      "priceOld": null,
      "custom1": "",
      "custom2": "",
      "custom3": "",
      "status": true,
      "trackingString": "IjoiNGI2ZDEwNzZjNzFkMGM4ZCIsInAiOiIyMDIiLCJzcyI6InJ0Yl8xMjg0MyJ9"
    }
  ]
}
accept-version: string
in header

(no description)

customer: string
in query

Quartic customer symbol

placementId: string
in query

quarticon.com placement ID (allowed characters: [a-z0-9A-Z-_])

cookie: string
in query

Required if [deviceId] is not sended to API User cookie value (for WWW) (allowed characters: [a-z0-9A-Z-_])

deviceId: string
in query

Required if [cookie] is not sended to API ID of the device which receives the recommendations (allowed characters: [a-z0-9A-Z-_])

userId: string
in query

ID of the user who receives the recommendations (allowed characters: [a-z0-9A-Z-_])

requestId: string
in query

Unique request ID (used for content deduplication). This must be used together with 'deduplicate' parameter to work (allowed characters: [a-z0-9A-Z-_])

deduplicate: boolean
in query

Boolean flag to explicitly ask for deduplicated content

filterProduct: string
in query

Related do this product, e.g. other users also viewed (allowed characters: [a-z0-9A-Z-_])

filterCategory: string
in query

Category filter

200 OK

OK

type
object
500 Internal Server Error

Unexpected error

Response Example (200 OK)
{
  "status": "string",
  "timestamp": "string",
  "placementId": "string",
  "qrId": "string",
  "data": [
    {
      "trackingString": "string",
      "id": "string",
      "title": "string",
      "image": "string",
      "description": "string",
      "url": "string",
      "price": "number (float)",
      "priceOld": "number (float)",
      "custom1": "string",
      "custom2": "string",
      "custom3": "string",
      "status": "boolean",
      "categories": [
        {
          "id": "integer",
          "name": "string"
        }
      ],
      "catalogSymbol": "string"
    }
  ]
}
Response Example (500 Internal Server Error)
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}

Schema Definitions

CollectProfile: object

userId: string
email: string

Valid user e-mail

cookie: string
agreement: boolean

Determines if Quartic can send emails on your behalf

Example
{
  "userId": "string",
  "email": "string",
  "cookie": "string",
  "agreement": "boolean"
}

Create or update Contact: object

email: string

Valid user email

cookie: string

Last known user cookie

agreements: array

An array of consents that specifies the user's individual consents to send him e-mails

tags: array

User tags (city, phone, age etc)

Example
{
  "email": "string",
  "cookie": "string",
  "agreements": "array",
  "tags": "array"
}

Get Contact: object

email: string

Valid user email

Example
{
  "email": "string"
}

Product: object

Product object

id: string

Product id (mid) (allowed characters: [a-z0-9A-Z-_])

title: string

Product title

image: string

Thumbnail URL

description: string

Product description

url: string

Link to the product

price: number (float)

Product price after discount

priceOld: number (float)

Product price before discount

custom1: string

Additional product description

custom2: string

Additional product description

custom3: string

Additional product description

status: boolean

Product status (is it visible and can we recommend it)

categories: Category

Product categories

Category
catalogSymbol: string

Symbol of the catalog containing the product

Example
{
  "id": "string",
  "title": "string",
  "image": "string",
  "description": "string",
  "url": "string",
  "price": "number (float)",
  "priceOld": "number (float)",
  "custom1": "string",
  "custom2": "string",
  "custom3": "string",
  "status": "boolean",
  "categories": [
    {
      "id": "integer",
      "name": "string"
    }
  ],
  "catalogSymbol": "string"
}

TransactionProduct: object

Ordered product

productId: string

Product id

price: number (float)

Ordered product price

quantity: number (integer)

Ordered product quantity

Example
{
  "productId": "string",
  "price": "number (float)",
  "quantity": "number (integer)"
}

Category: object

Product category

id: integer

Category id

name: string

Category name

Example
{
  "id": "integer",
  "name": "string"
}

RecommendedProduct:

Recommended product

trackingString: string
Example
{
  "trackingString": "string",
  "id": "string",
  "title": "string",
  "image": "string",
  "description": "string",
  "url": "string",
  "price": "number (float)",
  "priceOld": "number (float)",
  "custom1": "string",
  "custom2": "string",
  "custom3": "string",
  "status": "boolean",
  "categories": [
    {
      "id": "integer",
      "name": "string"
    }
  ],
  "catalogSymbol": "string"
}

Event: object

Base object for the events

eventType: string

Event class name

userId: string

Logged user ID

userEmail: string

Logged user email

deviceId: string

Device ID

timestamp: integer
referrer: string

URL of the website that redirected the user

cookie: string

Cookie (in case of WWW)

Example
{
  "eventType": "string",
  "userId": "string",
  "userEmail": "string",
  "deviceId": "string",
  "timestamp": "integer",
  "referrer": "string",
  "cookie": "string"
}

EventClick:

Click on the link to the product. Click on the element displayed in the recommendation frame.

productId: string

ID of the recommendation after downloading data from /recommendation.

trackingString: string

Product parameters - downloaded from /recommendation.

Example
{
  "productId": "string",
  "trackingString": "string",
  "eventType": "string",
  "userId": "string",
  "userEmail": "string",
  "deviceId": "string",
  "timestamp": "integer",
  "referrer": "string",
  "cookie": "string"
}

EventProductView:

Send when the object downloaded from recommendation is displayed to the user.

productId: string
Example
{
  "productId": "string",
  "eventType": "string",
  "userId": "string",
  "userEmail": "string",
  "deviceId": "string",
  "timestamp": "integer",
  "referrer": "string",
  "cookie": "string"
}

EventTransaction:

After making an order

transactionId: string

ID of the transaction

basket: TransactionProduct

ID, price and quantity of the ordered items

TransactionProduct
Example
{
  "transactionId": "string",
  "basket": [
    {
      "productId": "string",
      "price": "number (float)",
      "quantity": "number (integer)"
    }
  ],
  "eventType": "string",
  "userId": "string",
  "userEmail": "string",
  "deviceId": "string",
  "timestamp": "integer",
  "referrer": "string",
  "cookie": "string"
}

Error: object

status: string ERROR
timestamp: string
data: object
error_code: string
error_message: string
Example
{
  "status": "string",
  "timestamp": "string",
  "data": {
    "error_code": "string",
    "error_message": "string"
  }
}

Empty: object

status: string OK
timestamp: string
Example
{
  "status": "string",
  "timestamp": "string"
}