Pet-Distributor.cz - API dokumentace

1. Obecné

Nacházíte se v API dokumentaci api.pet-distributor.cz pro web www.pet-distributor.cz.

Aktuální verze API 1.5.0
Poslední editace
Kontakt Ondřej Vašíček (it@profisales.cz)

V případě nalezení chyb či nepřesností nebo námětu na vylepšení nás prosím kontaktuje na výše uvedený kontakt.

Používáním API souhlasíte s všeobecnými obchodními podmínkami.

1.1 O API

API je obecně veřejné rozhraní, díky kterému může klientská aplikace komunikovat s cílovým systémem.
V tomto případě je cílový systém e-shop www.pet-distributor.cz a klientská aplikace váš systém.

Díky API můžete automatizovaně v reálném čase čerpat veřejné informace (kategorie, produkty, ...) nebo data určená přímo vám (objednávky, vaše ceny, ...).
Stejně tak je možné data do API zasílat (vytváření objednávek, manipulace s položkami, ...).

1.2 Struktura dokumentace

Dokumentace je jednostránková. Pro hledání můžete použít prohlížeč (ctrl + f).

Pro rychlou orientaci slouží navigace v levém menu. Její podsekce se otevírají automaticky a naposledy otevřená sekce zůstane otevřená při další návštěvě.

Pokud často používáte určitou sekci, je možné si na ni vytvořit trvalý odkaz - po najetí na nadpis vyjede k levé straně nadpisu znak #, na který lze kliknout. Tím se dostanete přímo na danou sekci a v adresním řádku se zobrazí adresa sekce, kterou lze dle potřeby uložit nebo použít jako záložku.

Dokumentace je plně responsivní - je možné jí používat na zařízeních jako mobil a tablet.

1.3 Verzování

API používá verzování SemVer semver.org.
V jednoduchosti:

  • Změna major verze ruší zpětnou kompatibilitu.
  • Minor verze přidává nové funkce se zachováním zpětné kompatibility
  • Patch verze pouze opravuje chyby
V plánu je vydávat pouze minor a patch verze, tedy 1.x.x, bez porušení zpětné kompatibility.

Pod adresou https://api.pet-distributor.cz/v1/, kde v1 značí major verzi 1, se vždy nachází poslední minor/patch verze.

Pokud bude mít API verzi například 1.7.13, pod jedinou dostupnou adresou https://api.pet-distributor.cz/v1/ bude právě tato verze 1.7.13, včetně dokumentace k ní.
Díky zpětné kompatibilitě by měly fungovat veškeré implementace na předchozí verze.

Nové funkce a opravy je možné sledovat v sekci Changelog.

1.4 Šifrování

API stejně jako web používá HTTPS protokol pro šifrování přenášených dat.

Veškeré požadavky na url s http:// budou přesměrovány na https:// variantu. Přesto by mělo být v zájmu uživatele API, aby vždy explicitně volal URL v https:// tvaru, protože klientská aplikace nemusí defaultně na naše přesměrování reagovat.

1.5 Příklady

API je zcela nezávislé na klientově platformě či frameworku. Není proto reálné vytvářet příklady pro jakékoliv prostředí.

Aplikační příklady budou uváděny především v jazyce PHP ve verzi 5.5 a budou sloužit spíše jako obecný příklad, aplikovatelný kdekoliv.
Pro data bude použit JSON nebo XML a někdy budou využity i HTTP hlavičky.

Pro vytváření spojení s API bude použita knihovnu cURL php.net, přestože způsobů v PHP je více, například funkce file_get_contents() php.net.

V samotných příkladech bude pro srozumitelnost použit především kód relevantní k probírané problematice. Berte na vědomí, že pro použití v reálných podmínkách bude zapotřebí kód upravit dle vašich potřeb.

Zde je pro názornost uveden příklad, který ukazuje, jak nastavit přijímaná data na XML formát:

$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_HTTPHEADER => ['Accept: application/xml']]);
$result = curl_exec($ch);

Ve reálném prostředí byste ale zřejmě použili spíše něco takového:

$options = [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_HTTPAUTH => CURLAUTH_BASIC,
    CURLOPT_USERNAME => $token,
    CURLOPT_FOLLOWLOCATION => true,
    CURLOPT_POSTREDIR => 3,
    CURLOPT_TIMEOUT => 30,
    CURLOPT_CONNECTTIMEOUT => 10,
    CURLOPT_HTTPHEADER => ['Accept: application/xml']
];

$ch = curl_init($url);
curl_setopt_array($ch, $options);
$result = curl_exec($ch);

curl_close($ch);

Protože řada nastavení se bude při každém dotazu opakovat a většinou budete požadovat jen jinou URL či zasílat jiná data, je v rámci DRY wikipedia.com dobré udělat si obecnou metodu.

1.6 Formát dat

API nyní podporuje formáty JSON a XML.

Defaultně vrací API formát JSON.
Formát je však možné explicitně nastavit pomocí HTTP hlavičky Accept.

Pokud potřebujete například vrátit data ve formátu XML, zašlete následující hlavičku:

Accept: application/xml

V případě potřeby explicitního nastavení JSONu potom:

Accept: application/json

Pokud bude zaslána jakákoliv jiná hlavička, vrátí API HTTP stavový kód 415 Unsupported Media Type.

1.7 Kódování

Kódování poskytovaných dat je vždy UTF-8.
Stejné kódování je vyžadování i při zasílání dat do API.

1.8 Jazyk

V současné době jsou všechna vracená data v češtině s výjimkou některých chybových obecných hlášek, které jsou v angličtině.

Pokud se v budoucnu objeví nový jazyk, čeština zůstane defaultní.
Bude však možné další dostupné jazyky nastavit pomocí HTTP hlavičky Accept-Language.

1.9 Testování

API zatím nenabízí vyloženě testovací mechaniku, která by umožnila v ostrém režimu zasílat testovací dotazy, které neovlivní produkční data. S přibývající komplexností tuto možnost zvážíme.

Je však zatím možné používat vývojovou verzi API na adrese https://api.develop.pet-distributor.cz/v1/, která má svou vlastní testovací databázi. Ta sice není aktuální s ostrým webem, což však nebrání možnosti bez omezení API testovat.
Pokud jste právě na develop verzi dokumentace API, veškeré odkazy v ní směřují na develop verze stránek.

Vývojová verze může obsahovat experimentální funkce, které jsou předmětem testování. Proto se občas může vyskytnout dočasné neočekávané chování.

Pro samotné testování doporučujeme při práci s API používat nějakého API klienta, který testování ulehčuje. Například Postman www.getpostman.com/apps.

1.10 Limity

Vzhledem ke specifické skupině uživatelů neplánujeme zavést omezení přístupů, tzv. rate limiting.
S ohledem na počet položek nepřesahujícím pětimístná čísla, neplánujeme ani stránkování výpisů. Veškeré výstupy obsahují vždy celé sestavy.

