WEXBO API

ÚVOD#

Táto dokumentácia poskytuje informácie o API rozhraní pre vývojárov, prostredníctvom ktorého je možné získať prístup do jednotlivých účtov (profilov) vedených v systéme WEXBO a spravovať tak niektoré sekcie a položky (získavať, pridávať, upravovať alebo mazať) v reálnom čase. Prepojiť je tak možné účtovný systém, ERP či CRM systém, prepravnú spoločnosť, analytické a marketingové nástroje, atď. Naše rozhranie API funguje ako webová služba REST, ktorá je založená na jednoduchej komunikácii s protokolom HTTP, pričom na výmenu dát využíva dátový formát JSON. Dokumentácia popisuje aktuálnu verziu označovanú ako v1.

Podrobné informácie o systéme WEXBO nájdete na stránkach wexbo.com.

Autorizácia#

Každé volanie požiadavky na REST API musí byť autorizované. Vo všetkých volaniach tak musí byť prítomná HTTP hlavička Authorization obsahujúca API token, ktorý reprezentuje prístup ku konkrétnemu účtu.

Authorization: Bearer {API_TOKEN}požiadavkahttp

API token získate po prihlásení sa do administrácie vášho účtu napríklad cez https://admin.wexbo.com v sekcii DOPLNKY / PLUGINY v plugine s názvom API.

Návratový stavový kód HTTP pre volanie, pri ktorých nebol používateľ prihlásený, je 401 Unauthorized.

Požiadavka#

HTTP metódy#

Podporované sú bežné metódy protokolu HTTP, ktoré sa zvyčajne používajú medzi webovými službami REST. Každá metóda protokolu HTTP má inú funkciu, pričom spôsob výkladu je popísaný v nasledujúcom zozname:

V prípade potreby, pre zmenu HTTP metódy je možné použiť aj HTTP hlavičku X-HTTP-Method-Override. Pôvodná požiadavka tak môže mať napríklad HTTP metódu GET, pričom ak bude v tejto hlavičke požiadavky použitá hodnota DELETE, požiadavka bude spracovaná práve ako HTTP metóda DELETE.

HTTP hlavičky#

Požiadavka na volanie musí obsahovať HTTP hlavičku autorizácie s tokenom a HTTP hlavičku s verziou API. Aktuálna verzia API je v1.

Authorization: Bearer {API_TOKEN}
Content-Type: application/vnd.wexbo.v1požiadavkahttp

URL adresa#

Základná URL adresa pre požiadavky API je pre všetky profily rovnaká, a to:

https://api.wexbo.com/

Vyžadované je šifrované spojenie prostredníctvom protokolu HTTPS, keďže v opačnom prípade, pri využití nešifrovaného spojenia HTTP požiadavka nebude spracovaná.

Celková požiadavka sa skladá z HTTP hlavičiek, konkrétnej metódy, endpointu, parametrov popísaných nižšie, prípadne aj tela požiadavky vo formáte JSON.

https://api.wexbo.com/{ENDPOINT}/{NULL|ID|COUNT}?{URL_PARAMETERS}požiadavkaget

Koncový bod#

Zároveň URL adresa musí obsahovať aj tzv. endpoint (koncový bod). Konečná URL adresa pre volanie požiadavky pre zobrazenie zoznamu produktov bude vyzerať nasledovne:

https://api.wexbo.com/productspožiadavkaget

Zozname všetkých dostupných endpointov nájdete nižšie v dokumentácii v sekcii Odkazy, kde sú detailne popísané, keďže každý endpoint má vlastné parametre, dostupné metódy a rôznu štruktúru pre dáta požiadavky či samotné dáta odpovede.

Identifikátor#

V prípade, že chcete zobraziť konkrétny detail jedného záznamu (metóda GET), alebo aktualizovať konkrétny záznam (metóda PUT), prípadne daný záznam zmazať (metóda DELETE), je nutné hneď za endpointom pridať {ID} (identifikátor záznamu). Napríklad pre zobrazenie detailu produktu s ID 1000001 je to URL adresa požiadavky:

https://api.wexbo.com/products/1000001požiadavkaget

URL parametre#

Do URL požiadavky je možné pridať niektoré všeobecné nepovinné URL parametre, ktorých zoznam nájdete v tabuľke nižšie. Bližšie informácie niektorých všeobecných URL parametrov sú popísané nižšie v dokumentácii.

