Načíavam

API pripojenie

API rozhranie slúži na aplikačnú komunikáciu medzi webovou aplikáciou (eshopom) a službou vyhľadávania Magrano.

API koncový bod / Autentifikácie

K Magrano API sa pripája prostredníctvom HTTP requestov na nižšie definovanú cieľovú adresu.
Autorizácia požiadaviek je vykonávaná prostredníctvom BASIC HTTP autentifikácie pomocou užívateľského mena a hesla.

Užívateľské meno - API kľúč
Heslo - vypočítaný podpis na základe údajov, ktoré sa menia v každej požiadavke. Základný reťazec pre šifrovanie je tvorený spojením času, metódy requestu a API kľúča. Následne je potom hexadecimálne zašifrovaný HMAC metódou, SHA1 algoritmom a privátnym kľúčom (Client secret)

Obsah požiadavky je odoslaný vo formáte JSON prostredníctvom POST metódy.
V hlavičke požiadavky je potrebné odoslať Timestamp hodnotu, ktorá bola použitá na výpočet podpisu (príklad: 20200101T120000Z, GMT časové pásmo).
Komunikácia s API prebieha v kódovaní znakov UTF-8.
https://api.magrano.com/

Vyhľadanie položiek

JSON požiadavka

Požiadavka musí byť odoslaná pomocou formátu JSON.
Každá požiadavka môže obsahovať niekoľko voliteľných parametrov, ktoré sú popísané v špecifikácii. Na základe týchto odoslaných požiadaviek je následné vytvorená odpoveď, ktorá je taktiež vo formáte JSON.

Požiadavka môže byť aj prázdna. V takom prípade sú poskytnuté výsledky vyhľadávania podľa predvolených kritérií.
Parameter
Popis
lang
string - Nepovinné
Jazyk výsledkov vyhľadávania
(sk, cz, en, de, ro, bg, hu, hr, pl, si, fr, ru, it...)
currency
string - Nepovinné
Mena výsledkov vyhľadávania
(EUR, CZK, USD, GBP, BGN, PLN, HUF, RON...)
price
string - Nepovinné
Kľúč cenovej hladiny
V prípade nepoužitia tejto vlastnosti sa použije predvolená hodnota zo systému.
Príklad: b2b, b2c, reg...
group
string - Nepovinné
Kľúč skupiny návštevníka pre zobrazenie produktov s obmedzeným prístupom.
V prípade nepoužitia tejto vlastnosti sa použije predvolená hodnota zo systému.
Príklad: b2b, reg...
query
string - Nepovinné
Hľadaný výraz

V prípade nevyplnenia alebo nepoužitia tohto parametru bude vrátený zoznam odporúčaných položiek.
results
Nepovinné
Požadované výsledky hľadania.

Predvolené hodnoty
products, categories, brands
products
Nepovinné
V prípade použitia tohto parametru bude vyžadovaná odpoveď s výsledkom vyhľadaných produktov
fields
array - Nepovinné
Požadované hodnoty vyhľadaných položiek.

Možné hodnoty
item_id // ID položky z feedu
title // Názov položky
title_highlighted // Názov položky so zvýraznením vyhľadávania (CSS class="result_highlighted")
url // URL adresa položky
price // Bežná cena položky
sale_price // Zvýhodnená cena položky
availibility // Dostupnosť položky
image_thumb // Náhľad položky s nižším rozlíšením
image_large // Náhľad položky s vyšším rozlíšením
available_filters // Zoznam dostupných filtrov pre produkty. Sumárny zoznam bude uvedený ako jeden z parametrov pre celú požiadavku.

Predvolené hodnoty
item_id
results_max
int - Nepovinné
Maximálny počet vrátených výsledkov
V prípade hodnoty 0 budú vrátené všetky výsledky.

Predvolená hodnota
20
results_offset
int - Nepovinné
Číslo počiatočného záznamu výsledkov hľadania. Vhodné pre stránkovanie vyhľadaných položiek.

Predvolená hodnota
0
filters
Nepovinné
Rozšírené filtrovanie podľa parametrov, ceny, značky a dostupnosti.
params
array - Nepovinné
Zoznamu parametrov pre rozšírené filtrovanie.