Změna výše popsaného by nastala pouze na základě razantní změny podmínek, které by si vyžádali i novou verzi API.

2. HTTP metody

HTTP metody wikipedia.cz umožňují dotazovat určitou API adresu různými způsoby a dosáhnout tak rozdílných výsledků.
Běžné jsou například metody GET a POST, ale existují i další, z nichž některé API používá pro specifické účely.

Metody se liší dle toho, zda je můžete použít na seznam položek nebo na jejich detail. Navíc ne každá metoda je povolena pro každý API endpoint.
Detaily jsou uvedeny pro každý endpoint zvlášť.

2.1 Metody pro seznam

Následující HTTP metody lze použít na seznam položek, tedy například na výpis všech produktů.

HTTP Metoda Popis
GET Vrací seznam položek.
HEAD Stejné jako GET, ale vrací pouze hlavičky bez těla. Vhodné by bylo především pro zjištění informaci při stránkovaných datech, kde lze z hlaviček zjistit počet položek na stránku, počet stran, celkový počet položek, aktuální stranu a další, aniž bychom načítali samotná data do těla zprávy.
POST Vytváří novou položku.
OPTIONS V hlavičce ALLOW zasílá seznam povolených metod (prakticky tento seznam).

2.2 Metody pro detail

Následující HTTP metody lze použít na detail položky, tedy například detail objednávky.

HTTP Metoda Popis
GET Vrací detail položky.
HEAD Stejné jako GET, ale vrací pouze hlavičky bez těla.
PATCH, PUT Aktualizuje položku.
DELETE Maže položku.
OPTIONS V hlavičce ALLOW zasílá seznam povolených metod (prakticky tento seznam).

3. Systémové odpovědi

Pokud je na API zaslán jakýkoliv požadavek, systém vždy vrací nazpět informace, které se skládají z:

  • HTTP stavového kódu
  • Těla zprávy

3.1 HTTP stavový kód

Přečtení HTTP stavového kódu wikipedia.cz by mělo být primárním způsobem, jak zjistit výsledek zpracování požadavku.
Dle něj by se měla aplikace rozhodovat, jak dále postupovat.

API vrací následující kódy a jejich textovou formu v angličtině:

Kód Zpráva
200 Požadavek byl úspěšně zpracován a vrátil očekávaná data.
201 Položka byla úspěšně vytvořena dle POST požadavku. Location hlavička obsahuje její novou URL.
204 Požadavek byl úspěšně zpracován a nevrátil žádnou odpověď (například DELETE požadavek).
400 Neplatný požadavek. Například nevalidní vstupní data, neplatný parametr apod.
401 Neproběhla autentizace, respektive nevalidní token uživatele.
403 Uživatel sice použil validní token, ale nemá oprávnění na danou akci.
404 Požadovaná stránka neexistuje.
405 Nepovolená metoda požadavku. Seznam povolených HTTP metod pro danou akci je v hlavičce Allow.
415 Nepodporovaný typ požadovaného formátu dat.
422 Validace dat neproběhla úspěšně. Více informací v těle zprávy.
500 Vnitřní chyba serveru, pravděpodobně chyba API.

3.2 Tělo zprávy

Tělo zprávy je asociativní multidimenzionální pole v jednom z podporovaných formátů.

Na první úrovni jsou vždy dva prvky - status a data.

{
    "status": "ok",
    "data": {
        "item": {"param1": "..."}
    }
}

V případě XML jsou všechna data navíc v uzlu response.

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <status>ok</status>
    <data>
        <item>
            <param1>...</param1>
        </item>
    </data>
</response>

3.2.1 Status

Status slouží k jednoduššímu zjištění, zda se požadavek provedl úspěšně.
Může nabývat dvou hodnot:

  • ok - požadavek proběhl úspěšně. Prakticky reprezentuje HTTP stavové kódy >= 200 < 300.
  • error - nastala chyba. Detaily lze zjistit z HTTP stavového kódu a těla zprávy.

3.2.2 Data

Obsahuje samotná data specifická pro daný požadavek.
Většinou je každý prvek v položce item.
Struktura i příklady lze najít v dokumentaci níže, pro každý API endpoint zvlášť.

3.2.2.1 HATEOAS

Mnohdy jsou data komplexnější, než obyčejný výpis položek s parametry. Jednotlivé parametry mohou přes identifikátory poukazovat na položku z jiného výpisu.
U produktu je to třeba příklad značky nebo kategorie.
Každý produkt má maximálně jednu značku, ale může být ve více kategoriích.

Jak taková vzdálená data API poskytne? Tuto problematiku řeší HATEOAS wikipedia.cz.

V kostce API poskytne v položce odkaz na vlastní endpoint s detaily o provázaných datech.

Seznam takových odkazů se nachází v parametru _links.
Speciálním případem je potom link self, který odkazuje sám na sebe. V praxi je pak možné použít položku z výpisu a přejít na její detail.

Příklad, jak může přítomnost _links v položce vypadat:

{
    "status": "ok",
    "data": [
        {
            "code": 123,
            "name": "Product XXX",
            "param1": "value1",
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/products/123/"
                },
                "brand": {
                    "href": "https://api.pet-distributor.cz/v1/brands/3/"
                }
            }
        },
        {
            "code": 456,
            "name": "Product YYY",
            "param1": "value1",
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/products/456/"
                },
                "categories": [
                    {
                        "href": "https://api.pet-distributor.cz/v1/categories/11/"
                    },
                    {
                        "href": "https://api.pet-distributor.cz/v1/categories/22/"
                    }
                ]
            }
        }
    ]
}

Částečně lze některá provázaná data dostat přímo do hlavního výpisu pomocí modifikace obsahu, konkrétně parametru expand.

3.3 Chybové zprávy

Chybové zprávy jsou speciálním případem systémové odpovědi, kdy položka status nabývá hodnotu error.

V takovém případě jsou obsahem položky data 4 následující položky:

  • name - název chyby.
  • message - textový detail chyby.
  • code - kód chyby - zatím nevyužíváno, připraveno pro budoucí využití systémovějšího sledování typů chyb.
  • status - HTTP stavový kód.

Takto může vypadat tělo systémové odpovědi v případě chybného pokusu u autentizaci:

{
    "status": "error",
    "data": {
        "name": "Unauthorized",
        "message": "You are requesting with an invalid credential.",
        "code": 0,
        "status": 401
    }
}

3.3.1 Ošetření chyb

Je dobrou praktikou i v zájmu klienta, aby byly různé systémové odpovědi z API ošetřeny.

Pokud má vaše aplikace komunikovat s API automaticky, nemělo by se stát, že v případě chyby tiše zhavaruje.