https://api.wexbo.com/products?fields=id&options=pagination,links&sort=id&direction=desc&page=1&offset=0&limit=25požiadavkaget

Polia#

Každý endpoint obsahuje predvolené atribúty alebo či inak polia, ktoré sú súčasťou JSON tela odpovede požiadavky a sú už zahrnuté v parametri data. V prípade zadania ďalších hodnôt do URL parametra fields je možné v odpovedi v parametri data zobraziť ďalšie atribúty, ktoré konkrétny endpoint podporuje. Názvy atribútov sú v tzv. snakeCase formáte (slová bez diakritiky, zapísané malými písmenami, oddelené podtržníkom). Príklad zadania požiadavky pre zobrazenie požadovaných atribútov:

https://api.wexbo.com/products?fields=id,code,namepožiadavkaget

{
···
"data": [
{
"id": 1000001,
"code": "product_code",
"name": "Product name",
},
···
],
···
}odpoveďjson

Všetky podporované atribúty pre URL parameter fields sú popísané v konkrétnom endpointe.

Doplnkové možnosti#

V odpovedi je možné zobraziť aj ďalšie doplnkové možnosti a to prostredníctvom URL parametra options, ktorý je možné zadávať ako typ list alebo ako typ array. Dané typy parametra však nie je možné kombinovať.

V prípade typu list je možné do parametra zadať viacero hodnôt oddelených čiarkou.

https://api.wexbo.com/products?options=result,count,pagination,linkspožiadavkaget

V prípade typu array je možné zadať parameter do URL adresy viac krát.

https://api.wexbo.com/products?&options[]=result&options[]=count&options[]=pagination&options[]=linkspožiadavkaget

Filtrovanie#

V prípade požiadavky na zoznam záznamov (metóda GET bez {ID}) je možné si prostredníctvom rôznych filtrov jednotlivých endpointov zobraziť len záznamy na základe zvolených parametrov. URL parameter filter môže byť zadaný buď v jednoduchom čitateľnom zápise typu list alebo naopak typu object pre jednoduchšie parasovanie pomocou programu. Dané zápisy však nie je možné kombinovať.

Zoznam filtrov

V prípade typu list zadajte do URL parametra filter hodnoty oddelené čiarkou, pričom každá z hodnôt musí obsahovať identifikátor filtrovaného parametra a filtrovanú hodnotu oddelené dvojbodkou.

https://api.wexbo.com/products?filter=active:1,date:2000-12-31požiadavkaget

Samostatné filtre

V prípade typu object je možné parameter filter zadať do URL adresy opakovane s rôznym identifikátorom filtrovaného parametra, ktorá bude obsahovať samotnú filtrovanú hodnotu.

https://api.wexbo.com/products?filter[active]=1&filter[date]=2000-12-31požiadavkaget

Hodnota filtra

Hodnotu filtra je nutné zadať podľa typu, ktorý ma daný filter určenú. Podrobné informácie ohľadom správneho formátu jednotlivých typov sú popísané v odstavci Dátové typy.

https://api.wexbo.com/products?filter=active:1požiadavkaget

https://api.wexbo.com/products?filter[active]=truepožiadavkaget

Zoznam hodnôt filtra

Takmer všetky filtre okrem typu boolean môžu obsahovať viacero hodnôt, ktoré oddelíte znakom bodkočiarky ;. V tomto prípade sa zobrazia záznamy, ktoré vyhovujú aspoň jednej z hodnôt, teda pre zadané hodnoty sa použije logická spojka OR.

https://api.wexbo.com/products?filter=id:1000001;1000002;1000003požiadavkaget

https://api.wexbo.com/products?filter[id]=1000001;1000002;1000003požiadavkaget

Rozsah hodnôt filtra

Filtre typu integer, float, date, datetime môžu obsahovať rozsah hodnôt, ktoré oddelíte znakom pomlčky -. V tomto prípade sa zobrazia záznamy, ktoré vyhovujú zadanému rozsahu hodnôt vrátane zadaných hodnôt.

https://api.wexbo.com/products?filter=id:1000001-1000099požiadavkaget

https://api.wexbo.com/products?filter[id]=1000001-1000099požiadavkaget

https://api.wexbo.com/products?filter[date]=2000-01-01-2000-12-31požiadavkaget

Stránkovanie#

