info:
description: "## Popis BookUP Distributor API\n 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í ve formátech\
\ poskytnutých dodavateli ve formě tvz. master files. Rozsah dostupného katalogu\
\ je závislý na smlouvě o distribuci.\n\nTypy a formáty poskytované na API\n\n\
\ - Audioknihy ve formátu mp3\n - E-knihy ve formátu epub nebo pdf\n\nTypický\
\ průchod na API\n\n 1. Autentizace na API\n 2. Prvotní načtení kompletního katalogu\n\
\ 3. Získání obsahu ke stažení\n 4. Aktualizace katalogu\n 5. Průběžné reportování\
\ prodejů\n\n\n## API dokumentace\n\nZde 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.\n\n### Autentizace\n\n -\
\ Je postavena na technologii JWT tokenu.\n - Token je potřeba generovat pro každé\
\ volání všech metod na API.\n - 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í.\n - Obecný popis technologie naleznete https://jwt.io/.\n\
\ - Ukázkový příklad generování JWT tokenu pro Postman naleznete níže v sekci\
\ příklady.\n\n### Základní rozdělení API\n\nMetody 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í.\n\
\nSkupiny 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ů.\n\
\n - Audiobooks slouží k přístupu k datům audioknih.\n\t - `catalogue_export_get_file`\n\
\t - `catalogue_list`\n\t - `catalogue_updates`\n\n - Ebooks slouží k přístupu\
\ k datům e-knih.\n \t - `catalogue_export_get_file`\n \t - `catalogue_list`\n\
\t - `catalogue_updates`\n\n\n\n - Reporting slouží k reportování nákupu, či storna\
\ objednávky položek a je společný pro oba typy obsahu.\n\t - `report_payment`\n\
\t - `report_payment_cancel`\n - Systémové metody.\n - `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.\n - `categories` vrací seznam všech aktivních kategorií.\n\
\n## Princip práce s katalogem\nSystém generuje minimálně jednou každý den export\
\ celého katalogu. Na diagramu je zobrazen postup průchodu pro získání a aktualizaci\
\ katalogu.\n\n\n```mermaid\nsequenceDiagram\n Partner->>+Bookup: catalogue_export_get_file\n\
\ Bookup->>Partner: URL a čas generování\n note over Partner: Import dat\n\
\ Partner->>Bookup: download(file_id) stažení souborů\n Partner->>Bookup:\
\ catalogue_updates()\n Bookup->>Partner: Id změněných položek\n Partner->>Bookup:\
\ catalogue_list()\n Bookup->>Partner: Metadata požadovaných položek\n note\
\ over Partner: Import dat\n Partner->>Bookup: download(file_id) stažení souborů\n\
```\n\n### Stažení celého katalogu\n\nVý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).\n\nPo prvotním importu katalogu je možné používat metodu\
\ `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.\n\nPř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.\n\n### Stažení změn katalogu\n\nZjištění\
\ změn v katalogu vyžaduje volání dvou metod.\n\n - `catalogue_updates`\n\t-\
\ Vrací seznam ID položek, kterým se v požadovaném časovém období změnila metadata.\n\
\t- Maximální doba za kterou lze zpětně získat informace pomocí této metody je\
\ 48h, v opačném případě je potřeba kvůli změnám načíst kompletní katalog.\n\n\
- `catalogue_list`\n\t- Následně je potřeba k seznamu ID položek do načíst konkrétní\
\ metadata pomocí volání této metody.\n\t- Metodu je potřeba volat v dávkách s\
\ maximálním počtem 100 ID najednou.\n\t- U audioknih jsou metadata výrazně větší\
\ než u e-knih, proto je ke zvážení volat dávky s menším počtem ID.\n\t- Tato\
\ metoda vrací kompletní metadata položek včetně seznamu master files.\n\t- V\
\ metodě `catalogue_list` je možné použít jakýkoli seznam ID. (Příkladem využití\
\ muže být např. administrace distributora, kde v detailu zboží lze mít tlačítko\
\ na aktualizaci metadat, pak by se tato metoda volala právě s jedním ID daného\
\ zboží).\n\n### Stažení souborů k položkám katalogu\nStahování probíhá pomocí\
\ metody `download`, která vrací url pro stažení požadovaného souboru. Většina\
\ souborů je k dispozici ihned ke stažení. Distributor si zrcadlí všechny soubory\
\ na svojí infrastrukturu, odkud je vydává svým zákazníkům. Úložiště tohoto API\
\ není zamýšleno na vysoko kapacitní výdej přímo zákazníkům.\n\nV metadatech zboží\
\ poskytujeme pro každý soubor mimo jeho ID i datum a čas poslední změny a hash\
\ binárního obsahu. Je potřeba aby partner toto kontroloval na své straně a stahoval\
\ pouze změněné soubory. Doporučujeme řídit se se hashem binárního obsahu. Pokud\
\ by tento nedopatřením chyběl lze využít jako fallback i časovou známku, která\
\ se ale může měnit i bez změny binárního obsahu souboru.\n\nSpecifika audioknih:\n\
\n - Je potřeba počítat s tím, že aktuálně nemají správně vyplněné ID3 tagy. Tato\
\ funkčnost je plánována, ale aktuálně je vhodné obsah metadat v MP3 aktualizovat\
\ na straně partnera.\n - 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.\n\nSpecifika e-knih:\n\n - Je potřeba počítat\
\ s čekáním na stažení souborů masterů epub, pdf. 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.\n - Formát mobi je konstruován live na straně serveru z epub. Tedy není\
\ nezbytně nutné tento formát stahovat z API a lze jej vytvořit z předaného epub.\n\
\nDoplňkové soubory (addons)\n\n - 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.\n - pro stažení doplňkových souborů slouží\
\ metoda download, doplňkové soubory mohou mít libovolný mime-type i velikost.\n\
\n### Zpracování katalogu pro prezentaci a prodej\n 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.\n\
\n#### Prodejnost zboží\n\n Je řešena kombinací hodnot stavu zboží a dostupnosti\
\ v čase od a do.\n\n - Zboží k prodeji musí mít platnou licenci viz \"tabulka\
\ dostupnosti\" a jeho stav musí umožnovat prodej viz \"tabulka stavů\"\n - Zboží\
\ k zobrazení v katalogu musí mít platnou licenci viz \"tabulka dostupnosti\"\
\ a jeho stav musí umožnovat zobrazení viz \"tabulka stavů\".\n\n\nTabulka stavů\n\
\n| stav | zobrazení | prodej | poznámka|\n|--|--|--|--|\n| waiting for acceptance\
\ | ne | ne | |\n| active | ano | ano | |\n| cretated | ne | ne | |\n| canceled\
\ | ne | ne | |\n| preparing | ano | ne | |\n| presale | ne | ne | aktuálně\
\ není definované chování stavu, zatím považováno za neprodejné, bude definováno\
\ v budoucnosti |\n| hidden | ne | ano | |\n| sold out | ano | ne | pro digitální\
\ zboží nemá význam |\n\n\nTabulka dostupnosti\n\n| available_from| available_to\
\ | cílový stav| poznámka |\n|--|--|--|--|\n| null| null | beze změny| |\n| null|\
\ v minulosti| neplatná licence| |\n| null| v budoucnosti| beze změny| |\n| v\
\ minulosti| null | beze změny| |\n| v minulosti| v minulosti| neplatná licence|\
\ |\n| v minulosti| v budoucnosti| beze změny| |\n| v budoucnosti| null | neplatná\
\ licence, s výjimkou zobrazení pro stav preparing| |\n| v budoucnosti| v minulosti|\
\ neplatná licence| logicky nedává smysl, kombinace je chybný stav |\n| v budoucnosti|\
\ v budoucnosti| neplatná licence, s výjimkou zobrazení pro stav preparing| |\n\
\n\n\n#### Cenotvorba\nCeny se zobrazují v několika variantách v datech v objektu\
\ prices.\n\n - Aktuální cena\n\t - Jedná se o cenu platnou v okamžik vygenerování\
\ metadat zboží, včetně aplikované slevy, pokud existuje aktivní slevová kampaň.\n\
\t - Pokud existuje více aktivních kampaní, je aplikována kampaň s nejvýhodnější\
\ cenou.\n - Základní cena\n\t - Může obsahovat několik cen platných v různých\
\ časových úsecích a to i do budoucna.\n - Kampaně\n\t - 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.\n\t - Zboží muže obsahovat i\
\ kampaně definované v budoucnu.\n\nMěna cen - CZK.\n\nDPH je nedílnou součástí\
\ ceny v daném časovém období.\n\n#### Strom kategorii\n\n - Seznam všech kategorií\
\ je dostupný v metodě `generic/categories`.\n - Kategorie v metadatech obsahují\
\ svého rodiče.\n - 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.\n - Strom má aktuálně hloubku čtyř úrovní, včetně základní\
\ kategorie BookUP.\n - 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.\n - Nové kategorie na api mohou přibývat.\n -\
\ O změnách v kategoriiích se snažíme partnery individuálně informovat a děje\
\ se to vyjímečně.\n\n#### Párování druhů audioknih a eknih\n\nPro 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é.\n\n## Reporting\nDistributor\
\ 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 vyžaduje i informaci o prodejním kanále/místě\
\ (např. e-shop distributora).\n\nMetoda `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.\n\nMetoda `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.\n\
\nReportovanou 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ě.\n\n## Příklady\n#### Autentizace - ukázková\
\ základní implementace JWT pro Postman\n``` javascript\nvar dist_id = pm.environment.get('dist_id')\
\ || ''\nvar secret = pm.environment.get('jwt_secret') || ''\n\nvar pathParts\
\ = pm.request.url.path\n\nvar method = pathParts.join('/')\n\nvar timestamp =\
\ Date.now()/1000;\n\nvar payload = {\n \"exp\": timestamp,\n \"method\"\
: method,\n \"dist_id\": parseInt(dist_id)\n}\n\nvar header = {\n \"alg\"\
: \"HS512\",\n \"typ\": \"JWT\"\n}\nvar result = CryptoJS.enc.Base64.stringify(\n\
\ CryptoJS.enc.Utf8.parse(\n JSON.stringify(header)\n )\n)\nresult\
\ += \".\";\nresult += CryptoJS.enc.Base64.stringify(\n CryptoJS.enc.Utf8.parse(\n\
\ JSON.stringify(payload)\n )\n).replace(/=/g, \"\")\nverify=CryptoJS.HmacSHA512(result\
\ , secret).toString(CryptoJS.enc.Base64).replace(/\\+/g,'-').replace(/\\//g,'_').replace(/\\\
=+$/m,'');\nresult += \".\";\nresult += verify\n\npm.collectionVariables.set('jwt_token',\
\ result)\n```\n\n\n## Možná budoucí rozšíření\n\n - Rozdělení jména autorů na\
\ jméno a příjmení.\n - Přidání metod pro listování číselníků autorů, vydavatelů,\
\ překladatelů a podobně.\n"
license:
name: MIT
title: Bookup distribution api
version: 1.2.7
openapi: 3.0.0
paths:
/audiobooks/catalogue_export_get_file:
post:
description: 'Výchozí metoda pro první načtení kompletního katalogu. 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 metodu `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.
'
requestBody:
content:
application/json:
schema:
properties:
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
type: object
responses:
'200':
content:
application/json:
schema:
properties:
audiobooks/catalogue_export_get_file:
properties:
last_changed:
description: Čas poslední změny
type: string
url:
description: Url pro stažení katalogu
type: string
required:
- url
type: object
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
'404':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 401
type: number
status_message:
description: Error description
example: Soubor s daty nebyl nalezen
type: string
required:
- status
- status_message
type: object
description: Error
summary: Výchozí metoda pro načtení kompletního katalogu.
/audiobooks/catalogue_list:
post:
description: 'Tato metoda vrací kompletní metadata položek včetně seznamu master
files.
Metodu je potřeba volat v dávkách s maximálním počtem 100 ID najednou.Medata
jsou zde výrazně větší než u e-knih, proto je ke zvážení volat dávky s menším
počtem ID.
Stahování binárních souborů následně probíhá pomocí metody `download`.'
requestBody:
content:
application/json:
schema:
properties:
ids:
items:
minimum: 1
type: integer
type: array
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
required:
- ids
type: object
responses:
'200':
content:
application/json:
schema:
properties:
audiobooks/catalogue_list:
items:
description: Audiokniha
properties:
addons:
description: Doprovodné soubory
items:
properties:
checksum:
description: Kontrolní součet CRC32
type: string
description:
description: Doplňující popisek
type: string
file_size:
description: Velikost v bytech.
type: integer
id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
mime:
description: Mimetype souboru
type: string
order:
description: Pořadí souboru
type: integer
title:
description: Název
type: string
required:
- id
- order
- title
- checksum
- last_changed
type: object
type: array
authors:
description: Autoři knihy
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
available_from:
description: Dostupné od - řídí prodejnost položky
type: string
available_to:
description: Dostupné do - řídí prodejnost položky
type: string
categories:
description: Kategorie
items:
description: Kategorie
properties:
deprecated:
description: Zastaralá kategorie
type: boolean
id:
description: Id kategorie
type: integer
identification:
description: Název kategorie pro automatické importy
- jedná se o seo název. U deprecated kategoriií
může chybět.
type: string
name:
description: Název kategorie
type: string
parent_category_id:
description: Id nadřazené kategorie
type: integer
required:
- id
- name
- deprecated
type: object
type: array
changed_at:
description: Čas poslední změny
type: string
copyright:
description: Popis autorských práv
type: string
country_of_origin:
description: Země původu
enum:
- cs
- worldwide
- null
nullable: true
type: string
cover:
description: Cover
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
created_at:
description: Čas vytvoření
type: string
credits_payment_enabled:
description: Povoleno k prodeji za kredity
type: boolean
description:
description: Popis položky
type: string
download_preference:
description: Doporučený způsob stažení vzhledem k velikosti
dat atp.
collection - lze stáhnout vše najednou
volume - nelze stáhnout jako celek, ale pouze po volume
track - nelze stáhnout jako celek ani volume, ale pouze
po track
enum:
- collection
- volume
- track
type: string
duration:
description: Délka v sekundách
type: integer
ean:
description: Ean
type: string
edition_nr:
description: Pořadové číslo vydání
type: integer
editions:
description: Seznam edicí ve kterých se vyskytuje
items:
properties:
id:
description: Id edice
type: integer
title:
description: Název edice
type: string
required:
- id
- title
type: object
type: array
id:
description: Id položky
type: integer
identification:
description: Partnerské id (id v katalogu dodavatele).
type: string
isbn:
description: Isbn
type: string
narrators:
description: Čte
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
original_title:
description: Původní název položky
type: string
pages:
description: Počet stran tištěné publikace - orientační
type: integer
preview:
description: Preview
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
prices:
properties:
CZK:
description: Struktura pro cenu položky
properties:
actual_price:
description: Aktuální cena včetně případné aktuálně
platné kampaně.
properties:
price:
description: Cena
0=Zdarma
null nebo
-1=neprodejné
type: number
vat_rate:
description: Sazba dph
type: integer
required:
- vat_rate
type: object
base_prices:
items:
description: Base prices of the item
properties:
price:
description: Cena v měně
type: number
valid_from:
description: Platnost od
type: string
valid_to:
description: Platnost do
type: string
vat_rate:
description: Sazba dph
type: integer
required:
- vat_rate
type: object
type: array
campaigns:
items:
properties:
campaign_id:
description: Unikátní id kampaně
type: integer
campaign_type:
description: Typ úpravy ceny, dle typu je
vyplněn jeden z price_ parametrů
enum:
- ratio
- fix
- sub
type: string
name:
description: Název kampaně
type: string
price_fix:
description: Pevná cena např. base_price=100,
price_fix = 66 => výsledná cena 66
type: number
price_ratio:
description: Snížení v poměru, výsledná cena
se zaokrouhluje na celé koruny nahoru
např. base_price=100, price_sub = 20 =>
výsledná cena 80
type: number
price_sub:
description: Snížení základní ceny
např.
base_price=100, price_ratio = 0.7 => výsledná
cena 70
type: number
valid_from:
description: Platnost od
type: string
valid_to:
description: Platnost do
type: string
required:
- name
- campaign_id
- campaign_type
type: object
type: array
currency:
description: Měna
enum:
- CZK
type: string
required:
- currency
- base_prices
- campaigns
type: object
type: object
print_isbns:
description: Seznam ISBN tištěných vydání
items:
description: Isbn tištěného vydání
type: string
type: array
print_price:
description: Cena tištěného vydání
type: number
publishers:
description: Vydavatelé
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
reading_lang:
description: Jazyk, iso aplha2 kód
type: string
release_date:
description: Datum vydání - informativní hodnota
type: string
series:
description: Seznam sérií ve kterých se vyskytuje
items:
properties:
id:
description: Id série
type: integer
part:
description: Pořadí v sérii
type: integer
title:
description: Název série
type: string
required:
- id
- title
type: object
type: array
state:
description: Stav položky:
waiting_for_acceptance -
neprodejná, nezobrazujeme
active - prodejná, zobrazovat
created - neprodejná, nezobrazujeme
canceled
- neprodejná, nezobrazujeme, ale lze stahovat a zobrazovat v
knihovně
preparing - neprodejná, lze zobrazit v
katalogu
presale - prodejná, zobrazovat, lze stahovat
az po přepnutí do active
hidden - prodejná, nezobrazujeme
sold_out - neprodejná, zobrazujeme jako vyprodáno
enum:
- waiting_for_acceptance
- active
- created
- canceled
- preparing
- presale
- hidden
- sold_out
type: string
subscription_enabled:
description: Povoleno k prodeji v rámci subskripčních balíčků
type: boolean
title:
description: Název položky
type: string
translators:
description: Překladatelé
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
volumes:
description: Volumy
items:
description: Disk
properties:
description:
description: Popis položky
type: string
duration:
description: Délka v sekundách
type: integer
id:
description: Id položky
type: integer
state:
description: Stav položky:
waiting_for_acceptance
- neprodejná, nezobrazujeme
active - prodejná,
zobrazovat
created - neprodejná, nezobrazujeme
canceled - neprodejná, nezobrazujeme, ale
lze stahovat a zobrazovat v knihovně
preparing
- neprodejná, lze zobrazit v katalogu
presale
- prodejná, zobrazovat, lze stahovat az po přepnutí
do active
hidden - prodejná, nezobrazujeme
sold_out - neprodejná, zobrazujeme jako vyprodáno
enum:
- waiting_for_acceptance
- active
- created
- canceled
- preparing
- presale
- hidden
- sold_out
type: string
title:
description: Název položky
type: string
tracks:
description: Skladby
items:
description: Track
properties:
authors:
description: Autoři knihy
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
description:
description: Popis položky
type: string
download:
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
type: integer
file_size:
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- file_size
- checksum
- last_changed
type: object
duration:
description: Délka v sekundách
type: integer
id:
description: Id položky
type: integer
narrators:
description: Čte
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
publishers:
description: Vydavatelé
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
state:
description: Stav položky:
waiting_for_acceptance
- neprodejná, nezobrazujeme
active -
prodejná, zobrazovat
created - neprodejná,
nezobrazujeme
canceled - neprodejná,
nezobrazujeme, ale lze stahovat a zobrazovat v
knihovně
preparing - neprodejná, lze
zobrazit v katalogu
presale - prodejná,
zobrazovat, lze stahovat az po přepnutí do
active
hidden - prodejná, nezobrazujeme
sold_out - neprodejná, zobrazujeme jako
vyprodáno
enum:
- waiting_for_acceptance
- active
- created
- canceled
- preparing
- presale
- hidden
- sold_out
type: string
title:
description: Název položky
type: string
track_number:
description: Pořadové číslo skladby v disku
type: integer
volume_number:
description: Pořadové číslo disku
type: integer
required:
- id
- title
- state
- volume_number
- track_number
- download
type: object
type: array
volume_number:
description: Pořadové číslo disku
type: integer
required:
- id
- title
- state
- volume_number
- tracks
type: object
type: array
required:
- reading_lang
- download_preference
- volumes
- narrators
- id
- identification
- title
- state
- created_at
- changed_at
- publishers
- authors
- translators
- categories
type: object
type: array
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 400
type: number
status_message:
description: Error description
example: Vstupní parametry nejsou validní
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: Tato metoda vrací kompletní metadata položek včetně seznamu master
files.
/audiobooks/catalogue_updates:
post:
description: 'Vrací seznam ID položek, kterým se v požadovaném časovém období
změnila metadata.
Maximální doba za kterou lze zpětně získat informace pomocí této metody je
48h, v opačném případě je potřeba kvůli změnám načíst kompletní katalog.
Následně je potřeba metadata položek načíst pomocí metody `catalogue_list`.
Položka je označena za změněnou i v připadě, že došlo k aktualizaci interních
dat, které nejsou na API dostupné. Může se pak z pohlediu API jevt jako beze
změny.'
requestBody:
content:
application/json:
schema:
properties:
filters:
properties:
from_time:
description: Datum od - nesmí být starší 48h
type: string
required:
- from_time
type: object
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
required:
- filters
type: object
responses:
'200':
content:
application/json:
schema:
properties:
audiobooks/catalogue_updates:
items:
type: integer
type: array
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 400
type: number
status_message:
description: Error description
example: Vstupní parametry nejsou validní
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: Vrací seznam ID položek, kterým se v požadovaném časovém období změnila
metadata.
/audiobooks/download:
post:
description: 'Vrací url pro stažení požadovaného souboru. Většina souborů je
k dispozici ihned ke stažení. Distributor si zrcadlí všechny soubory na svojí
infrastrukturu, odkud je vydává svým zákazníkům.Úložiště tohoto API není zamýšleno
na vysoko kapacitní výdej přímo zákazníkům.
V metadatech zboží poskytujeme pro každý soubor mimo jeho ID i datum a čas
poslední změny a hash binárního obsahu. Je potřeba aby partner toto kontroloval
na své straně a stahoval pouze změněné soubory. Doporučujeme řídit se se hashem
binárního obsahu. Pokud by tento nedopatřením chyběl lze využít jako fallback
i časovou známku, která se ale může měnit i bez změny binárního obsahu souboru.
Je potřeba počítat s tím, že MP3 aktuálně nemají správně vyplněné ID3 tagy.
Tato funkčnost je plánována, ale aktuálně je vhodné obsah metadat v MP3 aktualizovat
na straně partnera.'
requestBody:
content:
application/json:
schema:
properties:
file_id:
type: integer
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
required:
- file_id
type: object
responses:
'200':
content:
application/json:
schema:
properties:
audiobooks/download:
description: Url pro stažení
type: string
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 407
type: number
status_message:
description: Error description
example: Chyba při downloadu nebo jeho přípravy
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: Vrací url pro stažení požadovaného souboru.
/ebooks/catalogue_export_get_file:
post:
description: 'Výchozí metoda pro první načtení kompletního katalogu. 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 metodu `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.
'
requestBody:
content:
application/json:
schema:
properties:
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
type: object
responses:
'200':
content:
application/json:
schema:
properties:
ebooks/catalogue_export_get_file:
properties:
last_changed:
description: Čas poslední změny
type: string
url:
description: Url pro stažení katalogu
type: string
required:
- url
type: object
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
'404':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 401
type: number
status_message:
description: Error description
example: Soubor s daty nebyl nalezen
type: string
required:
- status
- status_message
type: object
description: Error
summary: Výchozí metoda pro načtení kompletního katalogu.
/ebooks/catalogue_list:
post:
description: 'Tato metoda vrací kompletní metadata položek včetně seznamu master
files.
Metodu je potřeba volat v dávkách s maximálním počtem 100 ID najednou.
Stahování binárních souborů následně probíhá pomocí metody `download`.'
requestBody:
content:
application/json:
schema:
properties:
ids:
items:
minimum: 1
type: integer
type: array
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
required:
- ids
type: object
responses:
'200':
content:
application/json:
schema:
properties:
ebooks/catalogue_list:
items:
description: Ekniha
properties:
addons:
description: Doprovodné soubory
items:
properties:
checksum:
description: Kontrolní součet CRC32
type: string
description:
description: Doplňující popisek
type: string
file_size:
description: Velikost v bytech.
type: integer
id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
mime:
description: Mimetype souboru
type: string
order:
description: Pořadí souboru
type: integer
title:
description: Název
type: string
required:
- id
- order
- title
- checksum
- last_changed
type: object
type: array
authors:
description: Autoři knihy
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
available_from:
description: Dostupné od - řídí prodejnost položky
type: string
available_to:
description: Dostupné do - řídí prodejnost položky
type: string
categories:
description: Kategorie
items:
description: Kategorie
properties:
deprecated:
description: Zastaralá kategorie
type: boolean
id:
description: Id kategorie
type: integer
identification:
description: Název kategorie pro automatické importy
- jedná se o seo název. U deprecated kategoriií
může chybět.
type: string
name:
description: Název kategorie
type: string
parent_category_id:
description: Id nadřazené kategorie
type: integer
required:
- id
- name
- deprecated
type: object
type: array
changed_at:
description: Čas poslední změny
type: string
copyright:
description: Popis autorských práv
type: string
country_of_origin:
description: Země původu
enum:
- cs
- worldwide
- null
nullable: true
type: string
cover:
description: Cover
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
created_at:
description: Čas vytvoření
type: string
credits_payment_enabled:
description: Povoleno k prodeji za kredity
type: boolean
description:
description: Popis položky
type: string
edition_nr:
description: Pořadové číslo vydání
type: integer
editions:
description: Seznam edicí ve kterých se vyskytuje
items:
properties:
id:
description: Id edice
type: integer
title:
description: Název edice
type: string
required:
- id
- title
type: object
type: array
formats:
description: Dostupné formáty pro objednání
properties:
epub:
description: 'EPUB formát '
properties:
download:
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
type: integer
file_size:
description: Přibližná velikost v bytes, nelze
stanovit přesně vzhledem k DRM
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
ean:
description: Ean
type: string
ident:
description: Formát eknihy
enum:
- epub
- mobi
- pdf_reader
- pdf_a5
- pdf_a4
type: string
isbn:
description: Isbn
type: string
preview:
description: Url na ukázku
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
required:
- ident
- preview
- download
type: object
mobi:
description: Mobi formát
properties:
download:
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
type: integer
file_size:
description: Přibližná velikost v bytes, nelze
stanovit přesně vzhledem k DRM
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
ean:
description: Ean
type: string
ident:
description: Formát eknihy
enum:
- epub
- mobi
- pdf_reader
- pdf_a5
- pdf_a4
type: string
isbn:
description: Isbn
type: string
preview:
description: Url na ukázku
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
required:
- ident
- preview
- download
type: object
pdf_a4:
description: PDF ve formátu A4
properties:
download:
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
type: integer
file_size:
description: Přibližná velikost v bytes, nelze
stanovit přesně vzhledem k DRM
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
ean:
description: Ean
type: string
ident:
description: Formát eknihy
enum:
- epub
- mobi
- pdf_reader
- pdf_a5
- pdf_a4
type: string
isbn:
description: Isbn
type: string
preview:
description: Url na ukázku
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
required:
- ident
- preview
- download
type: object
pdf_a5:
description: PDF ve formátu A5
properties:
download:
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
type: integer
file_size:
description: Přibližná velikost v bytes, nelze
stanovit přesně vzhledem k DRM
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
ean:
description: Ean
type: string
ident:
description: Formát eknihy
enum:
- epub
- mobi
- pdf_reader
- pdf_a5
- pdf_a4
type: string
isbn:
description: Isbn
type: string
preview:
description: Url na ukázku
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
required:
- ident
- preview
- download
type: object
pdf_reader:
description: PDF pro čtečky
properties:
download:
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
type: integer
file_size:
description: Přibližná velikost v bytes, nelze
stanovit přesně vzhledem k DRM
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
ean:
description: Ean
type: string
ident:
description: Formát eknihy
enum:
- epub
- mobi
- pdf_reader
- pdf_a5
- pdf_a4
type: string
isbn:
description: Isbn
type: string
preview:
description: Url na ukázku
properties:
checksum:
description: Kontrolní součet CRC32
type: string
file_id:
description: Id souboru
type: integer
last_changed:
description: Čas poslední změny
type: string
required:
- file_id
- checksum
- last_changed
type: object
required:
- ident
- preview
- download
type: object
type: object
id:
description: Id položky
type: integer
identification:
description: Partnerské id (id v katalogu dodavatele).
type: string
illustrators:
description: Ilustrátoři
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
main_lang:
description: Hlavní jazyk, iso aplha2 kód
type: string
original_title:
description: Původní název položky
type: string
pages:
description: Počet stran tištěné publikace - orientační
type: integer
prices:
properties:
CZK:
description: Struktura pro cenu položky
properties:
actual_price:
description: Aktuální cena včetně případné aktuálně
platné kampaně.
properties:
price:
description: Cena
0=Zdarma
null nebo
-1=neprodejné
type: number
vat_rate:
description: Sazba dph
type: integer
required:
- vat_rate
type: object
base_prices:
items:
description: Base prices of the item
properties:
price:
description: Cena v měně
type: number
valid_from:
description: Platnost od
type: string
valid_to:
description: Platnost do
type: string
vat_rate:
description: Sazba dph
type: integer
required:
- vat_rate
type: object
type: array
campaigns:
items:
properties:
campaign_id:
description: Unikátní id kampaně
type: integer
campaign_type:
description: Typ úpravy ceny, dle typu je
vyplněn jeden z price_ parametrů
enum:
- ratio
- fix
- sub
type: string
name:
description: Název kampaně
type: string
price_fix:
description: Pevná cena např. base_price=100,
price_fix = 66 => výsledná cena 66
type: number
price_ratio:
description: Snížení v poměru, výsledná cena
se zaokrouhluje na celé koruny nahoru
např. base_price=100, price_sub = 20 =>
výsledná cena 80
type: number
price_sub:
description: Snížení základní ceny
např.
base_price=100, price_ratio = 0.7 => výsledná
cena 70
type: number
valid_from:
description: Platnost od
type: string
valid_to:
description: Platnost do
type: string
required:
- name
- campaign_id
- campaign_type
type: object
type: array
currency:
description: Měna
enum:
- CZK
type: string
required:
- currency
- base_prices
- campaigns
type: object
type: object
print_isbns:
description: Seznam ISBN tištěných vydání
items:
description: Isbn tištěného vydání
type: string
type: array
print_price:
description: Cena tištěného vydání
type: number
publishers:
description: Vydavatelé
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
release_date:
description: Datum vydání - informativní hodnota
type: string
series:
description: Seznam sérií ve kterých se vyskytuje
items:
properties:
id:
description: Id série
type: integer
part:
description: Pořadí v sérii
type: integer
title:
description: Název série
type: string
required:
- id
- title
type: object
type: array
state:
description: Stav položky:
waiting_for_acceptance -
neprodejná, nezobrazujeme
active - prodejná, zobrazovat
created - neprodejná, nezobrazujeme
canceled
- neprodejná, nezobrazujeme, ale lze stahovat a zobrazovat v
knihovně
preparing - neprodejná, lze zobrazit v
katalogu
presale - prodejná, zobrazovat, lze stahovat
az po přepnutí do active
hidden - prodejná, nezobrazujeme
sold_out - neprodejná, zobrazujeme jako vyprodáno
enum:
- waiting_for_acceptance
- active
- created
- canceled
- preparing
- presale
- hidden
- sold_out
type: string
subscription_enabled:
description: Povoleno k prodeji v rámci subskripčních balíčků
type: boolean
title:
description: Název položky
type: string
translators:
description: Překladatelé
items:
description: Autor
properties:
id:
description: Id položky
type: integer
name:
description: Jméno
type: string
required:
- id
- name
type: object
type: array
required:
- main_lang
- illustrators
- id
- identification
- title
- state
- created_at
- changed_at
- publishers
- authors
- translators
- categories
type: object
type: array
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 400
type: number
status_message:
description: Error description
example: Vstupní parametry nejsou validní
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: Tato metoda vrací kompletní metadata položek včetně seznamu master
files.
/ebooks/catalogue_updates:
post:
description: 'Vrací seznam ID položek, kterým se v požadovaném časovém období
změnila metadata.
Maximální doba za kterou lze zpětně získat informace pomocí této metody je
48h, v opačném případě je potřeba kvůli změnám načíst kompletní katalog.
Následně je potřeba metadata položek načíst pomocí metody `catalogue_list`.
Položka je označena za změněnou i v připadě, že došlo k aktualizaci interních
dat, které nejsou na API dostupné. Může se pak z pohlediu API jevt jako beze
změny.'
requestBody:
content:
application/json:
schema:
properties:
filters:
properties:
from_time:
description: Datum od - nesmí být starší 48h
type: string
required:
- from_time
type: object
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
required:
- filters
type: object
responses:
'200':
content:
application/json:
schema:
properties:
ebooks/catalogue_updates:
items:
type: integer
type: array
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 400
type: number
status_message:
description: Error description
example: Vstupní parametry nejsou validní
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: Vrací seznam ID položek, kterým se v požadovaném časovém období změnila
metadata.
/ebooks/download:
post:
description: 'Vrací url pro stažení požadovaného souboru. Většina souborů je
k dispozici ihned ke stažení. Distributor si zrcadlí všechny soubory na svojí
infrastrukturu, odkud je vydává svým zákazníkům.Úložiště tohoto API není zamýšleno
na vysoko kapacitní výdej přímo zákazníkům.
V metadatech zboží poskytujeme pro každý soubor mimo jeho ID i datum a čas
poslední změny a hash binárního obsahu. Je potřeba aby partner toto kontroloval
na své straně a stahoval pouze změněné soubory. Doporučujeme řídit se se hashem
binárního obsahu. Pokud by tento nedopatřením chyběl lze využít jako fallback
i časovou známku, která se ale může měnit i bez změny binárního obsahu souboru.
Je potřeba počítat s čekáním na stažení souborů masterů epub, pdf. 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/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.
Formát mobi je v BookUp konstruován live na straně serveru z epub. Tedy není
nezbytně nutné tento formát stahovat z API a lze jej vytvořit z předaného
epub.'
requestBody:
content:
application/json:
schema:
properties:
file_id:
type: integer
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
required:
- file_id
type: object
responses:
'200':
content:
application/json:
schema:
properties:
ebooks/download:
description: Url pro stažení
type: string
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'400':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 408
type: number
status_message:
description: Error description
example: Pod zadaným ID jsme nenalezli žádný záznam.
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 409
type: number
status_message:
description: Error description
example: Pod zadaným ID jsme nenalezli žádný soubor.
type: string
required:
- status
- status_message
type: object
description: Error
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 407
type: number
status_message:
description: Error description
example: Chyba při downloadu nebo jeho přípravy
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: Vrací url pro stažení požadovaného souboru.
/generic/categories:
post:
description: "Vrací seznam všech aktivních kategorií. \n\nKategorie označené\
\ jako zastaralé (deprecated) se zde neobjeví, ale po přechodnou dobu mohou\
\ být vraceny z api u položek tak, aby bylo možné změnu v kategoriích zohlednit."
requestBody:
content:
application/json:
schema:
properties:
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
type: object
responses:
'200':
content:
application/json:
schema:
properties:
generic/categories:
description: List kategorií
items:
description: Kategorie
properties:
deprecated:
description: Zastaralá kategorie
type: boolean
id:
description: Id kategorie
type: integer
identification:
description: Název kategorie pro automatické importy - jedná
se o seo název. U deprecated kategoriií může chybět.
type: string
name:
description: Název kategorie
type: string
parent_category_id:
description: Id nadřazené kategorie
type: integer
required:
- id
- name
- deprecated
type: object
type: array
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: !!python/object:checkerslib.checkers.StrChkr
_default: !!python/name:checkerslib.checkers.UNDEFINED ''
_descr: Seznam kategorií
_doc_hidden: null
_regex: null
args: !!python/tuple []
kwargs: {}
optional: false
/generic/ping:
post:
description: Tato metoda může sloužit pro monitoring ze strany partnera.
requestBody:
content:
application/json:
schema:
properties:
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
type: object
responses:
'200':
content:
application/json:
schema:
properties:
generic/ping:
description: pong
type: string
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: Tato metoda může sloužit pro monitoring ze strany partnera.
/reporting/report_payment:
post:
description: 'Slouží k hlášení prodejů.
Distributor reportuje prodeje nejpozději do 24h po zaplacení, v opačném případě
API vyhlásí chybu. Metoda vyžaduje i informaci o prodejním kanále/místě (např.
e-shop distributora).'
requestBody:
content:
application/json:
schema:
properties:
amount:
description: Cena položky včetně dph
type: number
channel:
description: 'Informace o detailu prodejního kanálu Například aplikace/mobil/web.
Může být zobrazena následně ve vyúčtování pro nějaké lepší vyhodnocení.
Po vzájemné dohodě lze hodnotu parametru [channel] využít pro
nápočet interních kampaní, např. prodej z voucheru nabo jiné akce,
která se spočítá jako interní kampaň (tzn. sleva se nezobrazuje
na API jako klasická kampaň, vyhodnocuje se pouze na základě zaslané
hodnoty ''channel''). '
type: string
currency:
description: Měna
enum:
- CZK
type: string
is_test:
description: Jedná se o testovací objednávku, default=False
type: boolean
item_ident:
description: Id položky
type: integer
item_type:
description: Typ položky
enum:
- audiobook
- ebook
type: string
paid_when:
description: Čas vzniku platby, ne starší než 24h
type: string
partner_payment_ident:
description: Id platby partnera. Pokud jedna objednávka obsahuje
více položek , je potřeba každou položku reportovat např. jako
[CLIENT_ORDER_ID]-[ITEM_ID].
type: string
test_reason:
description: Důvod označení platby za testovací pokud je znám
enum:
- reviewer
- development
- null
nullable: true
type: string
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
vat_rate:
description: Aplikovaná sazba dph, default=0
type: integer
required:
- paid_when
- item_type
- item_ident
- amount
- currency
- vat_rate
type: object
responses:
'200':
content:
application/json:
schema:
properties:
reporting/report_payment:
description: Id platby
type: string
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 405
type: number
status_message:
description: Error description
example: Platba již existuje
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 400
type: number
status_message:
description: Error description
example: Vstupní parametry nejsou validní
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: Slouží k hlášení prodejů.
/reporting/report_payment_cancel:
post:
description: 'Slouží ke stornu objednávky. Distributor reportuje storna nejpozději
do 24h po zaplacení
Je vhodné uvádět důvod reklamace z dostupného seznamu.'
requestBody:
content:
application/json:
schema:
properties:
canceled_when:
description: Čas vzniku storna, ne starší než 24h
type: string
payment_id:
description: Id platby
type: string
reason:
default: unknown
description: Důvod zrušení platby
enum:
- unknown
- refund_customer_request
- refund_item_quality
- refund_system_error
- null
nullable: true
type: string
token:
description: Token podle https://jwt.io, HS512, dist_id a secret
obdržíte v rámci zapojení API
type: string
required:
- canceled_when
- payment_id
type: object
responses:
'200':
content:
application/json:
schema:
properties:
reporting/report_payment_cancel:
description: Id zrušení platby
type: string
status:
example: 200
type: number
status_message:
example: OK
type: string
type: object
description: OK
'403':
content:
application/json:
schema:
oneOf:
- properties:
status:
description: Internal number code
example: 402
type: number
status_message:
description: Error description
example: Nelze zrušit již dříve zrušenou platbu
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 404
type: number
status_message:
description: Error description
example: Platba nebyla nalezena
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 400
type: number
status_message:
description: Error description
example: Vstupní parametry nejsou validní
type: string
required:
- status
- status_message
type: object
- properties:
status:
description: Internal number code
example: 403
type: number
status_message:
description: Error description
example: Exception raised for unauthorized access attempts.
type: string
required:
- status
- status_message
type: object
description: Error
summary: Slouží ke stornu objednávky.
servers:
- description: Api url
url: https://distribution-api.bookup.cz/