WEXBO API
INSTRUCTION#
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.
Authorization#
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}
requesthttp
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
.
Request#
HTTP methods#
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:
Code | Description |
---|---|
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 headers#
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
requesthttp
Name | Value | Description |
---|---|---|
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 address#
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}
requestget
Endpoint#
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
requestget
Zozname všetkých dostupných endpointov nájdete nižšie v dokumentácii v sekcii References, 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.
Identifier#
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
requestget
URL parameters#
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
requestget
Parameter | Type | Description |
---|---|---|
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 . |
Fields#
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
requestget
{
···
"data": [
{
"id": 1000001,
"code": "product_code",
"name": "Product name",
},
···
],
···
}responsejson
Všetky podporované atribúty pre URL parameter fields
sú popísané v konkrétnom endpointe.
Additional options#
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
requestget
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
requestget
Value | Description |
---|---|
result | In the JSON body of the response, the parameter result will be a value of type string instead of boolean . Thus, instead of the value true it will be ok and instead of the value false it will be error . For easier programmer processing of answers, we recommend using the original boolean type values. To display the result parameter, the data parameter must not be used at the same time. |
data | Display in the JSON body of the response only the content of the parameter data (only data without other parameters). In this case, no other parameters like result , count , pagination , links , errors , etc. will be displayed in the body. while the given data can only be obtained from the available HTTP headers. |
count | Information about the total available number of all records based on the specified filters. To display the count parameter, the data parameter must not be used at the same time. Parameter count je možné využiť len v endpointoch, ktoré zobrazujú zoznam záznamov (metóda GET bez {ID} ). |
pagination | Show paging information in the JSON body of the response itself. To display the pagination parameter, the data parameter must not be used at the same time. Parameter pagination je možné využiť len v endpointoch, ktoré zobrazujú zoznam záznamov (metóda GET bez {ID} ). |
links | Show links in the JSON body of the answer, for example regarding pagination. To display the links parameter, the data parameter must not be used at the same time. Parameter links je možné využiť len v endpointoch, ktoré zobrazujú zoznam záznamov (metóda GET bez {ID} ). |
Filtering#
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
requestget
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
requestget
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
requestget
https://api.wexbo.com/products
?filter[active]=true
requestget
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
requestget
https://api.wexbo.com/products
?filter[id]=1000001;1000002;1000003
requestget
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
requestget
https://api.wexbo.com/products
?filter[id]=1000001-1000099
requestget
https://api.wexbo.com/products
?filter[date]=2000-01-01-2000-12-31
requestget
Pagination#
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
requestget
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
requestget
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
requestget
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
...responsehttp
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
requestget
{
···
"pagination": {
"pages": 10,
"page": 1,
"offset": 0,
"count": 25,
"total": 250,
"paging": 25,
"status": "continue"
},
···
}responsejson
Parameter | Type | Description |
---|---|---|
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). |
Sorting#
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
requestget
Príklad kombinovaného radenia len s využitím URL parametra sort
typu list
.
https://api.wexbo.com/products
?sort=id:asc
requestget
https://api.wexbo.com/products
?sort=id:asc,name:desc
requestget
Príklad kombinovaného radenia len s využitím URL parametra sort
typu object
.
https://api.wexbo.com/products
?sort[id]=asc
requestget
https://api.wexbo.com/products
?sort[id]=asc&sort[name]=desc
requestget
JSON body#
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/productsrequestpost
{
"name": "Tenisová raketa",
"active": true,
"price": 50.99,
···
}requestjson
Data types#
Type | Description |
---|---|
boolean | Boolean value, while only the values shown in the example are supported. Example: true a false alebo 1 a 0 . |
string | Standard character string in UTF-8 encoding. |
integer | Whole number. Example: 123456 . |
float | A decimal number, where the dot character . is used as a decimal place separator. Example: 20.45 . |
list | Multiple values separated by comma character , . Example: 1,2,3 . |
array | JSON or URL values field. Example: JSON array [1, 2, 3] alebo URL array x[]=1&x[]=2&x[]=3 . |
object | An object of type JSON or URL. Example: JSON object {'id': 1, 'name': 'test'} alebo URL object x[id]=1&x[name]=test . |
date | Date in YYYY-MM-DD format according to the ISO 8601 standard. Example: 2000-12-31 . |
datetime | Date and time in YYYY-MM-DD HH:MM:SS format according to the ISO 8601 standard. Example: 2000-12-31 23:59:59 . |
enum | Some of the default values. |
uuid | A valid UUID is a 32-character string of hexadecimal characters (a - f, 0 - 9) separated by the dash character - according to the RFC 9562 standard. Example: 0192615c-a59d-7f2c-96a6-0f80c014856a |
code | A character string in which only basic alpha-numeric characters (a - z, 0 - 9) can be used without diacritics and the hyphen - , underscore _ and dot . characters (without spaces). |
image | Image content in data inline format encoded via Base64 . Example: data:image/jpeg;base64,... . |
url | URL address in absolute (external) or relative (local) form. Example: https://example.com/image.jpg alebo /files/images/image.jpg . |
email | A valid email address. Example: example@domain.com . |
language | Language code according to ISO 639-1 standard. Example: cs alebo sk alebo en . |
currency | Currency code according to ISO 4217 standard. Example: CZK alebo EUR alebo USD . |
country | Country code according to ISO 3166-1 alpha-2 standard. Example: cz alebo sk alebo us . |
Response#
Súčasťou každej odpovede servera na požiadavku klienta je telo vo formáte JSON
s parametrami result
, data
, errors
.
Status#
Ú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",
···
}responsejson
Data#
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,
···
},
···
}responsejson
Pagination#
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
.
Links#
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"responsehttp
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
requestget
{
···
"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"
},
···
}responsejson
Parameter | Type | Description |
---|---|---|
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. |
Errors#
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": "..."
}
]
}responsejson
Parameter | Type | Description |
---|---|---|
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. |
Response codes#
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í.
Successful processing#
Code | Name | Description |
---|---|---|
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 ). |
Error in processing#
Code | Name | Description |
---|---|---|
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 . |
Restrictions#
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.
Logins#
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
.
Size of the request#
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
.
Number of requests#
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.
Credit#
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.
Examples#
Show produkts#
https://api.wexbo.com/products
?fields=id,code,name,foo&options=pagination,links&sort=id&direction=asc&page=1&offset=0&limit=3
requestget
Authorization: Bearer
{API_TOKEN}
Content-Type: application/vnd.wexbo.v1
requesthttp
200 OK
Content-Type: application/vnd.wexbo.v1
+json; charset=utf-8responsehttp
{
"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"
}
]
}responsejson
Product update#
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
requestget
Authorization: Bearer
{API_TOKEN}
Content-Type: application/vnd.wexbo.v1
requesthttp
{
"name": "Tenisová raketa (vypredaná)",
"active": false,
"price": 40.99
}requestjson
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"responsehttp
{
"result": "ok",
"data": [
{
"id": 1000001
}
],
"errors": []
}responsejson
Changelog#
Date | Version | Description |
---|---|---|
2019-02-01 | v1 | For internal developers only |