V prípade požiadavky na zoznam záznamov (metóda GET bez {ID}) sa zobrazuje len určitý počet záznamov, pričom sa využíva tzv. stránkovanie. Predvolene je počet zobrazujúcich záznamov na stranu nastavený na hodnotu 25.

Nastaviť je možné aj inú hodnotu a to prostredníctvom URL parametra limit, do ktorého je možné zadať hodnotu od 1 do 250. Aktuálne nastavené stránkovanie požiadavky sa vždy zobrazí v odpovedi stránkovania v parametri paging.

https://api.wexbo.com/products?limit=50požiadavkaget

Predvolene sa zobrazí prvá stránka so zoznamom záznamov, keďže URL parameter page má predvolenú hodnotu 1. Pridaním daného parametra do URL adresy požiadavky je možné zobraziť zoznam záznamov ďalších stránok.

https://api.wexbo.com/products?page=2požiadavkaget

Namiesto parametra page je možné použiť URL parameter offset, kedy sa majú zobraziť záznamy od nastavenej hodnoty. Predvolene má daný parameter hodnotu 0 (od začiatku). Ak je zadaný súčasne aj parameter page, tak parameter offset sa v požiadavke neuplatní, teda pre stránkovanie je možné použiť len jeden z nich. Nastaviť je možné napríklad zobrazenie záznamov od 50-teho záznamu 25 záznamov na stranu, teda záznamy v poradí 50 až 75:

https://api.wexbo.com/products?limit=25&offset=50požiadavkaget

Súčasťou odpovede takýchto požiadaviek sú HTTP hlavičky X-Pagination-... obsahujúca informácie o stránkovaní.

...
X-Pagination-Pages: 10
X-Pagination-Page: 1
X-Pagination-Offset: 0
X-Pagination-Count: 25
X-Pagination-Total: 250
X-Pagination-Paging: 25
...odpoveďhttp

Ak chcete informácie o stránkovaní zobraziť priamo v JSON tele odpovede, je nutné v požiadavke využiť parameter options obsahujúcu hodnotu pagination.

https://api.wexbo.com/products?options=paginationpožiadavkaget

{
···
"pagination": {
"pages": 10,
"page": 1,
"offset": 0,
"count": 25,
"total": 250,
"paging": 25,
"status": "continue"
},
···
}odpoveďjson

Zoradenie#

V prípade požiadavky na zoznam záznamov (metóda GET bez {ID}) je možné si nastaviť radenie zobrazovaných záznamov. Požiť je možné buď jednoduché radenie prostredníctvom jedného parametra využitím URL parametrov sort typu list a parametra direction alebo je možné použiť zložitejšie radenie prostredníctvom viacerých parametrov využitím URL parametra sort a to buď typu list alebo object. Dané URL parametre či typy však nie je možné kombinovať.

Príklad jednoduchého radenia s využitím URL parametrov sort a direction. Parameter direction je využiť aj samostatne.

https://api.wexbo.com/products?sort=id&direction=ascpožiadavkaget

Príklad kombinovaného radenia len s využitím URL parametra sort typu list.

https://api.wexbo.com/products?sort=id:ascpožiadavkaget

https://api.wexbo.com/products?sort=id:asc,name:descpožiadavkaget

Príklad kombinovaného radenia len s využitím URL parametra sort typu object.

https://api.wexbo.com/products?sort[id]=ascpožiadavkaget

https://api.wexbo.com/products?sort[id]=asc&sort[name]=descpožiadavkaget

JSON telo#

V prípade požiadaviek s metódou PUT alebo POST musí požiadavka obsahovať aj telo s obsahom požiadavky. Naopak požiadavky s metódami GET a DELETE telo neobsahujú. Telo požiadavky musí byť v štruktúrovanom formáte JSON kódované prostredníctvom znakovej sady UTF-8. Príklady s kompletným výpisom tela aj popisom jednotlivých atribútov pre konkrétne endpointy nájdete nižšie po rozkliknutí požadovaného endpointu.

https://api.wexbo.com/productspožiadavkapost

{
"name": "Tenisová raketa",
"active": true,
"price": 50.99,
···
}požiadavkajson

Dátové typy#

Odpoveď#

Súčasťou každej odpovede servera na požiadavku klienta je telo vo formáte JSON s parametrami result, data, errors.

Stav#