Základním předpokladem je, že v situacích, kdy vaše aplikace neudělá vámi požadovanou akci z jakéhokoliv důvodu (chyba v aplikaci, nedostupnost služby, neočekávaný výstup z API, ...), měla by se situace logovat a například zaslat na mail.
Díky tomu je možné pružně na situaci reagovat a například udělat objednávky dočasně ručně, než se problém vyřeší. To je většinou preferovanější varianta, než po týdnu zjistit, že nechodí zboží a vaše odeslané objednávky již nelze nikde dohledat, protože se neuložily.

Mnohdy je však lepší jít ještě dále a pokud to situace umožní, snažit se automatizovat i očekávané situace.
Praktické například může být se službou několikrát po pár vteřinách opakovat spojení, pokud první pokus selže. Nebo při nezdařilém pokusu o uložení objednávky končící chybou HTTP kódem 422 - Data Validation Failed si zase včetně chyby uložit i zasílaná data, abyste je mohli po úpravě odeslat znovu.
Vždy záleží na konkrétní situaci a poměru usnadněné/vyložené práce.

4. Autentizace

Autentizace funguje na principu skrytých tokenů.
Pomocí našeho systému si vygenerujete token, který budete posílat spolu s požadavky.
API pak akceptuje pouze požadavky s validním tokenem. Ostatní vrací se stavovým HTTP kódem 401 Unauthorized.

4.1 Vytvoření tokenu

Token je možné si libovolně vygenerovat ve vašem účtu v sekci API.

V jeden moment je možné mít pouze jeden validní token.

Vygenerováním nového tokenu přestane starý platit. Je nutné to brát v potaz, pokud některá z vašich aplikací starý token používá.

4.2 Zaslání tokenu

Token se do API zasílá pomocí tzv Basic access authentication wikipedia.cz.

V praxi se jen zašle HTTP hlavička Authorization: Basic base64, kde base64 je textový řetězec login:heslo zakódován metodou Base64.
V našem případě se token posílá jako login, na heslo se nebere zřetel. Stačí kódovat pouze řetězec login:.

Například pro token lostnumbers4815162342 se zakóduje řetězec lostnumbers4815162342: metodou Base64 a zašle následující HTTP hlavička:

Authorization: Basic bG9zdG51bWJlcnM0ODE1MTYyMzQyOg==

V PHP je díky cURL situace ještě jednodušší:

$options = [
    CURLOPT_HTTPAUTH => CURLAUTH_BASIC,  // typ autentizace; automaticky zakóduje do Base64
    CURLOPT_USERNAME => $token,  // nastavuje pouze login, narozdíl od CURLOPT_USERPWD
];

$ch = curl_init($url);
curl_setopt_array($ch, $options);
$result = curl_exec($ch);

4.3 Uložení tokenu

Protože s vygenerovaným tokenem musí vaše aplikace pracovat, bude muset být na vaší straně uložen.

Z hlediska bezpečnosti, stejně jako například přihlašovací údaje do databáze, by token neměl být součástí repozitáře. Vhodné je ho umístit například do souboru s parametry určenými pro konkrétní prostředí (local, production, ...). V případě GITu pak bývá takový soubor s parametry součástí .gitignore.
Samozřejmostí je, aby k takovému souboru měli přístup pouze oprávnění lidé.

5. Modifikace výstupu

Kromě toho, že máte možnost pomocí hlavičky zvolit formát dat, je možné určitými GET parametry ovlivňovat i samotný obsah.

V současné době podporujeme tyto parametry:

  • fields
  • expand

Všechny parametry je možné kombinovat.

5.1 Fields

Pokud pomocí URL zažádáte API o data, defaultně nabídne všechny dostupné parametry položky.
Fields můžete použít v momentě, kdy vás zajímají pouze určité parametry. Můžete tím dosáhnout menšího výpisu, který se znatelně rychleji načte i zpracuje.

Ideálním příkladem může být situace, kde máte jeden skript na import produktů a druhý rychlý pouze na aktualizaci dostupnosti.
V tomto druhém případě tedy nemusíte načítat všechna data, která nepotřebujete, ale pouze kód a dostupnost.

Do URL se fields zapisuje jako seznam položek oddělených čárkou ,.
URL pro skript aktualizující dostupnost zmíněný výše by pak mohla vypadat následovně:

https://api.pet-distributor.cz/v1/products/?fields=code,delivery
Seznam položek, které můžete do fields použít, je shodný se seznamem parametrů pro každý endpoint.

5.2 Expand

Jak bylo popsáno v sekci HATEOAS, provázaná data API poskytuje pomocí linků.

V praxi je však někdy i přes případné nevýhody příhodné data získat přímo.
Přesně to umožňuje parametr expand.

Pokud například import produktů provádíte bez samostatné tabulky pro značku, jejíž jméno zapisujete rovnou do tabulky s produkty, je výhodnější získat název firmy rovnou.

Bez expand byste museli po naimportování produktů procházet endpoint značek a všechny vaše produkty aktualizovat o název značky. Popřípadě během importu jednotlivých produktů zvlášť dotazovat detail každé značky, což při při tisících produktů bylo extrémně neefektivní a velká zátěž na straně API.

Stejným způsobem jako u fields můžeme modifikovat obsah výstupu pomocí změny url.
URL pro výše zmíněný případ by mohla vypadat následovně:

https://api.pet-distributor.cz/v1/products/?expand=brand

Výstup takových produktů by mohl vypadat takto:

{
    "status": "ok",
    "data": [
        {
            "code": 123,
            "name": "Product XXX",
            "param1": "value1",
            "brand": {
                "id": 8,
                "name": "Company AAA"
            },
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/products/123/"
                },
                "brand": {
                    "href": "https://api.pet-distributor.cz/v1/brands/3/"
                }
            }
        },
        {
            "code": 456,
            "name": "Product YYY",
            "param1": "value1",
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/products/456/"
                }
            }
        }
    ]
}
Seznam položek, které můžete do expand použít, je vypsán v dokumentaci u každého endpointu.
Při použití expand budou _links stále dostupné.

5.3 Ostatní

Do budoucna plánujeme další parametry na filtrování, řazení a další.

6. Produkty

API produktů může plnohodnotně nahradit současný XML export produktů. Není vázáno na Heureka formát a může nabízet více dat ve vhodnějším formátu.

6.1 Parametry

Seznam parametrů produktu nacházejících se ve výpisu i detailu s jich popisem.