Požadované sú hodnoty typu {Kľúč: Hodnota}. Hodnota môže byť uvedená aj ako pole hodnôt.

V prípade použitia viacerých hodnôt v rámci pola s jedným kľúčom bude použitý operátor OR.
{Kľúč: [Hodnota1,Hodnota2]} bude vracať položky, ktoré obsahujú aspoň jednu hodnotu pre parameter Kľúč.

V prípade použitie viacerých parametrov s rovnakým kľúčom bude použitý operátor AND. {Kľúč: Hodnota1}, {Kľúč: Hodnota2} bude vracať položky, ktoré obsahujú obidve hodnoty pre parameter Kľúč.
brands
array - Nepovinné
Zoznamu značiek pre rozšírené filtrovanie.

Používané sú hodnoty ID zo zdrojových feedov.
categories_included
array - Nepovinné
Zoznam vybraných kategórií, z ktorých budú produkty zaradené do výsledku vyhľadávania.
V prípade nepoužitia alebo prázdnej hodnoty budú vo výsledku produkty všetkých kategórií.
category_id
string - Nepovinné
Používané sú hodnoty ID zo zdrojových feedov.
magrano_id
int - Nepovinné
Používané sú hodnoty ID z databázy Magrano
categories_excluded
array - Nepovinné
Zoznam kategórií, z ktorých produkty budú vylúčené z výsledku vyhľadávania.
V prípade nepoužitia alebo prázdnej hodnoty nebudú z výsledku vynechané žiadne produkty.
category_id
string - Nepovinné
Používané sú hodnoty ID zo zdrojových feedov.
magrano_id
string - Nepovinné
Používané sú hodnoty ID z databázy Magrano
price
Nepovinné
Požadovaný rozsah ceny produktov
price_from
decimal - Nepovinné
Minimálna cena položky

Predvolená hodnota
0
price_to
decimal - Nepovinné
Maximálna cena položky
Hodnota -1, znamená bez obmedzenia

Predvolená hodnota
-1
in_stock
boolean - Nepovinné
Vyhľadať produkty na sklade.

Predvolená hodnota
false
sort_by
string - Nepovinné
Zoradenie výsledkov vyhľadávania.

Možné hodnoty
best_match // Podľa najlepšej zhody
price_asc // Podľa ceny vzostupne
price_desc // Podľa ceny zostupne
sales // Podľa predajov, od najvyššej hodnoty

Predvolená hodnota
best_match
categories
V prípade použitia tohto parametru bude vyžadovaná odpoveď s výsledkom vyhľadaných kategórií
fields
array - Nepovinné
Požadované hodnoty vyhľadaných položiek.

Možné hodnoty
item_id // ID položky z feedu
title // Názov položky
title_highlighted // Názov položky so zvýraznením vyhľadávania (CSS class="result_highlighted")
url // URL adresa položky

Predvolené hodnoty
item_id
results_max
int - Nepovinné
Maximálny počet vrátených výsledkov
V prípade hodnoty 0 budú vrátené všetky výsledky.

Predvolená hodnota
10
results_offset
int - Nepovinné
Číslo počiatočného záznamu výsledkov hľadania. Vhodné pre stránkovanie vyhľadaných položiek.

Predvolená hodnota
0
filters
Nepovinné
Rozšírené filtrovanie kategórií.
categories_included
array - Nepovinné
Zoznam vybraných kategórií do výsledku vyhľadávania.
category_id
string - Nepovinné
Používané sú hodnoty ID zo zdrojových feedov.
magrano_id
int - Nepovinné
Používané sú hodnoty ID z databázy Magrano
categories_excluded
array - Nepovinné
Zoznam vylúčených kategórií z odpovede.
category_id
string - Nepovinné
Používané sú hodnoty ID zo zdrojových feedov.
magrano_id
string - Nepovinné
Používané sú hodnoty ID z databázy Magrano
brands
V prípade použitia tohto parametru bude vyžadovaná odpoveď s výsledkom vyhľadaných značiek
fields
array - Nepovinné
Požadované hodnoty vyhľadaných položiek.

Možné hodnoty
item_id // ID položky z feedu
title // Názov položky
title_highlighted // Názov položky so zvýraznením vyhľadávania (CSS class="result_highlighted")
url // URL adresa položky