Úspešne spracovaná požiadavka obsahuje v JSON tele odpovedi, hneď na začiatku parameter result s hodnotou ok. Naopak chybne spracovaná požiadavka obsahuje parameter result s hodnotou error.

{
"result": "ok",
···
}odpoveďjson

Dáta#

Základom odpovede na požiadavku sú samotné dáta, ktoré sú obsiahnuté v JSON tele odpovedi v parametri data. V prípade požiadavky s metódou DELETE (zmazanie záznamu) má daný parameter prázdnu hodnotu. V opačnom prípade parameter obsahuje predvolené atribúty, prípadne aj atribúty zahrnuté v URL parametry fields.

{
···
"data": {
"id": 1,
···
},
···
}odpoveďjson

Stránkovanie#

Súčasťou odpovede požiadaviek sú HTTP hlavičky X-Pagination-... obsahujúca informácie o stránkovaní. Ak chcete informácie o stránkovaní zobraziť priamo v JSON tele odpovede, je nutné v požiadavke využiť parameter options obsahujúcu hodnotu pagination. Podrobné informácie aj s príkladmi a popisom jednotlivých možností stránkovania nájdete vyššie v odstavci Požiadavka / Stránkovanie.

Odkazy#

Odpoveď obsahuje aj HTTP hlavičku Link obsahujúcu automaticky generované odkazy pre jednoduchšiu možnosť vykonania ďalšej akcie. V prípade stránkovania sú to napríklad odkazy na požiadavky pre zobrazenie ďalšej strany záznamov.

Link: <https://api.wexbo.com/products?page=2&options=links>; rel="self", <https://api.wexbo.com/products?page=1&options=links>; rel="first", <https://api.wexbo.com/products?page=1&options=links>; rel="prev", <https://api.wexbo.com/products?page=3&options=links>; rel="next", <https://api.wexbo.com/products?page=9&options=links>; rel="last"odpoveďhttp

Ak chcete informácie o odkazoch zobraziť priamo v JSON tele odpovede, je nutné v požiadavke využiť parameter options obsahujúcu hodnotu links.

https://api.wexbo.com/products?page=2&options=linkspožiadavkaget

{
···
"links": {
"self": "https://api.wexbo.com/products?page=2&options=links",
"first": "https://api.wexbo.com/products?page=1&options=links",
"prev": "https://api.wexbo.com/products?page=1&options=links",
"next": "https://api.wexbo.com/products?page=3&options=links",
"last": "https://api.wexbo.com/products?page=9&options=links"
},
···
}odpoveďjson

Chyby#

Zoznam konkrétnych informácií týkajúcich sa chýb požiadavky nájdete vždy v JSON tele odpovede na konci v parametri errors. V prípade úspešného spracovania požiadavky by mal byť zoznam parametra prázdny (prázdne array pole). Napriek tomu sa v danom zozname môžu nachádzať aj varovania s kódom 100, ktoré nie sú závažnými chybami, teda nebránia spracovaniu požiadavky, ale len upozorňujú na prípadné nezrovnalosti v požiadavke.

{
···
"errors": [
{
"code": 404,
"msg": "Information about error",
"error": "...",
"field": "..."
},
{
"code": 100,
"msg": "Just some warning",
"error": "...",
"field": "..."
}
]
}odpoveďjson

Kódy odpovedí#

Súčasťou každej odpovede servera na požiadavku klienta je kód o stave odpovedi v hlavičke (HTTP response status codes). Väčšina odpovedí zvyčajne obsahuje nižšie uvedené kódy odpovedí.

Úspešné spracovanie#

Chyba pri spracovaní#

Obmedzenia#

Aby nedochádzalo k zbytočnému preťažovaniu API serveru zahlcovaním požiadaviek, či už úmyselne alebo neúmyselne z dôvodu nesprávneho návrhu napojenia, má API nastavené určité predvolené limity. Vyžaduje sa tak dôraz na správny návrh a optimalizáciu interakcie s API (webhooks, pagination, filter, fields, atď.), aby bol k prístup k API po celú dobu stabilný a dostupný pre všetkých.

Prihlásenia#

Pokusy pre prihlásenie sú limitované počtom max. 5 neúspešných pokusov, pričom Ďalšie požiadavky nebudú spracované a na požiadavky bude odpovedané HTTP kódom 423 Locked.

Veľkosť požiadavky#