Klíč Poznámka
code Kód produktu - unikátní identifikátor, dle něž lze párovat.
numeric_code Číselná varianta kódu produktu - unikátní identifikátor, dle něž lze párovat. Má délku 40 znaků.
name Název.
description Plný popis v HTML formátu.
short_description Krátký popis v plaintextu.
categories_id Pole s identifikátory kategorií.
image Absolutní URL cesta k souboru s profilovým obrázkem.
url Absolutní URL cesta k produktu na webu
ean EAN kód produktu
delivery Počet dní, za které odesíláme.
vat Sazba DPH v procentech.
brand_id Identifikátor značky
weight Hmotnost v kg (float).
amount_in_box Číslo určuje, kolik kusů produktu je v kartonu. Pokud objednáváte více kusů, oceníme, když zvolíte násobky tohoto čísla. Ulehčíte tím balící proces a dostanete zboží rovnou v kartonu.
stock Počet jednotek na skladě. Hodnoty nad 20 zůstávají zobrazeny jako toto číslo.
not_sold Bool hodnota, zda se produkt již neprodává - tedy false, pokud se prodává.
Takové produkty již není možné objednat, pro archivní účely však můžete stále na svém webu zobrazovat jejich detail. Doporučujeme je ale pro běžného uživatele skrýt z výpisu.
Pokud se takový produkt objeví v objednávce, systém vrátí chybu s HTTP stavovým kódem 422.
price Nákupní cena bez DPH.
price_sale Nákupní cena se slevou bez DPH.
price_vat Nákupní cena s DPH.
price_sale_vat Nákupní cena se slevou s DPH.
base_price Doporučená prodejní cena bez DPH.
base_price_sale Doporučená prodejní cena se slevou bez DPH.
base_price_vat Doporučená prodejní cena s DPH.
base_price_sale_vat Doporučená prodejní cena se slevou s DPH.
modified_at Časové razítko, kdy byl produkt naposledy změněn.
Ceny jsou celá čísla v korunách.
V plánu je nabídnout zobrazení kategorií jako cestu v Heureka formátu.

6.1.1 Expand

Více informací v sekci Expand.

Klíč Popis
brand Značka - seznam parametrů viz. sekce 9.1. - Značky - parametry.
V plánu je nabídnout expand parametr pro kategorie.

6.1.2 Links

Více informací v sekci HATEOAS.

Klíč Popis
self Link na aktuální položku.
brand Link na detail firmy.
categories Pole linků na detaily kategorií.

6.2 Výpis

Poskytuje seznam všech produktů nezávisle na kategorii.

URL https://api.pet-distributor.cz/v1/products/
Povolené metody GET, HEAD, OPTIONS
Zakázané metody POST

Ukázka, jak může výpis vypadat:

{
    "status": "ok",
    "data": [
        {
            "code": "123",
            "name": "Produkt XXX",
            "description": "<p><strong>popis</strong>...</p>",
            "short_description": "Krátký popis",
            "categories_id": [
                111,
                222
            ],
            "image": "https://www.pet-distributor.cz/image-url.jpg",
            "url": "https://www.pet-distributor.cz/produkt-url/",
            "ean": "123456789",
            "delivery": 0,
            "vat": 15,
            "brand_id": 8,
            "price": 722,
            "price_sale": null,
            "price_vat": 831,
            "price_sale_vat": null,
            "base_price": 850,
            "base_price_sale": null,
            "base_price_vat": 977,
            "base_price_sale_vat": null,
            "modified_at": "2016-07-18 00:04:02.817+02",
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/products/123/"
                },
                "brand": {
                    "href": "https://api.pet-distributor.cz/v1/brands/8/"
                },
                "categories": [
                    {
                        "href": "https://api.pet-distributor.cz/v1/categories/111/"
                    },
                    {
                        "href": "https://api.pet-distributor.cz/v1/categories/222/"
                    }
                ]
            }
        },
        {
            "code": "456",
            "name": "Produkt YYY",
            "param1": "value 1 ..."
        }
    ]
}

6.3 Detail

Poskytuje detail produktu.

URL https://api.pet-distributor.cz/v1/products/<code>/
Parametry
  • <code> - kód produktu
Povolené metody GET, HEAD, OPTIONS
Zakázané metody PATCH, PUT, DELETE

Ukázka výstupu je stejná jako pro výpis s tím rozdílem, že v data není pole, ale rovnou detail produktu.

7. Objednávky

Endpointy pro objednávky umožňují získávat data o vlastních objednávkách, včetně jejich zakládání a aktualizování.

7.1 Parametry

Seznam parametrů objednávek nacházejících se ve výpisu i detailu s jejich popisem.

Obecné

Klíč Poznámka
id Unikátní identifikátor, dle něhož lze párovat.
status_id Identifikátor stavu objednávky.
delivery_id Identifikátor typu dopravy.
payment_id Identifikátor typu platby.
price Kompletní cena objednávky bez DPH.
price_vat Kompletní cena objednávky s DPH.
delivery_price Cena dopravy při objednání.
payment_price Cena platby při objednání.
note Poznámka nakupujícího.
order_items

Pole s objednanými produkty. Každý produkt obsahuje následující parametry:

  • code - kód produktu
  • name - název produktu při objednání
  • quantity - počet kusů
  • price - cena za kus bez DPH při objednání
  • vat - sazba DPH v % při objednání
  • _links - v rámci HATEOAS obsahuje každý item link product na endpoint produktu
created_at Časové razítko vytvoření objednávky.
modified_at Časové razítko poslední úpravy objednávky.

Fakturační údaje

Klíč Poznámka
id_number Identifikační číslo osoby (IČ, IČO).
vat_id Daňové identifikační číslo (DIČ).
billing_company Firma (fakturační).
billing_first_name Křestní jméno (fakturační).
billing_last_name Příjmení (fakturační).
billing_city Město (fakturační).
billing_postcode PSČ (fakturační).
billing_address Ulice/adresa (fakturační).
billing_phone Telefon (fakturační).
billing_email E-mail (fakturační).

Dodací údaje

Klíč Poznámka
delivery_equal_billing Bool hodnota, zda je dodací adresa stejná, jako fakturační.
delivery_company Firma (dodací).
delivery_first_name Křestní jméno (dodací).
delivery_last_name Příjmení (dodací).
delivery_city Město (dodací).
delivery_postcode PSČ (dodací).
delivery_address Ulice/adresa (dodací).
delivery_phone Telefon (dodací).
delivery_email E-mail (dodací).

7.1.2 Links

Více informací v sekci HATEOAS.

Klíč Popis
self Link na aktuální položku.
status Link stav objednávky.
delivery Link typ dopravy.
payment Link typ platby.

7.2 Výpis

Poskytuje seznam vašich objednávek.

URL https://api.pet-distributor.cz/v1/orders/
Povolené metody GET, HEAD, OPTIONS, POST
Zakázané metody -

Ukázka, jak může výpis vypadat:

{
    "status": "ok",
    "data": [
        {
            "id": 1,
            "status_id": 1,
            "delivery_id": 2,
            "payment_id": 3,
            "price": 363,
            "price_vat": 441,
            "delivery_price": 99,
            "payment_price": 30,
            "note": "Doručte prosím ve večerních hodinách.",
            "orderItems": [
                {
                    "code": "123",
                    "name": "Product XXX",
                    "quantity": 1,
                    "price": 234,
                    "vat": 21,
                    "_links": {
                        "product": {
                            "href": "https://api.pet-distributor.cz/v1/products/123/"
                        }
                    }
                },
                {
                    "code": "654",
                    "name": "Product YYY",
                    "quantity": 3,
                    "price": 654,
                    "vat": 15,
                    "_links": {
                        "product": {
                            "href": "https://api.pet-distributor.cz/v1/products/654/"
                        }
                    }
                }
            ],
            "created_at": "2016-07-24 18:51:09.665+02",
            "modified_at": null,
            "id_number": "123456789",
            "vat_id": "CZ8601011234",
            "billing_company": "Firma XXX",
            "billing_first_name": "Jan",
            "billing_last_name": "Novák",
            "billing_city": "Blansko",
            "billing_postcode": "67801",
            "billing_address": "Nádražní 1",
            "billing_phone": "+420 111 222 333",
            "billing_email": "mail@gmail.com",
            "delivery_equal_billing": true,
            "delivery_company": null,
            "delivery_first_name": null,
            "delivery_last_name": null,
            "delivery_city": null,
            "delivery_postcode": null,
            "delivery_address": null,
            "delivery_phone": null,
            "delivery_email": null,

            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/orders/1/"
                },
                "status": {
                    "href": "https://api.pet-distributor.cz/v1/statuses/1/"
                },
                "delivery": {
                    "href": "https://api.pet-distributor.cz/v1/deliveries/2/"
                },
                "payment": {
                    "href": "https://api.pet-distributor.cz/v1/payments/3/"
                }
            }
        },
        {
            "id" : 2,
            "parameter2" : "value 2 ..."
        }
    ]
}

7.2.1 Vytvoření objednávky

Novou objednávku vytvoříte zasláním dat objednávky v těle požadavku metodou POST.
Následující parametry se používají pro založení i editaci objednávky:

Parametr Typ Povinné Poznámka
terms_conditions boolean Jediná povolená hodnota je true. Toto pole je forma souhlasu s obchodními podmínkami.
join_orders boolean Defaultně true.
Pokud je tento parametr na true, bude více vašich objednávek z jednoho pracovního dne spojeno do jedné, což je běžné současné chování.
delivery_id integer Musí být platné ID dopravy.
payment_id integer Musí být platné ID platby.
note text
id_number varchar(16)
vat_id varchar(16)
billing_company varchar(256)
billing_first_name varchar(64)
billing_last_name varchar(64)
billing_city varchar(64)
billing_postcode varchar(6) Číslo s pěti znaky. Přebytečná mezera bude smazána.
billing_address varchar(64)
billing_phone varchar(64)
billing_email varchar(64) Musí jít o validní e-mailovou adresu.
delivery_equal_billing boolean Defaultně false.
Pokud false, následující delivery_* parametry jsou povinné.
Pokud true, následující delivery_* parametry se neberou v úvahu.
delivery_company varchar(256)
delivery_first_name varchar(64)
delivery_last_name varchar(64)
delivery_city varchar(64)
delivery_postcode varchar(6) Číslo s pěti znaky. Přebytečná mezera bude smazána.
delivery_address varchar(64)
delivery_phone varchar(64)
delivery_email varchar(64) Musí jít o validní e-mailovou adresu.
order_items array

Pole s produkty, které se mají objednat.
Každý prvek má povinné následující parametry:

  • code varchar(128) - kód produktu
  • quantity integer - počet kusů, musí být minimálně 1

Více detailů, co který parametr znamená, lze najít v celkové sekci s parametry.

Příklad, jak můžou vypadat JSON a XML data při zakládání nové objednávky, můžete vidět níže.
Pro různé formáty je potřeba pouze nastavit správně HTTP hlavičku Content-Type na application/json, případně application/xml.

{
    "delivery_id": 1,
    "payment_id": 2,
    "note": null,
    "id_number": "12345678",
    "vat_id": "CZ12345678",
    "billing_company": "Firma XXX",
    "billing_first_name": "Jan",
    "billing_last_name": "Novák",
    "billing_city": "Praha",
    "billing_postcode": "11000",
    "billing_address": "Pražská 1",
    "billing_phone": "+420 111 222 333",
    "billing_email": "mail@gmail.com",
    "delivery_equal_billing": false,
    "delivery_company": null,
    "delivery_first_name": "Marie",
    "delivery_last_name": "Nováková",
    "delivery_city": "Brno",
    "delivery_postcode": "61000",
    "delivery_address": "Brněnská 1",
    "delivery_phone": "+420 999 888 777",
    "delivery_email": "mail@seznam.cz",
    "terms_conditions" : true,
    "join_orders" : true,
    "orderItems": [
        {
            "code": "123-ABC-XYZ",
            "quantity": 1
        },
        {
            "code": "987-XXX-YYY",
            "quantity": 5
        }
    ]
}
<?xml version="1.0" encoding="UTF-8"?>
<response>
    <delivery_id>1</delivery_id>
    <payment_id>2</payment_id>
    <note/>
    <id_number>123456789</id_number>
    <vat_id>CZ12345678</vat_id>
    <billing_company>Firma XXX</billing_company>
    <billing_first_name>Jan</billing_first_name>
    <billing_last_name>Novák</billing_last_name>
    <billing_city>Praha</billing_city>
    <billing_postcode>11000</billing_postcode>
    <billing_address>Pražská 1</billing_address>
    <billing_phone>+420 111 222 333</billing_phone>
    <billing_email>mail@gmail.com</billing_email>
    <delivery_equal_billing>0</delivery_equal_billing>
    <delivery_company/>
    <delivery_first_name>Marie</delivery_first_name>
    <delivery_last_name>Nováková</delivery_last_name>
    <delivery_city>Brno</delivery_city>
    <delivery_postcode>61000</delivery_postcode>
    <delivery_address>Brněnská 1</delivery_address>
    <delivery_phone>+420 999 888 777</delivery_phone>
    <delivery_email>mail@seznam.cz</delivery_email>
    <terms_conditions>true</terms_conditions>
    <join_orders>0</join_orders>
    <orderItems>
        <code>123-ABC-XYZ</code>
        <quantity>1</quantity>
    </orderItems>
    <orderItems>
        <code>998</code>
        <quantity>5</quantity>
    </orderItems>
</response>

Návratové situace

Při úspěšném vložení objednávky vrátí API adekvátní HTTP kód 201 - Created a v těle zprávy stejná data jako pří zobrazení detailu viz sekce 7.3 Detail objednávky.
Díky nim můžete například získat ID objednávky nebo její celkovou cenu.

URL adresu na endpoint detailu vytvořené objednávky pak můžete najít v HTTP hlavičce location, popřípadě přímo v datech pod linkem self (viz HATEOAS).

Pokud se vložení nepodaří, většinou se jedná o jednu ze 3 chyb, na které API reaguje HTTP kódem a detaily v těle zprávy:

Špatný formát dat