Predvolené hodnoty
item_id
results_max
int - Nepovinné
Maximálny počet vrátených výsledkov
V prípade hodnoty 0 budú vrátené všetky výsledky.

Predvolená hodnota
10
results_offset
int - Nepovinné
Číslo počiatočného záznamu výsledkov hľadania. Vhodné pre stránkovanie vyhľadaných položiek.

Predvolená hodnota
0
Príklad najjednoduchšej požiadavky, ktorá vráti predvolený počet vyhľadaných produktov, kategórii a značiek.
{
        "query": "hladany vyraz"
}
Príklad jednoduchej požiadavky na vrátenie požadovaného počtu vyhľadávaných produktov.
{
        "query": "hladany vyraz",
        "results": {
                "products": {
                        "results_max": 10
                }
        }
}
Príklad rozšírenej požiadavky na vrátenie určitého počtu výsledkov vyhľadania produktov, kategórii a značiek s nastavením výstupných hodnôt jednotlivých položiek.
{
        "lang": "sk",
        "currency": "EUR",
        "query": "hladany vyraz",
        "results": {
                "products": {
                        "fields": [
                                "item_id",
                                "title",
                                "title_highlighted",
                                "url",
                                "price",
                                "sale_price",
                                "availibility",
                                "image_thumb",
                                "image_large"
                        ],
                        "results_max": 10,
                        "results_offset": 0,
                        "filters": {
                                "params": [],
                                "brands": [],
                                "categories_included": [
                                        {
                                                "category_id": "C123"
                                        },
                                        {
                                                "magrano_id": "123"
                                        }
                                ],
                                "categories_excluded": [
                                        {
                                                "magrano_id": "456"
                                        }
                                ],
                                "price": {
                                        "price_from": 0,
                                        "price_to": -1
                                }
                        },
                        "sort_by": "best_match"
                },
                "categories": {
                        "fields": [
                                "item_id",
                                "title",
                                "title_highlighted",
                                "url"
                        ],
                        "results_max": 5,
                        "results_offset": 0
                },
                "brands": {
                        "fields": [
                                "item_id",
                                "title",
                                "title_highlighted",
                                "url"
                        ],
                        "results_max": 5,
                        "results_offset": 0
                }
        }
}

PHP príklad

Príklad požiadavky v jazyku PHP.
<?php
$time = time();
$method = "POST";
$apiKey = "YOUR_API_KEY";
$clientSecret = "YOUR_CLIENT_SECRET";
$signature = hash_hmac("sha1", $time.$method.$apiKey, $clientSecret);

$data = array(
        "lang" => "sk",
        "currency" => "EUR",
        "query" => "hladany vyraz",
        "results" => array(
                "products" => array(
                        "fields" => array("item_id", "title"),
                        "results_max" => 5
                ),
                "categories" => array(
                        "fields" => array("item_id","title"),
                        "results_max" => 3
                ),
                "brands" => array(
                        "fields" => array("item_id","title"),
                        "results_max" => 3
                )
        )
);
$json_data = json_encode($data);

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://api.magrano.com/");
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json_data);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_BASIC);
curl_setopt($ch, CURLOPT_USERPWD, $apiKey.":".$signature);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
        "timestamp: ".gmdate("Ymd\THis\Z", $time),
]);

$response = curl_exec($ch);
$json_response = json_decode($response);
curl_close($ch);
?>

JSON odpoveď

Na základe parametrov z požiadavky vráti API odpoveď vo formáte JSON. Štruktúra odpovede je závislá od vyžadovaných skupín položiek.
Parameter
Popis
products
Skupina výsledkov vyhľadávania na základe požiadavky
results
array
Zoznam výsledkov vyhľadávania vo formáte asociatívneho poľa.

