Quarticon API API Reference

Obsługa błędów

Każda metoda dostępna w API zwraca odpowiedni komunikat i kod błędu w przypadku wystąpienia błędu.

W przypadku wystąpienie błędu należy spodziewać się odpowiedzi takiej jak poniższa:

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

Gdzie:

Pole Opis
status Status żądania
timestamp Timestamp odpowiedzi
data
error_code Kod błędu
error_message Opis błędu

Struktura

Każdy obiekt response jest zawarty w "kopercie". Dzięki temu każdy response ma wspólny zestaw kluczy których można by oczekiwać:

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

Gdzie:

Pole Opis
status Status żądania
timestamp Timestamp odpowiedzi
data Dodatkowe dane odpowiedzi
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

Klucz użytkownika API przesyłany w nagłówku żądania umożliwiającego aktualizację danych katalogu.

type
apiKey
name
x-api-key
in
header

CollectProfile

CollectProfile

POST /collectprofile

collectProfile umożliwia przesyłanie nam informacji o użytkowniku, które następnmie zostaną użyte do przeprowadzania kampanii mailingowej.

Wszystkie dane na ten endpoint powinny zostać wysłane zapytaniem typu POST o następującej strukturze:

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

Metoda ta powinna być wywoływana ilektroć dane użytkownika ulegną zmianie. W jednym zapytaniu możemy przesłać tylko jeden profil.

Gdzie:

Field Typ Czy wymagany Opis
userId String yes Identyfikator użytkownika
cookie String yes Ostatnie znane ciastko/identyfikator użytkownika
email String no Poprawny e-mail użytkownika
agreement Boolean nie, domyślnie false Informuje nas czy Quartic może wysyłać za Ciebie maile do użytkowników

Example Answer:

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

User object

x-api-key
in header
string

(no description)

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

OK

405 Method Not Allowed
Error

Invalid input

500 Internal Server Error
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

Event

POST /track/event

Umożliwia przesłanie do API obiektów opisujących zdarzenie. W tym celu należy wysłać metodą POST żądanie z treścią zgodną z poniższym schematem:

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

Gdzie:

Pole Typ Pole wymagane Opis
customer string tak Symbol klienta Quartic
eventType string tak Typ eventu. Możliwe wartości:
  1. eventClick
  2. eventProductView
  3. eventTransaction
userId string nie Identyfikator użytkownika (dla zalogowanych)
deviceId string nie Unikalny identyfikator urządzenia
timestamp integer tak Timestamp zdarzenia w formacie UNIX
cookie string nie Wartość cookie/identyfikatora użytkownika

Przykładowa spodziewana odpowiedź:

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

Wszystkie obiekty typu event mają wspólny zestaw właściwości. Aby przesłać obiekt zdarzenia konkretnego typu należy zapoznać się z listą jego unikalnych właściwości.

Event

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
Empty

OK

405 Method Not Allowed
Error

Invalid input

500 Internal Server Error
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

Product

POST /data/product

Umożliwia przesłanie do API informacji o produkcie (aktualizacja katalogu). W tym celu należy wysłać metodą POST żądanie z treścią zgodną z poniższym schematem:

{
  "id": 2,
  "title": "Przykładowy tytuł",
  "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": "Kategoria1"
    },
    {
      "id": 2,
      "name": "Kategoria2"
    }
  ],
  "catalogSymbol": ""
}
Product

Obiekt produktu

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
Empty

OK

405 Method Not Allowed
Error

Invalid input

500 Internal Server Error
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

Recommendation

GET /recommendation

W celu pobrania rekomendowanych produktów należy wysłać metodą GET treść żadania używając opisanych parametrów URL QUERY.

Przykładowa spodziewana odpowiedź:

{
  "status": "OK",
  "timestamp": 1486987017,
  "qrId": "ad_58a19f08ce6b6",
  "duplicatesCount": 0,
  "data": [
    {
      "id": "10",
      "title": "Przykładowy tytuł 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": "Przykładowy tytuł 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

Symbol klienta Quartic

cookie
in query
string

Wartość cookie użytkownika (dla WWW) (dozwolone znaki: [a-z0-9A-Z-_])

placementId
in query
string

ID placementu quarticon.com (dozwolone znaki: [a-z0-9A-Z-_])

userId
in query
string

ID użytkownika dla którego wyświetlamy rekomendacje (dozwolone znaki: [a-z0-9A-Z-_])

deviceId
in query
string

ID urządzenia dla którego wyświetlamy rekomendacje (dozwolone znaki: [a-z0-9A-Z-_])

requestId
in query
string

Unikatowy identyfikator żądania (używany do deduplikacji rekomendacji). Musi być użyty razem z parametrem "deduplicate" (dozwolone znaki: [a-z0-9A-Z-_])

deduplicate
in query
boolean

Flaga boolowska, aby wyraźnie poprosić o zdeduplikowaną treść

filterProduct
in query
string

Pasujące do tego produktu np. inni użytkownicy oglądali również (dozwolone znaki: [a-z0-9A-Z-_,])

filterCategory
in query
string

Filtr dla kategorii

200 OK

OK

type
object
500 Internal Server Error
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

Poprawny e-mail użytkownika

cookie: string
agreement: boolean

Określa czy Quartic może wysyłać maila do użytkownika

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

Product: object

Obiekt produktu

id: string

Identyfikator produktu (mid) (dozwolone znaki: [a-z0-9A-Z-_])

title: string

Tytuł produktu

image: string

URL miniatury

description: string

Opis produktu

url: string

Link do produktu

price: number (float)

Cena produktu po obniżce

priceOld: number (float)

Cena produktu przed obniżką

custom1: string

Dodatkowy opis produktu

custom2: string

Dodatkowy opis produktu

custom3: string

Dodatkowy opis produktu

status: boolean

Status produktu (czy jest widoczny i można go rekomendować)

categories: Category

Kategorie produktu

Category
catalogSymbol: string

Symbol katalogu do którego należy produkt

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

Zamówiony produkt

productId: string

Identyfikator produktu

price: number (float)

Cena zamówionego produktu

quantity: number (integer)

Ilośc zamówionego produktu

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

Category: object

Kategoria produktu

id: integer

Identyfikator kategorii

name: string

Nazwa kategorii

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

RecommendedProduct:

Rekomendowany produkt

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

Obiekt bazowy dla zdarzeń

eventType: string

Nazwa klasy eventu

userId: string

ID zalogowanego użytkownika

userEmail: string

Email zalogowanego użytkownika

deviceId: string

ID urządzenia

timestamp: integer
referrer: string

Adres URL strony z której użytkownik został przekierowany

cookie: string

Wartość cookie/identyfikatora użytokwnika

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

EventClick:

Klik na link do produktu. Klik na element wyświetlany w ramce rekomendacji.

productId: string

ID rekomendacji po pobraniu danych z /recommendation.

trackingString: string

Parametry produktu - pobierany z /recommendation

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

EventProductView:

Przesyłany gdy obiekt pobrany z rekomendacji zostanie wyświetlony użytkownikowi

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

EventTransaction:

Po złożeniu zamówienia

transactionId: string

ID transakcji

basket: TransactionProduct

ID, cena oraz ilość zakupionych produktów

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"
}
Documentation by Spectacle