Vrací chybu 400 - Bad request.

Je potřeba zkontrolovat správnou syntaxi JSON popřípadě XML. Doporučujeme vytvářet oba formáty za pomoci možností vašeho jazyka. V PHP použít funkci json_encode() php.net pro JSON, popřípadě třídu DOMDocument php.net pro XML.
Lepit formáty pomocí textu může vést k chybám.

Chyba ve validaci dat

Vrací chybu 422 - Data Validation Failed.

Je potřeba zkontrolovat tělo zprávy, kde je v poli výpis všech chyb.
Výpis může vypadat například takto:

{
    "status": "error",
    "data": [
        {
            "field": "billing_phone",
            "message": "Je zapotřebí vyplnit Telefon."
        },
        {
            "field": "delivery_email",
            "message": "Pro E-mail nebyla použita platná emailová adresa."
        },
        {
            "field": "terms_conditions",
            "message": "Musíte souhlasit s obchodními podmínkami"
        }
    ]
}
API hlídá pouze vstup parametrů, které zná. Pokud pošlete nějaká data například v parametru test_param, který neexistuje, API nevygeneruje chybu. Z tohoto chování vyplývá, že je nutné dávat si pozor na překlepy při zadávání dat.

Chyba v API

Vrací chybu 500 - Internal Server Error.

Jedná se o neošetřenou výjimku na straně API, kterou je dobré nahlásit na uvedený technický kontakt.

7.3 Detail

Poskytuje detail objednávky.

URL https://api.pet-distributor.cz/v1/orders/<id>/
Parametry
  • <id> - ID objednávky
Povolené metody GET, HEAD, OPTIONS, DELETE, PATCH, PUT
Zakázané metody -

Ukázka výstupu je stejná jako pro výpis s tím rozdílem, že v data není pole, ale rovnou detail objednávky.

Metodu DELETE, PATCH a PUT je možné provést pouze v případě, že se objednávka ještě nezačala zpracovávat.
Pokud takový požadavek zašlete na objednávku v jiném stavu, vrátí systém odpovídající HTTP kód 403 - Forbidden.

7.3.1 Smazání objednávky

Objednávku lze smazat zasláním HTTP požadavku DELETE na adresu detailu objednávky v případě, že je stále ve stavu 1, tedy nová.
Jakmile se objednávka začne vyřizovat, není možné s ní nijak manipulovat.

Pokud mazání proběhne v pořádku, vrátí systém tomu odpovídající HTTP kód 204 - No Content. Jak název napovídá, v těle zprávy není žádný obsah.

7.3.2 Aktualizace objednávky

Objednávku lze editovat zasláním dat v těle požadavku HTTP metodou PUT nebo PATCH na adresu detailu objednávky. To je možné pouze v případě, že je objednávka stále ve stavu 1, tedy nová.
Jakmile se objednávka začne vyřizovat, není možné s ní nijak manipulovat.

Aktualizace objednávky probíhá jejím přepsáním. Pokud některý parametr nepošlete, zůstává původní.

Zasláním parametru s prázdnou hodnotou tuto hodnotu smažete / přepíšete prázdným místem. Pokud například chcete jen aktualizovat položky objednávky, stačí zaslat parametr orderItems.

Jediným povinným parametrem je pole položek objednávky orderItems. To je nutné zasílat vždy znovu. Jedním zasláním tak vyřešíte přidání i odebrání položek.
Pokud si seznam položek objednávky sami neevidujete, můžete použít API k jejich načtení v detailu objednávky.

Struktura parametrů dat pro aktualizaci je stejná jako u vytváření nové objednávky.

Pokud aktualizace proběhne v pořádku, vrátí systém HTTP kód 200 - OK. V těle zprávy jsou pak data z aktualizované objednávky.

8. Kategorie

Poskytuje seznam kategorií s jejich vzájemným provázáním.

8.1 Parametry

Seznam parametrů kategorií nacházejících se ve výpisu i detailu s jich popisem.

Klíč Poznámka
id Unikátní identifikátor, dle něž lze párovat.
name Název.
description Popis v HTML formátu.
parent_id Identifikátor rodiče.

8.1.1 Expand

Více informací v sekci Expand.
API pro kategorie nenabízí žádné dodatečné informace prostřednictvím expand.

8.1.2 Links

Více informací v sekci HATEOAS.

Klíč Popis
self Link na aktuální položku.
parent Link nadřazenou kategorii.

8.2 Výpis

Poskytuje seznam všech kategorií.

URL https://api.pet-distributor.cz/v1/categories/
Povolené metody GET, HEAD, OPTIONS
Zakázané metody POST

Ukázka, jak může výpis vypadat:

{
    "status": "ok",
    "data": [
        {
            "id": 1,
            "name": "Kategorie XXX",
            "parent_id": null,
            "description": "<p>Popis kategorie</p>",
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/categories/1/"
                }
            }
        },
        {
            "id": 2,
            "name": "Kategorie YYY",
            "parent_id": 1,
            "description": null,
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/categories/2/"
                },
                "parent": {
                    "href": "https://api.pet-distributor.cz/v1/categories/1/"
                }
            }
        }
    ]
}
Pro kategorii plánujeme speciální výpis v podobě stromu.

8.3 Detail

Poskytuje detail kategorie.

URL https://api.pet-distributor.cz/v1/categories/<id>/
Parametry
  • <id> - ID kategorie
Povolené metody GET, HEAD, OPTIONS
Zakázané metody PATCH, PUT, DELETE

Ukázka výstupu je stejná jako pro výpis s tím rozdílem, že v data není pole, ale rovnou detail kategorie.

9. Značky

9.1 Parametry

Seznam parametrů značek nacházejících se ve výpisu i detailu s jich popisem.

Klíč Poznámka
id Unikátní identifikátor, dle něž lze párovat.
name Název značky.

9.1.1 Expand

Více informací v sekci Expand.
API pro značky nenabízí žádné dodatečné informace prostřednictvím expand.

9.1.2 Links

Více informací v sekci HATEOAS.

Klíč Popis
self Link na aktuální položku.

9.2 Výpis

Poskytuje seznam všech značek.

URL https://api.pet-distributor.cz/v1/brands/
Povolené metody GET, HEAD, OPTIONS
Zakázané metody POST

Ukázka, jak může výpis vypadat:

{
    "status": "ok",
    "data": [
        {
            "id": 1,
            "name": "Značka XXX",
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/brands/1/"
                }
            }
        },
        {
            "id": 2,
            "name": "Značka YYY",
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/brands/2/"
                }
            }
        }
    ]
}

9.3 Detail

Poskytuje detail značky.

URL https://api.pet-distributor.cz/v1/brands/<id>/
Parametry
  • <id> - ID značky
Povolené metody GET, HEAD, OPTIONS
Zakázané metody PATCH, PUT, DELETE