Možné kľúče parametrov každej položky na základe požiadavky.
item_id // ID položky z feedu. V prípade neexistujúcej hodnoty vracia NULL.
title // Názov položky
title_highlighted // Názov položky so zvýraznením vyhľadávania (CSS class="result_highlighted")
url // URL adresa položky
price // Bežná cena položky
sale_price // Zvýhodnená cena položky
availibility // Dostupnosť položky
image_thumb // Náhľad položky s nižším rozlíšením
image_large // Náhľad položky s vyšším rozlíšením
available_filters
array
Zoznam dostupných filtrov pre produkty. Sumárny zoznam bude uvedený ako jeden z parametrov pre celú požiadavku.
group
object
Objekt skupiny filtra
group_id
string
ID skupiny filtru
group_title
object
Názov skupiny filtru
options
array
Zoznam dostupných možností filtrovania
option
object
Objekt možnosti
key
string
Kľúč možnosti
value
string
Hodnota možnosti
total_count
int
Celkový počet výsledkov
categories
Skupina výsledkov vyhľadávania na základe požiadavky
results
array
Zoznam výsledkov vyhľadávania vo formáte asociatívneho poľa.

Možné kľúče parametrov každej položky na základe požiadavky.
item_id // ID položky z feedu. V prípade neexistujúcej hodnoty vracia NULL.
title // Názov položky
title_highlighted // Názov položky so zvýraznením vyhľadávania (CSS class="result_highlighted")
url // URL adresa položky
count
int
Počet vrátených výsledkov
total_count
int
Celkový počet výsledkov
brands
Skupina výsledkov vyhľadávania na základe požiadavky
results
array
Zoznam výsledkov vyhľadávania vo formáte asociatívneho poľa.

Možné kľúče parametrov každej položky na základe požiadavky.
item_id // ID položky z feedu. V prípade neexistujúcej hodnoty vracia NULL.
title // Názov položky
title_highlighted // Názov položky so zvýraznením vyhľadávania (CSS class="result_highlighted")
url // URL adresa položky
count
int
Počet vrátených výsledkov
total_count
int
Celkový počet výsledkov
{
        "products": {
                "results": [
                        {
                                "item_id": "1",
                                "title": "Product 1"
                        },
                        {
                                "item_id": "2",
                                "title": "Product 2"
                        },
                        {
                                "item_id": "3",
                                "title": "Product 3"
                        },
                        {
                                "item_id": "4",
                                "title": "Product 4"
                        },
                        {
                                "item_id": "5",
                                "title": "Product 5"
                        }
                ],
                "count": "5",
                "total_count": "50",
                "available_filters": [
                        {
                                "group_id": "1",
                                "group_title": "Filter 1",
                                "options": [
                                        {
                                                "key": "opt1",
                                                "value": "Option 1"
                                        },
                                        {
                                                "key": "opt2",
                                                "value": "Option 2"
                                        }
                                ]
                        },
                        {
                                "group_id": "2",
                                "group_title": "Filter 2",
                                "options": [
                                        {
                                                "key": "opt3",
                                                "value": "Option 3"
                                        },
                                        {
                                                "key": "opt4",
                                                "value": "Option 4"
                                        }
                                ]
                        }
                ]
        },
        "categories": {
                "results": [
                        {
                                "item_id": "1",
                                "title": "Category 1"
                        },
                        {
                                "item_id": "2",
                                "title": "Category 2"
                        },
                        {
                                "item_id": "3",
                                "title": "Category 3"
                        }
                ],
                "count": "3",
                "total_count": "5"
        },
        "brands": {
                "results": [
                        {
                                "item_id": "1",
                                "title": "Brand 1"
                        },
                        {
                                "item_id": "2",
                                "title": "Brand 2"
                        },
                        {
                                "item_id": "3",
                                "title": "Brand 3"
                        }
                ],
                "count": "3",
                "total_count": "3"
        }
}

Administrácia položiek

Časť API rozhrania slúžiaca na spravovanie položiek, ktoré majú byť vyhľadatelné. Magrano umožňuje ukladať produkty, kategórie, značky a články.
Pre každý typ položky sú k dispozícii viaceré parametre podľa následujúcich špecifikácii.

Produkty

Produkty je možné vytvárať a upravovať prostredníctvom následujúcej špecifikácii rozhrania. Pre pridávania a úpravu produktov, je povinnou položkou len ID produktu a aktualizované budú všetky hodnoty, ktoré budú definované v požiadavke.

Vymazanie produktov je možné na základe požadovaných ID produktov.

Pridanie / úprava produktov

