-
Filmy, knihy, hry
-
Dětské zboží
-
Elektronika
-
Bílé zboží
-
Dům a zahrada
-
Chovatelství
-
Auto-moto
-
Oblečení a móda
-
Kosmetika a zdraví
-
Sport
-
Hobby
-
Jídlo a nápoje
-
Stavebniny
Nápověda
API
API je rozhraní, přes které mohou se Shopasem komunikovat ostatní aplikace a získávat z vašeho e‑shopu potřebná data. API je teprve na začátku svého vývoje, ale postupně ho učíme novým věcem a brzy již zvládne většinu toho, co nyní musíte v e‑shopu řešit vy.
REST API pro váš e‑shop je dostupné na adrese <doména-vašeho-eshopu>/api/, například https://www.mujeshop.cz/api/. Komunikace probíhá ve formátu JSON a je zabezpečena API klíčem, který je nutné posílat v HTTP hlavičce Api-Key každého požadavku na API.
Kromě toho je zapotřebí v požadavku zasílat HTTP hlavičku Content-Type s hodnotou application/json.
Získání API klíče
API klíč je na Shopasu vždy svázaný s konkrétním provozovatelem e‑shopu. Získat ho můžete na stránce Editace provozovatele na záložce API klíč. Pokud jste žádný API klíč dosud nepoužívali, klikněte na Vygenerovat nový API klíč. Nový API klíč se objeví v poli před tlačítkem. Jedná se o dlouhý řetězec znaků.
API klíč je citlivý údaj, chovejte se k němu prosím stejně obezřetně jako ke svému přístupovému heslu. Kdokoliv získá váš API klíč, může přes API získávat důležité údaje o vašem e‑shopu! Pokud si nejste jistí, zda váš API klíč někdo nezískal, můžete si zde opětovným kliknutím na tlačítko vygenerovat klíč nový. Původní klíč tím okamžitě ztratí platnost a přestane fungovat.
Pomocí API klíče provozovatele můžete získávat informace o všech e‑shopech, které tento provozovatel na Shopasu provozuje.
Metody
Získání objednávek
GET /api/orders
Vrací seznam objednávek na vašem e‑shopu. Odpověď má následující strukturu:
Array<{
id: string, // ID objednávky v rámci Shopasu
number: string, // číslo objednávky na vašem e‑shopu
shopId: string, // ID e‑shopu v rámci Shopasu
name: string, // Jméno zákazníka
email: string, // E-mail zákazníka
phone: string, // Telefonní číslo zákazníka
invoiceAddress: { // Fakturační adresa
street: string, // Ulice
houseNumber: string, // Číslo popisné/orientační
city: string, // Město
zipCode: string, // PSČ
country: string, // Stát
isCompany: boolean, // Objednávám na firmu
companyName: string, // Název firmy, nepovinné
registrationNumber: string, // IČO, nepovinné
vatId: string, // DIČ, nepovinné
}
deliveryAddress: { // Doručovací adresa
street: string, // Ulice
houseNumber: string, // Číslo popisné/orientační
city: string, // Město
zipCode: string, // PSČ
country: string, // Stát
name: string, // Jméno příjemce
}
status: "Created" | "Paid" | "Confirmed" | "Dispatched" | "Not Picked Up" | "Finished" | "Canceled", // Stav objednávky
deliveryMethod: { // Způsob dopravy
name: string, // Název způsobu dopravy
countries: Array<string>, // Země dostupné pro tento způsob dopravy
type: string, // Typ způsobu dopravy
description: string, // Popis způsobu dopravy
defaultPrice: { // Základní cena dopravy
price: number, // Částka
vatRate: "high" | "low" | "lowest" | "none", // Sazba DPH
},
includeOnProductDetail: boolean, // Zobrazovat způsob dopravy na detailu produktu
},
paymentMethod: { // Způsob platby
name: string, // Název způsobu platby
price: { // Cena platby
price: number, // Částka
vatRate: "high" | "low" | "lowest" | "none", // Sazba DPH
},
shouldCollectOnDelivery: boolean, // Dobírka
paymentGatewayAlias: string, // Název platební brány
emailContent: string, // Text e-mailu u tohoto způsobu platby
shouldAttachInvoice: boolean, // Zda k e-mailu přiložit vygenerovaný doklad
},
deliveryPrice: number, // Celková částka za dopravu a platbu
price: {
prices: { // Rozpad ceny podle sazeb DPH
high?: number // Celková částka v základní sazbě DPH
low?: number // Celková částka ve snížené sazbě DPH
lowest?: number // Celková částka ve druhé snížené sazbě DPH
none?: number // Celková částka s nulovou sazbou DPH
}
},
totalPrice: number, // Celková částka včetně dopravy a platby
createdAt: Date, // Datum vytvoření
updatedAt: Date, // Datum poslední změny
packageId?: string, // ID balíku v Zásilkovně
}>Kromě výše uvedených vlastností objednávky lze pomocí parametru properties (více informací najdete níže v kapitole obecné parametry) do odpovědi zahrnout tyto propojené entity:
- items - seznam položek objednávky,
- seller - aktuální údaje o provozovateli e‑shopu,
- person - údaje o zákazníkovi,
- messages - historie objednávky.
Obecné parametry
U API metod, které vracejí seznamy entit, lze tyto seznamy vždy filtrovat a řadit pomocí následujících parametrů v URL:
- limit - Omezuje maximální počet vrácených záznamů. Výchozí hodnota je 100. Například
?limit=5vrátí pouze 5 prvních záznamů. - offset - Počet záznamů od začátku, které se mají přeskočit. Například
?offset=200vrátí seznam počínající 201. záznamem. - order - Seznam vlastností či cest k vlastnostem, které se mají použít k řazení záznamů, oddělený čárkou
,. Vlastnosti, před jejichž název uvedete-, se použijí k řazení v sestupném pořadí. Například?order=name,-idvrátí seznam seřazený nejprve podle jména a poté sestupně podle ID,?order=users.emailvrátí seznam seřazený podle e-mailu propojené entity uživatele. - properties - Seznam vlastností či cest k vlastnostem, které se mají zahrnout do odpovědi nebo naopak z odpovědi vyloučit. Výchozí nastavení je takové, že se u každé entity vrací všechny jeho vlastnosti s výjimkou propojených entit a jejich vlastností. (Propojené entity jsou takové entity, které jsou se získávanou entitou svázané pomocí relační vazby.) Pomocí parametru
propertiesmůžete buď určit, které vlastnosti chcete do odpovědi zahrnout, nebo dáte-li před název vlastnosti minus-, tuto vlastnost z odpovědi vyloučíte. Stejným způsobem můžete zahrnout či vyloučit i vlastnosti z propojených entit. Cesta k vlastnostem v propojených entitách se odděluje pomocí tečky.. Pro zkrácení zápisu můžete vlastnosti seskupovat pomocí složených závorek. Příklady:properties=users- výběr všech vlastností včetně napojené entity uživatele,properties=id,users- výběr pouze vlastnosti id získávané entity a celé napojené entity uživatele,properties=id,name,users.d- výběr pouze vlastnostiida vlastnostinamea z napojené entity uživatele pouze vlastnostid,properties=-name,users.-name- výběr všech vlastností kroměnamea napojené entity uživatele kromě jejich vlastnostiname,properties=id,users.id,users.name- výběr pouze vlastnostiida vlastnostíidanameu napojené entity uživatele,properties=id,users{id,name}- předchozí příklad zkrácený pomocí složených závorek.
- query - Podmínka ve formátu Doctrine DQL, která se použije pro filtraci získaných entit. Alias kořenové entity je
e, proto musí být všechna pole a asociace prefixována pomocíe.. Použití DQL je omezeno sandboxem, použití joinů, subselectů, výrazůexists,instanceofa vstupních parametrů je zakázáno. Příklady:?query=e.createdAt < '2021-01-01'- Vrátí pouze entity vytvořené před 1. lednem 2021.?query=e.name LIKE 'A%'- Vrátí pouze entity se jménem začínajícím na A.
Odpovědi API vracející seznamy entit obsahují v HTTP hlavičkách header Total-Count, který vrací celkový neofiltrovaný počet záznamů, který je na serveru k dispozici.
Podpora pro provozovatele e-shopů