Ukázka výstupu je stejná jako pro výpis s tím rozdílem, že v data není pole, ale rovnou detail značky.

10. Stavy objednávek

10.1 Parametry

Seznam parametrů stavů objednávek nacházejících se ve výpisu i detailu s jich popisem.

Klíč Poznámka
id Unikátní identifikátor, dle něž lze párovat.
name Název.
complete Bool hodnota, zda stav objednávky označuje objednávku jako hotovou/dokončenou.

10.1.1 Expand

Více informací v sekci Expand.
API pro stavy objednávek nenabízí žádné dodatečné informace prostřednictvím expand.

10.1.2 Links

Více informací v sekci HATEOAS.

Klíč Popis
self Link na aktuální položku.

10.2 Výpis

Poskytuje seznam všech stavů objednávek.

URL https://api.pet-distributor.cz/v1/statuses/
Povolené metody GET, HEAD, OPTIONS
Zakázané metody POST

Ukázka, jak může výpis vypadat:

{
    "status": "ok",
    "data": [
        {
            "id": 1,
            "name": "Nová",
            "complete": false,
            "_links": {
                "self": {
                    "href": "http://api.pet-distributor.cz/v1/statuses/1/"
                }
            }
        },
        {
            "id": 2,
            "name": "Odesláno",
            "complete": true,
            "_links": {
                "self": {
                    "href": "http://api.pet-distributor.cz/v1/statuses/2/"
                }
            }
        }
    ]
}

10.3 Detail

Poskytuje detail stavu objednávky.

URL https://api.pet-distributor.cz/v1/statuses/<id>/
Parametry
  • <id> - ID stavu objednávky
Povolené metody GET, HEAD, OPTIONS
Zakázané metody PATCH, PUT, DELETE

Ukázka výstupu je stejná jako pro výpis s tím rozdílem, že v data není pole, ale rovnou detail stavu objednávky.

11. Dopravy

11.1 Parametry

Seznam parametrů doprav nacházejících se ve výpisu i detailu s jich popisem.

Klíč Poznámka
id Unikátní identifikátor, dle něž lze párovat.
name Název.
price Cena bez DPH.
payments_id Pole s ID plateb, které můžete pro tuto dopravu vybrat.
description Popis v HTML formátu.

11.1.1 Expand

Více informací v sekci Expand.
API pro dopravy nenabízí žádné dodatečné informace prostřednictvím expand.

11.1.2 Links

Více informací v sekci HATEOAS.

Klíč Popis
self Link na aktuální položku.

11.2 Výpis

Poskytuje seznam všech doprav.

URL https://api.pet-distributor.cz/v1/deliveries/
Povolené metody GET, HEAD, OPTIONS
Zakázané metody POST

Ukázka, jak může výpis vypadat:

{
    "status": "ok",
    "data": [
        {
            "id": 1,
            "name": "Geis",
            "price": 99,
            "payments_id": [
                1,
                2
            ],
            "description": "<p>Popis dopravy</p>",
            "_links": {
                "self": {
                    "href": "http://api.pet-distributor.cz/v1/deliveries/1/"
                }
            }
        },
        {
            "id": 2,
            "name": "Český pošta",
            "price": 120,
            "payments_id": [
                3
            ],
            "description": null,
            "_links": {
                "self": {
                    "href": "http://api.pet-distributor.cz/v1/deliveries/2/"
                }
            }
        }
    ]
}

11.3 Detail

Poskytuje detail dopravy.

URL https://api.pet-distributor.cz/v1/deliveries/<id>/
Parametry
  • <id> - ID dopravy
Povolené metody GET, HEAD, OPTIONS
Zakázané metody PATCH, PUT, DELETE

Ukázka výstupu je stejná jako pro výpis s tím rozdílem, že v data není pole, ale rovnou detail dopravy.

12. Platby

12.1 Parametry

Seznam parametrů plateb nacházejících se ve výpisu i detailu s jich popisem.

Klíč Poznámka
id Unikátní identifikátor, dle něž lze párovat.
name Název.
price Cena bez DPH.
description Popis v HTML formátu.

12.1.1 Expand

Více informací v sekci Expand.
API pro platby nenabízí žádné dodatečné informace prostřednictvím expand.

12.1.2 Links

Více informací v sekci HATEOAS.

Klíč Popis
self Link na aktuální položku.

12.2 Výpis

Poskytuje seznam všech plateb.

URL https://api.pet-distributor.cz/v1/payments/
Povolené metody GET, HEAD, OPTIONS
Zakázané metody POST

Ukázka, jak může výpis vypadat:

{
    "status": "ok",
    "data": [
        {
            "id": 1,
            "name": "Dobírka",
            "price": 30,
            "description": null,
            "_links": {
                "self": {
                    "href": "http://api.pet-distributor.cz/v1/payments/1/"
                }
            }
        },
        {
            "id": 2,
            "name": "Bankovní převod",
            "price": 0,
            "description": "<p>Bankovní účet: XXX-XXX</p>",
            "_links": {
                "self": {
                    "href": "http://api.pet-distributor.cz/v1/payments/2/"
                }
            }
        }
    ]
}

12.3 Detail

Poskytuje detail platby.

URL https://api.pet-distributor.cz/v1/payments/<id>/
Parametry
  • <id> - ID platby
Povolené metody GET, HEAD, OPTIONS
Zakázané metody PATCH, PUT, DELETE

Ukázka výstupu je stejná jako pro výpis s tím rozdílem, že v data není pole, ale rovnou detail platby.

13. Bankovní účty

13.1 Parametry

Seznam parametrů bankovních účtů nacházejících se ve výpisu i detailu s jich popisem.

Klíč Poznámka
id Unikátní identifikátor, dle něž lze párovat.
number Číslo účtu.
code Kód banky.
bank Název banky.
iban IBAN. wikipedia.cz
swift SWIFT. wikipedia.cz

13.1.1 Expand

Více informací v sekci Expand.
API pro bankovní účty nenabízí žádné dodatečné informace prostřednictvím expand.

13.1.2 Links

Více informací v sekci HATEOAS.

Klíč Popis
self Link na aktuální položku.

13.2 Výpis

Poskytuje seznam všech bankovních účtů.

URL https://api.pet-distributor.cz/v1/accounts/
Povolené metody GET, HEAD, OPTIONS
Zakázané metody POST

Ukázka, jak může výpis vypadat:

{
    "status": "ok",
    "data": [
        {
            "id": 1,
            "number": "2631172369",
            "code": "0800",
            "bank": "Česká spořitelna",
            "iban": "CZ43 0800 0000 0026 3117 2369",
            "swift": "GIBACZPX",
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/accounts/1/"
                }
            }
        },
        {
            "id": 2,
            "number": "1846682273",
            "code": "0800",
            "bank": "Česká spořitelna",
            "iban": "CZ04 0800 0000 0018 4668 2273",
            "swift": "GIBACZPX",
            "_links": {
                "self": {
                    "href": "https://api.pet-distributor.cz/v1/accounts/2/"
                }
            }
        }
    ]
}