Parameter
Popis
request
string - povinné
Pevná hodnota: "products"
products
array - povinné
Zoznam produktov z eshopu
product
object - povinné
Objekt produktu, ktorý obsahuje následovné vlastnosti
item_id
string - povinné
ID produktu z eshopu
item_group_id
string - Nepovinné
Odporučené
ID skupiny produktu z eshopu
title
string - Nepovinné
Odporučené
Názov produktu
group_title
string - Nepovinné
Odporučené
Názov skupiny produktov (bez názvov vlastností)
url
string - Nepovinné
Odporučené
URL adresa produktu
img
string - Nepovinné
Odporučené
URL adresa náhľadu produktu
brand
string - Nepovinné
Odporučené
Značka produktu
description
text - Nepovinné
Neformátovaný popis produktu
category
array - Nepovinné
Odporučené
Zoznam ID kategórií produktu
prices
array - Nepovinné
Zoznam cien produktu
price
object - Nepovinné
Konkrétna cenová hľadina.
price
decimal - povinné
Základná cena produktu
sale_price
decimal - Nepovinné
Odporučené
Zľavnená cena produktu
margin
decimal - Nepovinné
Odporučené
Percentuálna hodnota marže produktu pre výpočet zisku
currency
string - Nepovinné
Odporučené
Mena vo formáte ISO 4217
Príklad: EUR, CZK, USD, GBP ...
V prípade nepoužitia tejto vlastnosti sa použije predvolená hodnota zo systému.
level
string - Nepovinné
Odporučené
Kľúč cenovej hladiny Slúži na uloženie rôznych cenových hladín pre daný produkt.
Týmto kľúčom bude potrebné vyžiadať cenovú hladinu v eshope.
V prípade nepoužitia tejto hodnoty bude táto cenová hladina považovaná za predvolenú.
Príklad: b2b, b2c, reg...
sales
int - Nepovinné
Odporučené
Počet objednávok produktu za určité obdobie
stock
int - Nepovinné
Odporučené
Počet kusov produktu na sklade
delivery_date
string - Nepovinné
Počet dní potrebných na doručenie produktu
delivery_label
string - Nepovinné
Odporučené
Popisok k termínu dodania
Príklad: Na sklade, Nedostupné, U dodávateľa...
priority
int - Nepovinné
Priorita pre uprednostnenie produktov vo vyhľadávaní. Čím vyššie číslo, tým skôr sa produkt zobrazí.
params
array - Nepovinné
Odporučené
Zoznam parametrov produktu, ktoré upresňujú vyhľadávanie a umožňujú rozšírené filtrovanie.
param
object - Nepovinné
Jednotlivý parameter s následujúcimi vlastnosťami.
name
string - povinné
Názov parametra
value
string - povinné
Hodnota parametra
param_id
string - Nepovinné
Odporučené
ID parametra z eshopu
labels
array - Nepovinné
Zoznam štítkov pri produktoch
label
object - Nepovinné
Konkrétny štítok s následujúcimi parametrami
label_id
string - Nepovinné
Odporučené
ID štítku z eshopu
name
string - povinné
Nadpis štítku
priority
int - Nepovinné
Priorita štítku. Čím vyššia priorita, tým vyššie sa štítok zobrazí. Štítky s rovnakou prioritou sa zoraďujú abecedne.
css_class
string - Nepovinné
Odporučené
CSS class štítku
colors
object - Nepovinné
Odporučené
Farby štítku
background
string - Nepovinné
Farba pozadia
text
string - Nepovinné
Farba textu
border
string - Nepovinné
Farba orámovania
tags
array - Nepovinné
Odporučené
Zoznam dodatočných štítkov produktu, podľa ktorých bude možné vyhľadávanie. Napríklad kód produktu, EAN...
tag
object - Nepovinné
Objekt tagu s následujúcimi vlastnosťami.
name
string - povinné
Názov štítku
value
string - povinné
Hodnota štítku
related
array - Nepovinné
Zoznam previazaných produktov
Ukážka vytvorenia produktu
{
        "request": "products",
        "products": [
                {
                        "item_id": "123",
                        "title": "N\u00e1zov produktu 123",
                        "url": "https:\/\/www.adresavashoobchodu.com\/product123",
                        "img": "https:\/\/www.adresavashoobchodu.com\/product123_image.png",
                        "brand": "B123",
                        "category": [
                                "C123"
                        ],
                        "prices": [
                                {
                                        "price": "23.99",
                                        "sale_price": "19.99",
                                        "margin": "30"
                                }
                        ],
                        "sales": "2",
                        "params": [
                                {
                                        "name": "Farba",
                                        "value": "\u017dlt\u00e1"
                                },
                                {
                                        "name": "Ve\u013ekos\u0165",
                                        "value": "XL"
                                }
                        ],
                        "related": [
                                "456"
                        ],
                        "stock": "3"
                },
                {
                        "item_id": "456",
                        "title": "N\u00e1zov produktu 456",
                        "url": "https:\/\/www.adresavashoobchodu.com\/product456",
                        "img": "https:\/\/www.adresavashoobchodu.com\/product456_image.png",
                        "brand": "B123",
                        "category": [
                                "C456"
                        ],
                        "prices": [
                                {
                                        "price": "33.99",
                                        "sale_price": "27.99",
                                        "margin": "30"
                                }
                        ],
                        "sales": "4",
                        "params": [
                                {
                                        "name": "Farba",
                                        "value": "\u017dlt\u00e1"
                                },
                                {
                                        "name": "Ve\u013ekos\u0165",
                                        "value": "XL"
                                }
                        ],
                        "related": [
                                "123"
                        ],
                        "stock": "0"
                }
        ]
}
Ukážka vytvorenia produktu s cenovými hladinami a menami
{
        "request": "products",
        "products": [
                {
                        "item_id": "123",
                        "title": "N\u00e1zov produktu 123",
                        "url": "https:\/\/www.adresavashoobchodu.com\/product123",
                        "img": "https:\/\/www.adresavashoobchodu.com\/product123_image.png",
                        "brand": "B123",
                        "category": [
                                "C123"
                        ],
                        "prices": [
                                {
                                        "price": "23.99",
                                        "sale_price": "19.99",
                                        "margin": "30",
                                        "currency": "EUR",
                                        "level": "b2b"
                                },
                                {
                                        "price": "18.99",
                                        "sale_price": "0",
                                        "margin": "20",
                                        "currency": "EUR",
                                        "level": "b2c"
                                },
                                {
                                        "price": "599",
                                        "sale_price": "499",
                                        "margin": "30",
                                        "currency": "CZK",
                                        "level": "b2b"
                                },
                                {
                                        "price": "475",
                                        "sale_price": "0",
                                        "margin": "20",
                                        "currency": "CZK",
                                        "level": "b2c"
                                }
                        ],
                        "sales": "2",
                        "params": [
                                {
                                        "name": "Farba",
                                        "value": "\u017dlt\u00e1"
                                },
                                {
                                        "name": "Ve\u013ekos\u0165",
                                        "value": "XL"
                                }
                        ],
                        "related": [
                                "456"
                        ],
                        "stock": "3"
                }
        ]
}
Ukážka aktualizácie skladovej dostupnosti
{
        "request": "products",
        "products": [
                {
                        "item_id": "123",
                        "stock": "5"
                },
                {
                        "item_id": "456",
                        "stock": "2"
                },
                {
                        "item_id": "789",
                        "stock": "0"
                }
        ]
}

