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
in header
string

(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"
  }
}

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
  2. eventProductView
  3. 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
in header
string

(no description)

accept-version
in header
string

(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
in header
string

(no description)

accept-version
in header
string

(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
in header
string

(no description)

customer
in query
string

Quartic customer symbol

cookie
in query
string

User cookie value (for WWW) (allowed characters: [a-z0-9A-Z-_])

placementId
in query
string

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

userId
in query
string

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

deviceId
in query
string

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

requestId
in query
string

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

deduplicate
in query
boolean

Boolean flag to explicitly ask for deduplicated content

filterProduct
in query
string

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

filterCategory
in query
string

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"
}

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"
}