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:
Kód | Popis |
---|---|
GET | Načítanie jedného alebo viacerých záznamov. Požiadavka neobsahuje žiadne telo, teda sa využívajú len URL parametre. |
POST | Vytvorenie nového záznamu. Požiadavka musí obsahovať telo vo formáte JSON, teda údaje záznamu, ktoré chcete pridať. |
PUT | Úprava či aktulizácia existujúceho záznamu. Požiadavka musí obsahovať identifikátor záznamu a telo vo formáte JSON, teda údaje záznamu, ktoré chcete upraviť. |
DELETE | Zmazanie existujúceho záznamu. Požiadavka musí obsahovať identifikátor záznamu, a zároveň neobsahuje žiadne telo. |
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.v1
požiadavkahttp
Názov | Hodnota | Popis |
---|---|---|
Authorization | Bearer {API_TOKEN} | Autorizácia bude vykonaná na základe Bearer tokenu. Hlavička je popísaná vyššie v dokumentácii. |
Content-Type | application/vnd.wexbo.v1 | Určuje, že odoslaná požiadavka je v štruktúre systému WEXBO v aktuálnej verzii v1 a obsah tela je vo formáte JSON s kódovaním UTF-8 . |
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/
products
pož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/
1000001
pož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=25
požiadavkaget
Parameter | Typ | Popis |
---|---|---|
fields | list , array | Požadované atribúty odpovede oddelené čiarkou. Predvolená hodnota je zoznam predvolene zobrazených atribútov konkrétneho endpointu. Príklad použitia v prípade typu list : fields=id,code,name . Príklad použitia v prípade typu array : fields[]=id&fields[]=code&fields[]=name . |
options | list , array | Zobrazenie doplnkových možností v odpovedi. Predvolene je hodnota parametru prázdna. Možné je použiť nasledujúce hodnoty oddelené čiarkou: result , data , count , pagination , links . Príklad použitia v prípade typu list : options=count,pagination,links . Príklad použitia v prípade typu array : options[]=count&options[]=pagination&options[]=links . |
filter | list , object | Možnosť nastavenia viacerých filtrov pre zobrazenie len konkrétnych záznamov. Príklad použitia v prípade typu list : filter=date_from:2000-01-01,date_to:2000-12-31 . Príklad použitia v prípade typu object : filter[date_from]=2000-01-01&filter[date_to]=2000-12-31 . |
sort | list , object | Zoradenie zoznamu záznamov na základe určeného poľa. Povolené hodnoty, resp. zoznam atribútov pre radenie je zobrazený v konkrétnom endpointe. Príklad použitia v prípade typu list : sort=id . Príklad použitia v prípade typu list : sort=id:asc,name:desc . Príklad použitia v prípade typu object : sort[id]=asc&sort[name]=desc . |
direction | enum | Spôsob predvoleného abecedného radenia záznamov na základe URL parametra sort . Zadať je možné len hodnotu asc (A - Z, 0 - 9, vzostupne) alebo desc (Z - A, 9 - 0, zostupne). Predvolenú hodnotu má nastavenú každý endpoint zvlášť. Príklad použitia: direction=asc . |
page | integer | Aktuálna strana. Predvolená hodnota je 1 (prvá strana). Príklad použitia: page=2 . |
offset | integer | Nastavená začiatočná pozícia záznamov pri stránkovaní. V prípade použitia parametru page sa parameter offset neuplatní. Predvolená hodnota je 0 (od začiatku). Príklad použitia: offset=25 . |
limit | integer | Nastavenie stránkovania. Predvolená hodnota je 25 (záznamov na stranu) a maximálna hodnota je 250 (záznamov na stranu). Príklad použitia: limit=100 . |
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,name
pož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,links
pož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[]=links
požiadavkaget
Hodnota | Popis |
---|---|
result | V JSON tele odpovedi bude parameter result hodnota typu string namiesto boolean . Teda namiesto hodnoty true bude ok a namiesto hodnoty false bude error . Pre ľahšie programátorské spracovanie odpovedí odporúčame používať pôvodné hodnoty typu boolean . Pre zobrazenie parametra result súčasne nesmie byť použitý parameter data . |
data | Zobraziť v JSON tele odpovedi len samotný obsah parametra data (len dáta bez ďalších parametrov). V tomto prípade sa v tele nezobrazia žiadne ďalšie parametre ako result , count , pagination , links , errors atď. pričom dané údaje je možné získať len z dostupných HTTP hlavičiek. |
count | Informácia o celkovom dostupnom počte všetkých záznamov na základe zadaných filtrov. Pre zobrazenie parametra count súčasne nesmie byť použitý parameter data . Parameter count je možné využiť len v endpointoch, ktoré zobrazujú zoznam záznamov (metóda GET bez {ID} ). |
pagination | Informácie o stránkovaní zobraziť v samotnom JSON tele odpovedi. Pre zobrazenie parametra pagination súčasne nesmie byť použitý parameter data . Parameter pagination je možné využiť len v endpointoch, ktoré zobrazujú zoznam záznamov (metóda GET bez {ID} ). |
links | Zobraziť v JSON tele odpovedi aj odkazy, napríklad ohľadom stránkovania. Pre zobrazenie parametra links súčasne nesmie byť použitý parameter data . Parameter links je možné využiť len v endpointoch, ktoré zobrazujú zoznam záznamov (metóda GET bez {ID} ). |
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-31
pož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-31
pož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:1
požiadavkaget
https://api.wexbo.com/products
?filter[active]=true
pož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;1000003
požiadavkaget
https://api.wexbo.com/products
?filter[id]=1000001;1000002;1000003
pož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-1000099
požiadavkaget
https://api.wexbo.com/products
?filter[id]=1000001-1000099
požiadavkaget
https://api.wexbo.com/products
?filter[date]=2000-01-01-2000-12-31
pož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=50
pož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=2
pož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=50
pož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=pagination
požiadavkaget
{
···
"pagination": {
"pages": 10,
"page": 1,
"offset": 0,
"count": 25,
"total": 250,
"paging": 25,
"status": "continue"
},
···
}odpoveďjson
Parameter | Typ | Popis |
---|---|---|
pagination.pages | integer | Celkový počet dostupných strán záznamov. |
pagination.page | integer | Aktuálna strana záznamov. |
pagination.offset | integer | |
pagination.count | integer | Počet záznamov na aktuálnej strane. |
pagination.total | integer | Celkový počet záznamov (na všetkých stranách). |
pagination.paging | integer | Počet záznamov na stranu. Aktuálne nastavené stránkovanie pomocou URL parametra limit . |
pagination.status | enum | Aktuálny stav stránkovania, ktorý určuje či je existuje aj nasledujúca strana s ďalšími záznamami. Parametr môže obsahovať hodnoty continue (je možné prejsť na ďalšiu stranu), done (posledná strana), error (strana mimo rozsah stránkovania). |
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=asc
požiadavkaget
Príklad kombinovaného radenia len s využitím URL parametra sort
typu list
.
https://api.wexbo.com/products
?sort=id:asc
požiadavkaget
https://api.wexbo.com/products
?sort=id:asc,name:desc
požiadavkaget
Príklad kombinovaného radenia len s využitím URL parametra sort
typu object
.
https://api.wexbo.com/products
?sort[id]=asc
požiadavkaget
https://api.wexbo.com/products
?sort[id]=asc&sort[name]=desc
pož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#
Typ | Popis |
---|---|
boolean | Boolean hodnota, pričom podporované sú len hodnoty uvedené v príklade. Príklad: true a false alebo 1 a 0 . |
string | Štandardný reťazec znakov v kódovaní UTF-8 . |
integer | Celé číslo. Príklad: 123456 . |
float | Desatinné číslo, pričom ako oddeľovač desatinných miest je použitý znak bodky . . Príklad: 20.45 . |
list | Viaceré hodnoty oddelených znakom čiarky , . Príklad: 1,2,3 . |
array | Pole hodnôt typu JSON alebo URL. Príklad: JSON array [1, 2, 3] alebo URL array x[]=1&x[]=2&x[]=3 . |
object | Objekt typu JSON alebo URL. Príklad: JSON object {'id': 1, 'name': 'test'} alebo URL object x[id]=1&x[name]=test . |
date | Dátum vo formáte YYYY-MM-DD podľa štandardu ISO 8601 . Príklad: 2000-12-31 . |
datetime | Dátum a čas vo formáte YYYY-MM-DD HH:MM:SS podľa štandardu ISO 8601 . Príklad: 2000-12-31 23:59:59 . |
enum | Niektorá z predvolených hodnôt. |
uuid | Validný UUID 32 znakový reťazec hexadecimálnych znakov (a - f, 0 - 9) oddelených znakom pomlčky - podľa štandardu RFC 9562 . Príklad: 0192615c-a59d-7f2c-96a6-0f80c014856a |
code | Reťazec znakov, v ktorom môžu byť použité len základné alfa-numerické znaky (a - z, 0 - 9) bez diakritiky a znaky pomlčka - , podtržník _ a bodka . (bez medzier). |
image | Obsah obrázku v data inline formáte zakódovaný prostredníctvom Base64 . Príklad: data:image/jpeg;base64,... . |
url | URL adresa v absolútnom (externá) alebo aj v relatívnom (lokálna) tvare. Príklad: https://example.com/image.jpg alebo /files/images/image.jpg . |
email | Validná e-mailová adresa. Príklad: example@domain.com . |
language | Kód jazyka podľa štandardu ISO 639-1 . Príklad: cs alebo sk alebo en . |
currency | Kód meny podľa štandardu ISO 4217 . Príklad: CZK alebo EUR alebo USD . |
country | Kód krajiny podľa štandardu ISO 3166-1 alpha-2 . Príklad: cz alebo sk alebo us . |
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=links
pož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
Parameter | Typ | Popis |
---|---|---|
links | object | Zoznam URL adries požiadavky pre stránkovanie. |
links.self | url | Aktuálna strana záznamov alebo aktuálne URL adresa požiadavky. |
links.first | url | Prvá strana záznamov. |
links.prev | url | Predchádzajúca strana záznamov. |
links.next | url | Nasledujúca strana záznamov. |
links.last | url | Posledná strana záznamov. |
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
Parameter | Typ | Popis |
---|---|---|
errors | array | Zoznam chýb a varovaní. |
errors[] | object | Informácie o jednej z chýb alebo varovaní. |
errors[].code | integer | Všeobecný stavový kód chyby popísaný nižšie. |
errors[].msg | string | Krátky popis chyby. |
errors[].error | string | Interný identifikačný kód chyby pre lepšiu identifikáciu v prípade požiadavky na dohľadanie problému. |
errors[].field | string | Problémový parameter, metóda, atribút, pole, možnosť alebo položka požiadavky. |
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#
Kód | Názov | Popis |
---|---|---|
200 | OK | Úspešné načítanie alebo vykonanie požadovaného úkonu na zázname (metódy GET , PUT , DELETE ). |
201 | Created | Záznam bol úspešne vytvorený (metóda POST ). |
204 | No Content | Úspešné spracovanie požiadavky no bez odpovede. Napríklad pri niektorých požiadavkách zmazania záznamu (metóda DELETE ). |
Chyba pri spracovaní#
Kód | Názov | Popis |
---|---|---|
301 | Moved Permanently | Premiestnenie zastaralej endpoint požiadavky na inú URL adresu. Nová URL adresa je uvedená v HTTP hlavičke Location . Odporúčame si čo najskôr URL adresu v implementácii zmeniť na novú. |
400 | Bad Request | Chyba v požiadavke klienta (napríklad v objekte JSON). |
401 | Unauthorized | Nesprávna autorizácia požiadavky klienta. Nezadaná hlavička autorizácie alebo nesprávny či neplatný API token. Podrobné informácie sú popísané v odstavci Autorizácia . |
403 | Forbidden | |
402 | Payment Required | Odpoveď požiadavky je spoplatnená, pričom v profile je nedostatok dostupného kreditu. Podrobné informácie sú popísané v odstavci Obmedzenia / Kredit . |
404 | Not Found | Požadovaný záznam sa nenašiel. |
405 | Method Not Allowed | Nepovolená metóda REQUEST METHOD v požiadavke klienta. Povolené sú len metódy GET , POST , PUT , DELETE . Podrobné informácie sú popísané v odstavci Požiadavka / HTTP metódy . |
408 | Request Timeout | Prekročená maximálna doba na vykonanie požiadavky klienta. |
409 | Conflict | Požiadavku nebolo možné spracovať z rôznych dôvodov, pričom najčastejšie sa jedná o nesprávny formát hodnôt odosielaných atribútov, či nepoužitie povinných atribútov. |
413 | Payload too large | Príliš veľký obsah parametrov požiadavky klienta. Najčastejšie sa jedná o veľmi objemné obrázky, ktoré je možné posielať taktiež prostredníctvom JSON požiadavky. Podrobné informácie sú popísané v odstavci Obmedzenia / Veľkosť požiadavky . |
422 | Unprocessable Entity | Nesprávne zadaná niektorá hodnota alebo parameter požiadavky. |
423 | Locked | Blokovanie požiadavky klienta najčastejšie z dôvodu nepovolenej IP adresy klienta, alebo exspirácie API tokenu či samotného pluginu API . Podrobné informácie sú popísané v odstavci Obmedzenia / Prihlásenia . |
426 | Upgrade Required | Vyžadované nastavenie vyššej verzie požiadavky klienta. Aktuálna verzia API je v1 . Verziu API zadávate do HTTP hlavičky Content-Type , pričom popis je uvedený vyššie v dokumentácii. Podrobné informácie sú popísané v odstavci Požiadavka / HTTP hlavičky . |
429 | Too Many Requests | Požiadavku klienta nebolo možné vykonať z dôvodu dosiahnutia maximálneho počtu požiadaviek, buď za určitý čas alebo na základe nastavených limitov v plugine API . Podrobné informácie sú popísané v odstavci Obmedzenia / Počet požiadaviek . |
500 | Internal Server Error | Nedostupnosť API serveru z dôvodu neplánovaného výpadku. Pre bližšie informácie kontaktujte našu technickú podporu alebo zopakujte požiadavku neskôr. |
501 | Not Implemented | Neexistujúci alebo aktuálne nepodporovaný endpoint požiadavky. |
503 | System maintenance | Prebiehajúca údržba lebo dočasný výpadok API systému. Zopakujte požiadavku neskôr. |
505 | HTTP Version Not Supported | Požiadavka klienta bola odoslaná cez nepodporovaný protokol HTTP . Všetky požiadavky je nutné posielať cez šifrovaný protokol HTTPS . Podrobné informácie sú popísané v odstavci Požiadavka / URL adresa . |
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=3
požiadavkaget
Authorization: Bearer
{API_TOKEN}
Content-Type: application/vnd.wexbo.v1
pož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/
1000001
požiadavkaget
Authorization: Bearer
{API_TOKEN}
Content-Type: application/vnd.wexbo.v1
pož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#
Dátum | Verzia | Popis |
---|---|---|
2025 Q1 | v1 | Public API for users (we are preparing...) |
2024-11-22 | v1 | Public API for internal testing |
2019-02-01 | v1 | For internal developers only |