Zmazanie produktov


Vymazanie vybraných produktov
Parameter
Popis
request
string - povinné
Pevná hodnota: "products_delete"
item_id
array - povinné
Zoznam ID položiek z eshopu, ktoré sa majú vymazať
Ukážka zmazania produktu
{
        "request": "products_delete",
        "item_id": [
                "123",
                "456",
                "789"
        ]
}
Vymazanie všetkých produktov okrem vybraných
Parameter
Popis
request
string - povinné
Pevná hodnota: "products_delete"
exc_item_id
array - povinné
Zoznam ID položiek z eshopu, ktoré sa nemajú vymazať
Ukážka zmazania produktu
{
        "request": "products_delete",
        "exc_item_id": [
                "123"
        ]
}

Kategórie

API rozhranie slúžiace na vytváranie, úpravu a mazanie kategórii eshopu.
Povinnou položkou v každej požiadavke je ID kategórie z eshopu. Aktualizované budú hodnoty použitých vlastností pre každú uvedenú kategóriu.
V prípade mazania kategórii budú vymazané aj všetky podradené kategórie.

Pridanie / úprava kategórii

Parameter
Popis
request
string - povinné
Pevná hodnota: "categories"
categories
array - povinné
Zoznam kategórií z eshopu
category
object - povinné
Objekt kategórie, ktorý obsahuje následovné vlastnosti
item_id
string - povinné
ID kategórie z eshopu
parent_id
array - Nepovinné
ID nadradenej kategórie z eshopu
title
string - Nepovinné
Názov kategórie
title_optimized
string - Nepovinné
Stručný a optimalizovaný názov kategórie, ktorý sa zobrazujr užívateľom bez celej hierarchickej štruktúry kategórie. Napr. Namiesto "Obuv > Dámska > Čizmy" sa zobrazí len "Dámske čižmy"
url
string - Nepovinné
URL adresa kategórie
Ukážka vytvorenia kategórie
{
        "request": "categories",
        "categories": [
                {
                        "item_id": "C123",
                        "title": "N\u00e1zov kateg\u00f3rie 123",
                        "url": "https:\/\/www.adresavashoobchodu.com\/category123"
                },
                {
                        "item_id": "C456",
                        "parent_id": "C123",
                        "title": "N\u00e1zov kateg\u00f3rie 456",
                        "url": "https:\/\/www.adresavashoobchodu.com\/category456"
                }
        ]
}