13.3 Detail

Poskytuje detail bankovního účtu.

URL https://api.pet-distributor.cz/v1/accounts/<id>/
Parametry
  • <id> - ID bankovního účtu
Povolené metody GET, HEAD, OPTIONS
Zakázané metody PATCH, PUT, DELETE

Ukázka výstupu je stejná jako pro výpis s tím rozdílem, že v data není pole, ale rovnou detail bankovního účtu.

14. Faktury

14.1 Parametry

Seznam parametrů faktur nacházejících se ve výpisu i detailu s jich popisem.

Klíč Poznámka
variable_code Variabilní symbol.
constant_code Konstantní symbol.
price Celková cena bez DPH.
price_vat Celková cena s DPH.
date Datum vystavení faktury.
date_tax Datum zdanitelného plnění.
date_due Datum splatnosti.
text Text dokladu.
billing_company Název subjektu (fakturační).
billing_city Město (fakturační).
billing_postcode Poštovní směrovací číslo (fakturační).
billing_address Ulice/adresa (fakturační).
billing_phone Telefon (fakturační).
billing_email E-mail (fakturační).
billing_id_number IČ (fakturační).
billing_vat_id DIČ (fakturační).
delivery_company Název subjektu (doručovací).
delivery_city Město (doručovací).
delivery_postcode Poštovní směrovací číslo (doručovací).
delivery_address Ulice/adresa (doručovací).
shop_company Název subjektu (dodavatel).
shop_city Město (dodavatel).
shop_postcode Poštovní směrovací číslo (dodavatel).
shop_address Ulice/adresa (dodavatel).
shop_phone Telefon (dodavatel).
shop_email E-mail (dodavatel).
shop_id_number IČ (dodavatel).
shop_vat_id DIČ (dodavatel).
order_id ID objednávky.
payment_id ID platby.
account_id ID bankovního účtu.
items

Seznam položek objednávky. Položky mají následující parametry:

  • code - kód produktu
  • unit - jednotka množství
  • vat - číselná hodnota DPH
  • quantity - počet položek
  • name - jméno produktu
  • unit_price - cena za jednotku bez DPH
  • price - cena za všechny jednotky bez DPH
  • price_vat - hodnota DPH za všechny jednotky
  • price_sum - kompletní cena s DPH za všechny jednotky

14.1.2 Links

Více informací v sekci HATEOAS.

Klíč Popis
self Link na aktuální položku.
order Link objednávku, ze které faktura vychází.
payment Link typ platby.
account Link bankovní účet.

14.2 Výpis

Poskytuje seznam všech bankovních účtů.

URL https://api.pet-distributor.cz/v1/invoices/
Povolené metody GET, HEAD, OPTIONS
Zakázané metody POST

Ukázka, jak může výpis vypadat:

{
    "status": "ok",
    "data": [
        {
            "variable_code": "160101234",
            "date": "2016-11-09",
            "date_tax": "2016-11-09",
            "date_due": "2016-11-23",
            "text": "Fakturujeme Vám dle Vaší objednávky:",
            "billing_company": "Firma XXX",
            "billing_city": "Blansko",
            "billing_postcode": "678 01",
            "billing_address": "Nádražní 1",
            "billing_phone": "+420 111 222 333",
            "billing_email": "mail@gmail.com",
            "billing_id_number": "1234567",
            "billing_vat_id": "CZ12345678",
            "delivery_company": "Firmy YYY",
            "delivery_city": "Praha 2",
            "delivery_postcode": "120 00",
            "delivery_address": "Pražská 1",
            "shop_company": "ProfiSales s.r.o.",
            "shop_city": "Rájec-Jestřebí",
            "shop_postcode": "679 02",
            "shop_address": "Petrovice ",
            "shop_phone": "720025069,721158775",
            "shop_email": "profisales@profisales.cz",
            "shop_id_number": "29261783",
            "shop_vat_id": "CZ29261783",
            "order_id": 123,
            "payment_id": 1,
            "account_id": 2,
            "constant_code": "0308",
            "price": "2166.00",
            "price_vat": "2491.00",
            "items": [
                {
                    "code": "317",
                    "unit": "ks",
                    "vat": 15,
                    "quantity": 3,
                    "name": "ALAVIS Triple Blend",
                    "unit_price": "722.00",
                    "price": "2166.00",
                    "price_vat": "324.90",
                    "price_sum": "2490.90"
                },
                {
                    "code": "",
                    "unit": "",
                    "vat": 21,
                    "quantity": 1,
                    "name": "Geis",
                    "unit_price": "0.00",
                    "price": "0.00",
                    "price_vat": "0.00",
                    "price_sum": "0.00"
                }
            ],
            "_links": {
                "self": {
                    "href": "http://api.pet-distributor.cz/v1/invoices/123/"
                },
                "order": {
                    "href": "http://api.pet-distributor.cz/v1/orders/123/"
                },
                "payment": {
                    "href": "http://api.pet-distributor.cz/v1/payments/1/"
                },
                "account": {
                    "href": "http://api.pet-distributor.cz/v1/accounts/2/"
                }
            }
        },
        ...
    }

14.3 Detail

Poskytuje detail bankovního účtu.

URL https://api.pet-distributor.cz/v1/invoices/<id>/
Parametry
  • <id> - ID bankovního účtu
Povolené metody GET, HEAD, OPTIONS
Zakázané metody PATCH, PUT, DELETE

Ukázka výstupu je stejná jako pro výpis s tím rozdílem, že v data není pole, ale rovnou detail bankovního účtu.

A. Historie verzí (changelog)

Všechny významné změny API a dokumentace budou zaznamenány do této sekce. Tento projekt se drží sématického verzování.

V přípravě

  • Parametry pro úpravu výpisů položek

1.5.0 - 2017-06-29

Přidává

  • parametr produktu 'numeric_code'

1.4.0 - 2017-04-27

Přidává

  • možnost aktualizovat nové objednávky

1.3.0 - 2017-03-03

Přidává

  • parametr produktu 'not_sold'

Mění

  • endpointy produktů obsahují i již neprodávané produkty

1.2.0 - 2016-11-25

Přidává

  • stavy skladů
  • parametr produktu 'amount_in_box'

1.1.0 - 2016-11-14

Přidává

  • faktury
  • bankovní účty

1.0.0 - 2016-10-08

Přidává

  • Finalizuje autentizaci, produkty, objednávky, kategorie, značky, stavy objendávek, dopravy a platby

Mění

  • Upravuje a dolaďuje řadu sekcí

0.1.0 - 2016-08-04

Přidává

  • Init verze
  • Počáteční dokumentace
  • Základní funkcionalita
Dokumentace je vždy aktuální k současné verzi systému (1.5.0).