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.
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.
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:
U API metod, které vracejí seznamy entit, lze tyto seznamy vždy filtrovat a řadit pomocí následujících parametrů v URL:
?limit=5
vrátí pouze 5 prvních záznamů.?offset=200
vrátí seznam počínající 201. záznamem.,
. Vlastnosti, před jejichž název uvedete -
, se použijí k řazení v sestupném pořadí. Například ?order=name,-id
vrátí seznam seřazený nejprve podle jména a poté sestupně podle ID, ?order=users.email
vrátí seznam seřazený podle e-mailu propojené entity uživatele.properties
můž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 vlastnosti id
a vlastnosti name
a z napojené entity uživatele pouze vlastnost id
,properties=-name,users.-name
- výběr všech vlastností kromě name
a napojené entity uživatele kromě jejich vlastnosti name
,properties=id,users.id,users.name
- výběr pouze vlastnosti id
a vlastností id
a name
u napojené entity uživatele,properties=id,users{id,name}
- předchozí příklad zkrácený pomocí složených závorek.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
, instanceof
a 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.