Zmazanie kategórií

Parameter
Popis
request
string - povinné
Pevná hodnota: "categories_delete"
item_id
array - povinné
Zoznam ID kategórii z eshopu
Ukážka zmazania kategórie
{
        "request": "categories_delete",
        "item_id": [
                "C123",
                "C456"
        ]
}

Značky

API rozhranie slúžiace na vytváranie, úpravu a mazanie značiek eshopu.
Povinnou položkou v každej požiadavke je ID značky z eshopu. Aktualizované budú hodnoty použitých vlastností pre každú uvedenú značku.

Pridanie / úprava značiek

Parameter
Popis
request
string - povinné
Pevná hodnota: "brands"
brands
array - povinné
Zoznam značiek z eshopu
brand
object - povinné
Objekt značky, ktorý obsahuje následovné vlastnosti
item_id
string - povinné
ID značky z ehopu
title
string - Nepovinné
Názov značky
url
string - Nepovinné
URL adresa značky
Ukážka vytvorenia značky
{
        "request": "brands",
        "brands": [
                {
                        "item_id": "B123",
                        "title": "N\u00e1zov zna\u010dky 123",
                        "url": "https:\/\/www.adresavashoobchodu.com\/brand123"
                },
                {
                        "item_id": "B456",
                        "title": "N\u00e1zov zna\u010dky 456",
                        "url": "https:\/\/www.adresavashoobchodu.com\/brand456"
                }
        ]
}

Zmazanie značiek

Parameter
Popis
request
string - povinné
Pevná hodnota: "brands_delete"
item_id
array - povinné
Zoznam ID značiek z eshopu
Ukážka zmazania značky
{
        "request": "brands_delete",
        "item_id": [
                "B123",
                "B456"
        ]
}

Články

API rozhranie slúžiace na vytváranie, úpravu a mazanie článkov zo stránky.
Povinnou položkou v každej požiadavke je ID článku zo stránky. Aktualizované budú hodnoty použitých vlastností pre každý uvedenýú článok.

Pridanie / úprava článkov

Parameter
Popis
request
string - povinné
Pevná hodnota: "articles"
articles
array - povinné
Zoznam článkov z eshopu
article
object - povinné
Objekt článku, ktorý obsahuje následovné vlastnosti
item_id
string - povinné
ID článku zo stránky
title
string - Nepovinné
Nadpis článku
text
text - Nepovinné
Neformátovaný text článku
timestamp
string - Nepovinné
Dátum a čas článku
Formát: 2026-03-19T01:46:40     YYYY-MM-DDThh:mm:ss
url
string - Nepovinné
URL adresa článku
img
string - Nepovinné
URL adresa obrázku k článku
Ukážka vytvorenia článku
{
        "request": "articles",
        "articles": [
                {
                        "item_id": "A123",
                        "title": "Nadpis \u010dl\u00e1nku 123",
                        "text": "Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Fusce id velit ut tortor pretium viverra suspendisse potenti nullam.",
                        "timestamp": "2026-03-19T01:46:40",
                        "url": "https:\/\/www.adresavashoobchodu.com\/article123",
                        "img": "https:\/\/www.adresavashoobchodu.com\/article123_thumb.jpg"
                },
                {
                        "item_id": "A456",
                        "title": "Nadpis \u010dl\u00e1nku 456",
                        "text": "Volutpat consequat mauris nunc congue nisi vitae suscipit tellus. Sed risus pretium quam vulputate. Mattis nunc sed blandit libero volutpat sed cras ornare arcu.",
                        "timestamp": "2026-03-18T01:46:40",
                        "url": "https:\/\/www.adresavashoobchodu.com\/article456",
                        "img": "https:\/\/www.adresavashoobchodu.com\/article456_thumb.jpg"
                }
        ]
}

