Naše JSON-RPC rozhraní myšlenkově vychází z XML-RPC, ale řeší některé jeho nedostatky pro jednodušší používání.
Název volané metody je cesta v URL, takže například volání metody items se zapíše jako /items.
Tento JSON-RPC server umožňuje volání metod několika způsoby:
_, _callback, nebo callback. Jakmile volání obsahu jeden z těchto parametrů, automaticky se odpovídá pomocí JSONP. Více o JSONP na Wikipedii.Content-Type: application/x-www-form-urlencoded.application/json, text/json, nebo text/plain pro JSON a application/bson pro BSON.Rozhraní odpovídá buďto JSONem, jebo BSONem a to podle HTTP hlavičky Accept. Výchozí formát odpovědi je JSON.
Odpověď vždy obsahuje objekt s klíči status a status_message. Status je číselný stav vyřízení volání podobný stavovým kódům HTTP, ale může se lišit tam, kde neexistuje odpovídající HTTP status. Status_message pak obsahuje textový popis výsledku volání. V případě úspěšného volání je odpověď {“status”:200, “status_message”: “OK”}.
Pokud volání vrací nějaká data, kořenový objekt obsahuje ještě klíč s názvem volané metody.
GET /system_list_methods HTTP/1.0
User-Agent: curl/7.37.1
Host: dummy.grandit.cz:1200
Accept: */*
HTTP/1.1 200 OK
Content-Type: application/json
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, GET, OPTIONS
Access-Control-Allow-Headers: Reply-OK-Only
Connection: Close
Content-Length: __
{
"status_message": "OK",
"system_list_methods": [
"system_alive",
"system_list_methods",
"system_method_help",
"system_method_info",
"system_method_sig",
"system_multicall",
"system_status",
],
"status": 200
}
Pokud do vstupního pole, zadáte adresu našeho RPC rozhraní, můžete klikem na tlačítko načíst jeho konfiguraci. S konfigurací rozhraní se načítají jak signatury metod, tak nápověda. Pomocí tohoto rozhraní je také možné jednotlivé metody provolat a zovnou se podívat na návratové hodnoty.
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.
Typy a formáty poskytované na API
Typický průchod na API
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.
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_listcatalogue_updatesEbooks slouží k přístupu k datům e-knih.
catalogue_export_get_filecatalogue_listcatalogue_updatesReporting slouží k reportování nákupu, či storna objednávky položek a je společný pro oba typy obsahu.
report_paymentreport_payment_cancelping 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í.Systé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.
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 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.
Zjištění změn v katalogu vyžaduje volání dvou metod.
catalogue_updates
catalogue_list
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ží).Stahová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.
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.
Specifika audioknih:
Specifika e-knih:
Doplňkové soubory (addons)
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.
Je řešena kombinací hodnot stavu zboží a dostupnosti v čase od a do.
Tabulka stavů
| stav | zobrazení | prodej | poznámka |
|---|---|---|---|
| waiting for acceptance | ne | ne | |
| active | ano | ano | |
| cretated | ne | ne | |
| canceled | ne | ne | |
| preparing | ano | ne | |
| presale | ne | ne | aktuálně není definované chování stavu, zatím považováno za neprodejné, bude definováno v budoucnosti |
| hidden | ne | ano | |
| sold out | ano | ne | pro digitální zboží nemá význam |
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 |
Ceny se zobrazují v několika variantách v datech v objektu prices.
Měna cen - CZK.
DPH je nedílnou součástí ceny v daném časovém období.
generic/categories.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.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é.
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 vyžaduje i informaci o prodejním kanále/místě (např. e-shop distributora).
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ě.
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)