Požiadavky s HTTP metódou PUT, teda aktualizácia záznamov, môžu obsahovať maximálne 100 parametrov s hodnotami, zároveň celé telo požiadavky pri HTTP metódach PUT a POST nesmie presiahnuť veľkosť 1 MB (hlavne v prípade vkladania obrázkov). V prípade, že je tento limit prekročený, požiadavka sa nevykoná a na požiadavku bude odpovedané s HTTP kódom 413 Payload too large.

Počet požiadaviek#

V rámci krátkeho času je možné odosielať len určitý počet požiadaviek, pričom po prekročení limitu bude na požiadavky odpovedané HTTP kódom 429 Too Many Requests.

Systém má aktuálne pevne nastavený hodinový, a taktiež denný limit na počet požiadaviek, ktorý je pri bežnom a správnom používaní API výrazne dostačujúci.

Jedným z limitov je aj počet súbežných požiadaviek v jednej sekunde, ktorý je aktuálne stanovený na maximálne 5 požiadaviek za sekundu pre jedno pripojenie (token). Odporúčame si tak pri väčšom počte požiadaviek nastaviť aj krátky čas oneskorenia, alebo budete musieť požiadavky odoslať znova.

Kredit#

Aj keď vedenie API pre používateľov nie je spoplatnené nejakým pevným mesačným poplatkom, spoplatnené sú samotné požiadavky, resp. záznamy v požiadavkách. Dynamicky sa využíva dostupný kredit profilu, pričom za každý záznam z požiadavky je profilu strhnutý 1 kredit. Pri nedostatku kreditu sa požiadavka nevykoná a na požiadavku bude odpovedané s HTTP kódom 402 Payment Required.

Kredit je možné si v profile dobiť cez administráciu https://admin.wexbo.com v sekcii NASTAVENIA / WEB v položke Dostupný kredit po kliknutí na tlačítko DOBIŤ KREDIT.

Partnerské implementácie, ktoré sú prepojené s natívnym pluginom systému nie sú spoplatnené prostredníctvom kreditu. Teda takýto plugin Vám nebude stŕhať žiadny kredit v profile.

Príklady#

Zobrazenie produktov#

https://api.wexbo.com/products?fields=id,code,name,foo&options=pagination,links&sort=id&direction=asc&page=1&offset=0&limit=3požiadavkaget

Authorization: Bearer {API_TOKEN}
Content-Type: application/vnd.wexbo.v1požiadavkahttp

200 OK
Content-Type: application/vnd.wexbo.v1+json; charset=utf-8odpoveďhttp

{
"result": "ok",
"data": [
{
"id": 1000001,
"code": "tenrak01",
"name": "Tenisová raketa",
},
{
"id": 1000002,
"code": "tankt72m1",
"name": "Tank T-72 M1",
},
{
"id": 1000003,
"code": "office30",
"name": "Microsoft Office 2030",
},
],
"pagination": {
"pages": 30,
"page": 1,
"offset": 0,
"count": 3,
"total": 90,
"paging": 3,
"status": "continue"
},
"links": {
"self": "https://api.wexbo.com/products?page=2&options=links",
"first": "https://api.wexbo.com/products?page=1&options=links",
"prev": "https://api.wexbo.com/products?page=1&options=links",
"next": "https://api.wexbo.com/products?page=3&options=links",
"last": "https://api.wexbo.com/products?page=9&options=links"
},
"errors": [
{
"code": 100,
"msg": "Field foo not exist.",
"error": "fields_1",
"field": "foo"
}
]
}odpoveďjson

Aktualizácia produktu#

Zobrazenie príkladu požiadavky na URL adresu s metódou GET, HTTP hlavičkou a samotným JSON telom.

https://api.wexbo.com/products/1000001požiadavkaget

Authorization: Bearer {API_TOKEN}
Content-Type: application/vnd.wexbo.v1požiadavkahttp

{
"name": "Tenisová raketa (vypredaná)",
"active": false,
"price": 40.99
}požiadavkajson

Výsledná odpoveď s HTTP hlavičkou a JSON telom.

200 OK
Content-Type: application/vnd.wexbo.v1+json; charset=utf-8
Link: <http://api.wexbo.co/products/1000001>; rel="self"odpoveďhttp

{
"result": "ok",
"data": [
{
"id": 1000001
}
],
"errors": []
}odpoveďjson

Denník zmien#

ODKAZY#