Popis BookUP API
API slouží pro distribuci digitálního obsahu, jako jsou e-knihy, nebo audioknihy, umožnuje získání a aktualizaci metadat zboží, cen, obálek a audio náslechů. Zpřístupňuje zboží ke stažení pro koncové uživatele. Rozsah dostupného katalogu je závislý na smlouvě o distribuci.
Typy a formáty poskytované na API
- Audioknihy ve formátu mp3
- E-knihy ve formátu epub nebo pdf
Typický průchod na API
- Autentizace na API
- Prvotní načtení kompletního katalogu
- Aktualizace katalogu
- Průběžné reportování prodejů
- Získání obsahu ke stažení
API dokumentace
Zde uvádíme obecné shrnutí a předpoklady pro práci s API. Popis vstupních parametrů, obsah odpovědí a seznam výjimek/chybových kódů je pak rozepsán u nápovědy jednotlivých metod.
Autentizace
- Je postavena na technologii JWT tokenu.
- Token je potřeba generovat pro každé volání všech metod na API.
- Pro generování tokenu distributor obdrží potřebné parametry "jwt_secret" a "dist_id" a které jsou rozdílné pro testovací a provozní prostředí.
- Obecný popis technologie naleznete https://jwt.io/.
- Ukázkový příklad generování JWT tokenu pro Postman naleznete níže v sekci příklady.
Základní rozdělení API
Metody API jsou rozděleny do základních skupin dle typu obsahu (z důvodu rozdílného datového výstup), nebo účelu použití.
Skupiny API metod audiobooks a ebooks fungují v principu stejně, liší se pouze v názvech v některých metadatech a v detailech stažení některých typů souborů.
-
Audiobooks slouží k přístupu k datům audioknih.
catalogue_export_get_filecatalogue_updatescatalogue_updates_idscatalogue_listdownloaddownload_packagestream_track
-
Ebooks slouží k přístupu k datům e-knih.
catalogue_export_get_filecatalogue_updatescatalogue_updates_idscatalogue_listdownloaddownload_addon
-
Reporting slouží k reportování nákupu, či storna objednávky položek a je společný pro oba typy obsahu.
report_paymentreport_payment_cancel
- Systémové metody.
ping může sloužit pro monitoring ze strany partnera. Pokud by partner použil pro monitoring nevhodné metody, jako získání katalogu, je zde riziko zablokování přístup na API z důvodu nepřiměřené zátěže.categories vrací seznam všech aktivních kategorií.
Princip práce s katalogem
Systém generuje minimálně jednou každý den export celého katalogu. Následně existují 2 možnosti jak katalog aktualizovat. Na diagramech jsou zobrazeny oba postupy průchodu pro získání a aktualizaci katalogu.
Aktulálně doporučovaným přístupem je načtení seznamu změněných ID položek a jejich následné zpracování pomocí category_list. Tato metoda poskytuje efektivnější přístup ke zpracování změnových položek a v případě větších změn katalogu, si distributor může tyto změny zpracovávat po dávkách.
aktualizace katalogu pomocí seznamu id (doporučovaný způsob)
sequenceDiagram
Partner->>+Bookup: catalogue_export_get_file
Bookup->>Partner: URL a čas generování
note over Partner: Import dat
Partner->>Bookup: catalogue_updates()
Bookup->>Partner: Id změněných položek
Partner->>Bookup: catalogue_list()
Bookup->>Partner: Metadata požadovaných položek
note over Partner: Import dat
aktualizace katalogu pomocí přírůstkové metody
sequenceDiagram
Partner->>+Bookup: catalogue_export_get_file
Bookup->>Partner: URL a čas generování
note over Partner: Import dat
Partner->>Bookup: catalogue_updates()
Bookup->>Partner: Metadata požadovaných položek
note over Partner: Import dat
Stažení celého katalogu
Výchozí metoda pro první načtení kompletního katalogu je catalogue_export_get_file. Výstupem je url na JSON soubor s kompletním katalogem a informací, kdy byl tento soubor naposledy vygenerován a tedy k jakému datum jsou informace v něm aktuální (generuje se typicky 1x denně mezi 1:00-3:00).
Po prvotním importu katalogu je možné používat metody catalogue_updates_ids, catalogue_list a catalogue_updates pro načtení pouze změněných položek. Nicméně doporučujeme zkontrolovat pomocí metody catalogue_export_get_file kompletní katalog, alespoň jednou za 14 dní, aby se odstranily případné chyby způsobené časovými překryvy, případně nějakými většími změnami v katalogu.
Při implementaci je potřeba počítat s tím, že s ohledem na typ a množství dostupného zboží, může mít výsledný JSON soubor velikost v řádech desítek MB.
Stažení změn katalogu
Zjištění změn v katalogu.
API poskytuje dva způsoby, jak získat informace o aktualizovaném zboží. Aktuálně doporučovaný způsob vrací datově úsporný seznam ID zboží, který lze pak použít pro získání metadat v metodě catalogue_list a takovýto seznam lze dle potřeby rozdělit do dávek . Původní způsob poskytuje plná metadata všech změněnch položek, a v případě vetšího množství změn, mohou být výstupní data obsáhlá.
Stažení souborů k položkám katalogu
Stahování probíhá pomocí metody download, stream_track, download_package či download_addon, které vrací url pro stažení požadovaného souboru. Většina souborů je k dispozici ihned ke stažení. Vydané linky mají omezenou platnost a nejsou určeny k ukládání na straně partnera. Soubory také obsahují DRM, proto je potřeba při žádosti o ně předat relevantní data.
Odložené stahování:
- Platí jak pro eknihy tak audioknihy pro metody
download a download_package. (Tzn netýká se streamingu ani addons)
- Je potřeba počítat s čekáním na stažení souborů. Soubory jsou připravovány na straně serveru a může chvíli trvat, než jsou k dispozici ke stažení. To je indikováno HTTP hlavičkou Retry-After. Typická doba čekání je 5s, ale je závislá na velikosti souboru. Na API existují soubory větší než jednotky MB jejichž příprava trvá déle.
- Retry-After posílá až HTTP GET na stažení URL (typicky stav 307), nikoli volání JSON-RPC
download / download_package.
- U audioknih mohou vybraní partneři dočasně zvolit downloader parametrem
downloader_version (1 = původní host abdwn, 2 = nový host dwn). Bez parametru se použije výchozí verze partnera. Parametr mimo allowlist se ignoruje. Jde o přechodný souběh, po dokončení migrace se zruší.
- Výsledná velikost staženého souboru se drobně liší oproti prezentovaným velikostem souborů v metadatach na API u položek. Rozdíl velikosti je způsoben přidáním DRM.
Specifika audioknih:
- Pro streaming obsahu slouží link vygenerovaný pomocí
stream_track. Link pro jednotlivý track vygenerovaný přes download není určen ke streamingu a v případě využití tímto způsobem se partner vystavuje riziku nefunkčnosti, či odstavení API.
- Pokud požadovaný download obsahuje pouze jeden soubor (přímo track, nebo package s jedním souborem) vrací se přímo tento soubor bez obalového ZIP kontejneru
- Metody
download a download_package mají limit 2 GB. U souborů větších než 2 GB je nutné respektovat atribut download_preference, který indikuje požadované rozdělení downloadu. Partner musí atribut vyhodnotit a stáhnout obsah přes odpovídající entitu. Atribut nesmí ignorovat, jinak se soubor nevytvoří.
collection — celá audiokniha najednou (download s item_id kolekce).volume — nelze stáhnout jako celek, pouze po jednotlivých volume (item_id volume).track — nelze stáhnout jako celek ani po volume, pouze po jednotlivých trackách (item_id tracku).
- Od r. 2024 mohou mít audioknihy také přiděleno ISBN. Proto je tento atribut volitelný. Ne všechny starší audioknihy budou mít zpětně doplněné ISBN. Předpokládáme, že proces doplnění může trvat i několik let, či dokonce nebude dokončen nikdy.
Specifika e-knih:
- mobi soubory se vytvářejí konverzí z formátu epub a jejich příprava proto trvá déle než ostatních formátů.
Doplňkové soubory (addons)
- Některé zboží může obsahovat doplňkové soubory, aktuálně se to zatím týká e-knih. Jde typicky o soubory zdarma jako například testy k učebnicím, nebo audiosoubory.
pro stažení doplňkových souborů slouží metoda download_addon, doplňkové soubory mohou mít libovolný mime-type i velikost.
Chybové stavy při stažení ticketu
Následující chyby vrací HTTP GET na URL, kterou vrátily metody download (audioknihy i e-knihy) a download_package (audioknihy). Nejde o chybu JSON-RPC volání, které URL vydá. Text níže je status_message odpovědi.
- Chyba při sestavení souboru ke stažení. Ticket se nepodařilo sestavit, soubor nelze vygenerovat (HTTP 422). Text:
Chyba sestavení souboru ke stažení, na opravě pracujeme, opakujte stažení později prosím, případně kontaktuje zákaznický servis prodejce. Integrátor stažení zopakuje později. Když chyba přetrvává, kontaktuje zákaznický servis prodejce.
- Vypršení času sestavení. Sestavení souboru nestihlo limit (HTTP 422). Text:
Časový limit pro sestavení souboru ke stažení vypršel, opakujte stažení později prosím, případně kontaktujte zákaznický servis prodejce. Stejný postup: zopakovat stažení později, při přetrvávající chybě kontaktovat zákaznický servis prodejce.
- Expirovaný ticket. Platnost ticketu ke stažení vypršela (HTTP 410). Text:
Ticket vypršel. Integrátor vyžádá nový ticket novým voláním download nebo download_package. Původní URL znovu nepoužívá.
Omezení počtu žádostí o linky na API
Volání metod ebooks/download, ebooks/download_addon, audiobooks/download a audiobooks/download_package podléhá omezení počtu žádostí.
Hodnoty limitu jsou řízeny interně na straně serveru a jedná se o globální nastavení pro celé API. Pro unikátní kombinaci parametrů user_id, item_id a order_id je možné odeslat maximálně 10 požadavků v časovém okně 60 sekund. Při překročení tohoto limitu vrátí API chybovou odpověď (HTTP status:429 status v json datech odpovědi:429).
Životní cyklus linku pro streaming
Proces streamingu placeného obsahu využívá odkazy s dynamickou platností, která je řízena dvěma parametry:
- Počáteční expirace (expiration): Určuje, jak dlouho je nově vygenerovaný link platný, než ho uživatel poprvé použije. (Aktuálně: 24 hodin)
- Prodloužená expirace (expiration_prolong): Jakmile uživatel zahájí streaming, původní expirace se nahradí tímto kratším časovým limitem pro všechny následující požadavky na data. (Aktuálně: 1 hodina)
Pokud link není využit v rámci těchto dvou po sobě jdoucích časových limitů, stává se neplatným. Pro pokračování v poslechu je pak vždy nutné prostřednictvím API vygenerovat nový link.
Zpracování katalogu pro prezentaci a prodej
Jedním z nejdůležitějších aspektů zpracování katalogu a zařazení do nabídky je vyhodnocení dostupnosti/platnosti licence, cenotvorba, zařazení do stromu kategorii. Zde jsou popsány obecně, ve větším detailu včetně popisu jednotlivých hodnot v popisu každé metody.
Prodejnost zboží
Je řešena kombinací hodnot stavu zboží a dostupnosti v čase od a do.
- Zboží k prodeji musí mít platnou licenci viz "tabulka dostupnosti" a jeho stav musí umožnovat prodej viz "tabulka stavů"
- Zboží k zobrazení v katalogu musí mít platnou licenci viz "tabulka dostupnosti" a jeho stav musí umožnovat zobrazení viz "tabulka stavů".
Tabulka stavů
Katalog v poli state vrací jen tyto čtyři hodnoty.
| API State Name |
Název |
can_sell |
can_download |
can_view |
| active |
V prodeji |
t |
t |
t |
| preparing |
Připravujeme |
f |
f |
t |
| presale |
Předprodej |
t |
t |
t |
| canceled |
Prodej ukončen |
f |
t |
f |
Tabulka dostupnosti
| available_from |
available_to |
cílový stav |
poznámka |
| null |
null |
beze změny |
|
| null |
v minulosti |
neplatná licence |
|
| null |
v budoucnosti |
beze změny |
|
| v minulosti |
null |
beze změny |
|
| v minulosti |
v minulosti |
neplatná licence |
|
| v minulosti |
v budoucnosti |
beze změny |
|
| v budoucnosti |
null |
neplatná licence, s výjimkou zobrazení pro stav preparing |
|
| v budoucnosti |
v minulosti |
neplatná licence |
logicky nedává smysl, kombinace je chybný stav |
| v budoucnosti |
v budoucnosti |
neplatná licence, s výjimkou zobrazení pro stav preparing |
|
Cenotvorba
Ceny se zobrazují v několika variantách v datech v objektu prices.
- Aktuální cena
- Jedná se o cenu platnou v okamžik vygenerování metadat zboží, včetně aplikované slevy, pokud existuje aktivní slevová kampaň.
- Pokud existuje více aktivních kampaní, je aplikována kampaň s nejvýhodnější cenou.
- Základní cena
- Může obsahovat několik cen platných v různých časových úsecích a to i do budoucna.
- Kampaně
- Zboží může obsahovat jednu, či více kampaní/slev, které jsou definovány názvem, platností od, platností do a mechanikou výpočtu ceny ze základní ceny.
- Zboží muže obsahovat i kampaně definované v budoucnu.
Měna cen - CZK.
DPH je nedílnou součástí ceny v daném časovém období.
Strom kategorii
- Seznam všech kategorií je dostupný v metodě
generic/categories.
- Kategorie v metadatech obsahují svého rodiče.
- Kategorie první úrovně je obecná kategorie BookUP v metadatech má jako rodičovskou kategorii "null". Pro prezentaci na webu, by měly sloužit pouze její podkategorie.
- Strom má aktuálně hloubku čtyř úrovní, včetně základní kategorie BookUP.
- Pokud se chystáme kategorii odstranit je nejdříve označena za deprecated. Taková kategorie se neobjeví ve výpisu
generic/categories, ale po přechodnou dobu mohou bude vracena z api u položek tak, aby bylo možné změnu v kategoriích zohlednit.
- Nové kategorie na api mohou přibývat.
- O změnách v kategoriiích se snažíme partnery individuálně informovat a děje se to vyjímečně.
Párování druhů audioknih a eknih
Pro párování zboží audiokiha-ekniha lze využít atribut print_isbns, který obsahuje všechna isbn tištěných knih, které korespondují s touto elektronickou verzí. Obsah tohoto atributu je v současné době omezen vzhledem k dotupným podkladům od vydavatů, ale bude se v budoucnosti doplňovat. Pokud prodejce prodává i tištěné varianty knih, může je pomocí tohoto atributu párovat také.
Reporting
Distributor reportuje prodeje prostřednictvím metody report_payment . Uvádí datum a čas vzniku platby, kdy k tomuto okamžiku je pak prováděna kontrola prodejní ceny pro vyúčtování. Reportovat prodeje lze nejpozději do 24h po zaplacení, v opačném případě API vyhlásí chybu. Metoda volitelně přijímá i informaci o doplňkovém kanále prodeje, kde je možno rozlišit nákupy z aplikace a z webu, či cokoliv jiného, Tato hodnota se pak v textové formě může objevit ve výůčtování partnerovi, bez vlivu na výpočet.
Metoda report_payment vrací id objednávky ze seznamu BookUP, partner by se měl toto ID ukládat pro případné párování objednávek v jeho systému, případně pro případ reklamace.
Metoda report_payment umožňuje vyreportovat testovací objednávku, která bude vyřazena z vyúčtování, Testovací objednávka musí být označena správným parametrem, viz detailní nápověda metody.
Reportovanou objednávku je možné zrušit pomocí volání report_payment_cancel. Kdy je vhodné uvádět důvod reklamace z dostupného seznamu popsaného v detailu této metody, maximálně 24h zpětně.
Příklady
Autentizace - ukázková základní implementace JWT pro Postman
var dist_id = pm.environment.get('dist_id') || ''
var secret = pm.environment.get('jwt_secret') || ''
var pathParts = pm.request.url.path
var method = pathParts.join('/')
var timestamp = Date.now()/1000;
var payload = {
"exp": timestamp,
"method": method,
"dist_id": parseInt(dist_id)
}
var header = {
"alg": "HS512",
"typ": "JWT"
}
var result = CryptoJS.enc.Base64.stringify(
CryptoJS.enc.Utf8.parse(
JSON.stringify(header)
)
)
result += ".";
result += CryptoJS.enc.Base64.stringify(
CryptoJS.enc.Utf8.parse(
JSON.stringify(payload)
)
).replace(/=/g, "")
verify=CryptoJS.HmacSHA512(result , secret).toString(CryptoJS.enc.Base64).replace(/\+/g,'-').replace(/\//g,'_').replace(/\=+$/m,'');
result += ".";
result += verify
pm.collectionVariables.set('jwt_token', result)
Možná budoucí rozšíření
- Rozdělení jména autorů na jméno a příjmení.
- Přidání metod pro listování číselníků autorů, vydavatelů, překladatelů a podobně.