Zmazanie článkov

Parameter
Popis
request
string - povinné
Pevná hodnota: "articles_delete"
item_id
array - povinné
Zoznam ID článkov zo stránky
Ukážka zmazania článku
{
        "request": "articles_delete",
        "item_id": [
                "A123",
                "A456"
        ]
}

XML feedy

Vloženie feedu

JSON požiadavka

Parameter
Popis
request
string - povinné
Pevná hodnota: "feed"
url
string - povinné
URL adresa feedu
type
string - povinné
Typ feedu
(products / categories / brands)
format
string - Nepovinné
Formát feedu
(magrano)
lang
string - Nepovinné
Jazyk položiek vo feede. Pokiaľ sa neuvedie, bude použitá predvolená hodnota.
(sk, cz, en, de, ro, bg, hu, hr, pl, si, fr, ru, it...)
currency
string - Nepovinné
Mena cien položiek vo feede. Pokiaľ sa neuvedie, bude použitá predvolená hodnota.
(EUR, CZK, USD, GBP, BGN, PLN, HUF, RON...)
{
        "request": "feed",
        "url": "https:\/\/www.magrano.com\/sample_products.xml",
        "type": "products",
        "format": "magrano",
        "lang": "sk",
        "currency": "EUR"
}

JSON odpoveď

{
        "success": "true"
}

Aktualizácia údajov z feedov

JSON požiadavka

{
        "request": "feed_update"
}

JSON odpoveď

{
        "success": "true"
}

Zdrojové tagy

JSON požiadavka

Parameter
Popis
request
string - povinné
Pevná hodnota: "tags"
{
        "request": "tags"
}

JSON odpoveď

{
        "stylesheet_tag": "magrano.css",
        "javascript_tag": "magrano.js",
        "initialize_tag": "$(document).ready(function(){ searchBoxInit({ apiKey: 'YOUR_API_KEY', inputSelector: 'search input jQuery selector', lang: 'sk'}); })",
        "initialize_options": "{apiKey: 'YOUR_API_KEY', inputSelector: 'search input jQuery selector', lang: 'sk'},
}

Udalosti našeptávača

Slúži na nastavenie udalosti pri zobrazení, skrytí alebo potvrdení vyhľadávania.
Vkladané môžu byť Javascriptové procedúry a funkcie zo stránky.

JSON požiadavka

Parameter
Popis
request
string - povinné
Pevná hodnota: "events"
events
array - Nepovinné
Zoznam udalostí našetpávača
on_show
string - Nepovinné
Udalosť pri otvorení našeptávača
on_hide
string - Nepovinné
Udalosť pri zatvorení našeptávača
on_submit
string - Nepovinné
Udalosť pre "Viac výsledkov".
Pokiaľ sa nechá prázdna hodnota, použije sa predvolená udalosť pre formulár s hľadaním.
{
        "request": "events",
        "events": {
                "on_show": "showSearchOverlay();",
                "on_hide": "hideSearchOverlay();"
        }
}

JSON odpoveď

{
        "success": "true",
        "events": {
                "on_show": "showSearchOverlay();",
                "on_hide": "hideSearchOverlay();"
        }
}

Chybové hlásenia

V prípade chyby API požiadavky je vrátená informácia o chybe v podobe odpovede vo formáte JSON.
Chyba
Popis
400: Bad request
Chyba požiadavky
Požiadavka má nesprávny formát.
401: Authentification failed
Chyba overenia
Skontrolujte správnosť generovania autorizačného podpisu.