TrhKnih.cz API – v1.0

• Základní informace
• Přístupové údaje
• Autorizace a autentizace
• Resource: Issue
• Resource: Ask
• Resource: Order
• Resource: Search
• Resource: User/Settings
• Callback notifikace
• Chybové hlášky
• Typické workflow
• Úprava API v srpnu 2019

Základní informace

API je v experimentálním provozu od února 2016, v srpnu 2019 jsme provedli dílčí aktualizaci.

Jedná se o rozhraní naplňující principy REST.

Vrací a přijímá data především ve formátu JSON.

Technickou podporu poskytujeme na emailu info@trhknih.cz.

Zabezpečení

API je v provozu pouze přes HTTPS a používá platný SSL certifikát.

Povolení přístupu do API

Přístup do API mají jen partneři portálu TrhKnih.cz po dohodě s provozovatelem. Pokud máte zájem o spolupráci, napište nám pomocí kontaktního formuláře nebo na info@trhknih.cz.

Identifikátory

Objekty jednotlivých zdrojů jsou označeny alfanumerickými identifikátory. Příklad: 21mpj9se

Testovací prostředí

API zatím nemá verzi s testovacími daty. Veškerá volání se provádí nad ostrými daty v příslušném uživatelském profilu.

Výjimku představuje testovací callback notifikace, kterou je možné nechat zaslat po přihlášení ve webovém rozhraní.

Získání přístupových údajů

Pokud máte přístup do API od provozovatele povolen, přihlašte se na webové rozhraní TrhKnih.cz a v sekci Nastavení a podsekci API si opište Client ID a vygenerujte Client secret.

Viz následující dva screenshoty.

ClientSecret se ukáže jen jednou. Pokud ho zapomenete, je nutné vygenerovat nové.

Autorizace a autentizace

Pro každé volání API budete potřebovat Access Token. Jedná se o hexadecimální řetězec. Token má platnost typicky 30 minut. Po expiraci je potřeba získat nový.

• HTTP
• curl

{
    "clientId":"1rz64uzk5r",
    "clientSecret":"b278170dac75cd8371c08e07458bf64aecaff19388a22a563981496c3aa88d31"
}

{
    "clientId":"1rz64uzk5r",
    "clientSecret":"b278170dac75cd8371c08e07458bf64aecaff19388a22a563981496c3aa88d31"
}

Volání vrátí:

{
    "token": "c45df156ea5c3073285a72b9eeb3ddea1475d6068f60b48518fbd5f051cce041",
    "expiration": 1455779716
}

Získaný token je potřeba předávat s každým dalším požadavkem na API v hlavičce Authorization. Např.:

• HTTP
• curl

Pro přehlednost je v dalších příkladech hlavička Authorization vynechána.

Resource: Issue

Zdroj issue představuje vydání knižního titulu. Jde o stěžejní entitu v rámci portálu TrhKnih.cz.

• HTTP
• curl

Volání vrátí:

{
	"id": "9b8oa1l7",
	"name": "Puls",
	"subtitle": null,
	"year": 2006,
	"authors": [{
		"full_name": "Stephen King"
	}],
	"publishers": [{
		"name": "Beta"
	}],
	"cover": "/cover/tiny/x/p/6fyutmpx.jpg",
	"isbn": "80-7306-276-3"
}

Atributy authors a publishers jsou pole řetězců. V tuto chvíli API verze 1.0 nevrací identifikátory osob a vydavatelů, jen jejich jména. Autorství více osob je u vydání běžné, některé tituly mají i více vydavatelů, ale tato situace je velmi výjimečná.

Resource: Ask

Zdroj ask představuje inzerát na knihu – nabídku. Jde o druhou nejdůležitější entitu v rámci portálu TrhKnih.cz.

Název Ask pochází z dvojice Ask/Bid, která má původ v burzovní (tržní) terminologii. Oproti očekvání Ask označuje nabídku a Bid poptávku.

Zdroj ask podporuje všechny čtyři metody: POST pro vytvoření, GET pro získání detailů, PUT pro aktualizaci, DELETE pro smazání.

Vytvoření

• HTTP
• curl

{
    "issue_id": "21mpj9se",
    "price": 390,
    "shape": "dobrý",
    "note": "Natržená strana 210, jinak v pořádku.",
    "registered_shipping": 1,
    "weight_cat": 1,
    "callback_data": "123456789"
}

{
    "issue_id": "21mpj9se",
    "price": 390,
    "shape": "dobrý",
    "note": "Natržená strana 210, jinak v pořádku.",
    "registered_shipping": 1,
    "weight_cat": 1
}

Při úspěšném volání vrátí návratový kód 201 Created a ID vytvořeného objektu Ask:

{
    "id": "h02y9a990"
}

Při vytvoření nabídky přes API neproběhne automatická emailová notifikace případných poptávajících, jako je tomu při ručním zadání na webu TrhKnih.cz.

Specifikace dopravy

Nová nabídka musí mít alespoň jeden druh dopravy: přepravu poštou/Zásilkovnou nebo osobní převzetí. Případně oboje.

Přeprava poštou je specifikována jako

 "registered_shipping": 1,
 "weight_cat": 1

kde registered_shipping nabývá hodnot 1 a 0 ve smyslu true/false a weight_cat označuje ID váhové kategorie a nabývá hodnot 1 až 4.

Určení váhové kategorie knihy je důležité, aby při případné objednávce mohl systém správně spočítat poštovné. Metoda výpočtu poštovného je uvedena ve standardní nápovědě. Tamtéž je uvedeno, co hrozí, pokud je kategorie vybrána špatně.

Nastavení vlastní ceny dopravy pro jednotlivé váhové kategorie je možné pouze přes webové rozhraní přihlášeného uživatele v sekci Nastavení » Ceny dopravy.

Na stejném místě se provádí povolení nebo zakázání konkrétního dopravce (Česká pošta/ Zásilkovna).

Osobní převzetí je specifikováno jako

 "registered_shipping": 0,
 "handover": [15738, 3168]

kde handover je pole ID lokalit nastavených pro osobní převzetí.

Celý číselník lokalit není přes API k dispozici. Specifikovat je možné pouze lokality, které má uživatel předem nastaveny. Nastavení je možné pouze ručně přes webové rozhraní v sekci Nastavení » Osobní předání.

Seznam nastavených lokalit uživatele je možné přes API získat, viz resource user/settings/handover-locality.

Zapnutí dopravy poštou i osobního převzetí pak vypadá takto:

 "registered_shipping": 1,
 "weight_cat": 2,
 "handover": [3168]

Callback data

K inzerátu je možné si poznamenat další údaje, např. interní ID z vašeho systému. Slouží k tomu atribut callback_data, který pojme řetězec dlouhý až 128 znaků.

Atribut je pak vrácen mj. ve výpisu položek objednávky.

Výpis

Detail konkrétního inzerátu získáme:

• HTTP
• curl

Volání vrátí např. toto:

{
    "id": "1pn6piatwh",
    "issue_id": "21mpj9se",
    "price": 800,
    "shape": "dobry",
    "note": "Zadní obálka škráblá.",
    "registered_shipping": 1,
    "weight_cat": 3,
    "callback_data": null
}

Seznam všech inzerátů uživatele:

• HTTP
• curl

Vrátí pole ID inzerátů. Pro získání detailů inzerátu je v tuto chvíli nutné zavolat GET na každé ID inzerátu zvlášť.

[
    "23nb5i26",
    "77hnqhf7",
    "7mxt7f2b",
    "7x3dfl0l",
    "89njhle8",
    "c0nfjdb6", 
    ...
]

Při zavolání https://api.trhknih.cz/v1/ask?callback_data=<cokoli> lze získat ID inzerátů s konkrétní hodnotou atributu callback_data. Hodí se např. když v tomto atributu skladujete vaše interní identifikátory.

Aktualizace

Aktualizace inzerátu se provádí takto:

• HTTP
• curl

{
    "price": 50,
    "shape": "dobrý",
    "note": "Natržená strana 209.",
    "registered_shipping": 1,
    "weight_cat": 1
}

{
    "price": 50,
    "shape": "dobrý",
    "note": "Natržená strana 209.",
    "registered_shipping": 1,
    "weight_cat": 1
}

Úspěšné volání vrací návratový kód 200 OK, neúspěšné volání pak 400 Bad Request.

Aktualizace provádí de-facto nahrazení. Pokud neuvedete povinný atribut, skončí volání chybou. Pokud neuvedete nepovinný atribut, původní hodnota nebude zachována.

Příslušnost ke knize se nedá aktualizovat. (Zasláním nové hodnoty pro pole issue_id.) Pokud chcete inzerát přesunout k jinému titulu, smažte ho a vytvořte nový.

Smazání

• HTTP
• curl

Úspěšné volání vrací návratový kód 204 No Content, neúspěšné volání pak 404 Not Found.

Požadavek na mazání volejte bez hlavičky Content-Type: application/json.

Resource: Order

Zdroj order představuje objednávku knih. V tuto chvíli je možné vypisovat pouze příchozí objednávky, čili zdroj order/incoming.

• HTTP
• curl

Volání vrátí např. toto:

{
    "id": 16001234,
    "state": 2,
    "timestamp": 1656761148,
    "note": "Pošlete prosím obzvlášť pečlivě zabalené. Děkuji.",
    "buyer": {
        "fullname": "Alena Rybová",
        "email": "alena.rybova@example.org",
        "phone": "777123456"
    },
    "shipping": {
        "type": "registered",
        "price": 50,
        "shipping_carrier": "Česká pošta",
        "shipping_product": "Doporučené psaní do 1 kg",
        "address": {
            "name": "Alena",
            "surname": "Rybová",
            "street": "Prosecká 676/12",
            "city": "Praha 9",
            "postcode": "19000"
        }
    },
    "items": [{
        "ask_id":"e89ts6yh",
        "issue_id": "12r716a1",
        "price": 40,
        "shape": "nová",
        "note": "",
        "callback_data": null
    }],
    "total": 90
}

Stav objednávky v atributu state má následující hodnoty:

Objednávku nikdy neexpedujte, když má stav 2. Znamená to, že ještě není zaplacená.

Atribut shipping vypadá v případě osobního odběru např. takto:

    "shipping": {
        "type": "handover",
        "price": 0,
        "handover_locality": 15738
    },

kde handover_locality je ID lokality, které prodejce nabídl pro osobní převzetí, viz user/settings/handover-locality.

Seznam všech objednávek uživatele:

• HTTP
• curl

Vrátí pole ID objednávek. Pro získání detailů inzerátu je v tuto chvíli nutné zavolat GET na každé ID objednávky zvlášť.

[
    16001234,
    16001235,
    16001237,
    16001239, 
    ...
]

Zadání podacího čísla zásilky se provádí takto:

• HTTP
• curl

{
    "tracking_number": "RR1234567890CZ"
}

{
    "tracking_number": "RR1234567890CZ"
}

V tuto chvíli podporuje TrhKnih.cz zásilky Českou poštou a Zásilkovnou. Podací čísla jiných přepravců neumožní zadat.

Úspěšné zadání podacího čísla převede objednávku ze stavu 3 (zaplaceno) do stavu 4 (odesláno) a pošle zákazníkovi emailovou notifikaci obsahující podací číslo – aby mohl zásilku sledovat.

Resource: Search

Zdroj search/issue umožní fulltextové vyhledání entity typu Issue (vydání knihy).

Parametr q je povinný a obsahuje hledaný řetězec. Parametr year je volitelný a funguje jako filtr pro rok vydání.

• HTTP
• curl

Volání vrátí:

[{
    "id": "21mpj9se",
    "name": "Harry Potter a kámen mudrců",
    "subtitle": null,
    "authors": "J. K. Rowling",
    "publishers": "Albatros",
    "year": 2001,
    "cover": ""
}, {
    ...
}]

Na rozdíl od resource Issue volání nevrací v případě atributů authors a publishers pole, ale jen serializovaný řetězec. Snad v budoucnu chování vylepšíme.

Vyhledávání podle ISBN je možné realizovat vložením ISBN bez oddělovačů (pomlček):

• HTTP
• curl

Resource: User/Settings

V tuto chvíli funguje jen resource user/settings/handover-locality a to v read only režimu.

• HTTP
• curl

Volání vrátí:

[{
    "id": 3168,
    "local_name": "Havlíčkův Brod",
    "locality": "Havlíčkův Brod"
}, {
    "id": 15738,
    "local_name": "Vysočany",
    "locality": "Praha"
}]

ID lokalit se používají při vytváření nové nabídky na knihu, viz zdroj Ask a jeho metoda POST.

Nastavení lokalit prosím proveďte ručně ve webovém rozhraní.

Callback notifikace

Callback slouží k realtime programovému oznámení nové objednávky ze systému TrhKnih.cz do webového systému klienta.

Na TrhKnih.cz v sekci Nastavení a podsekci API si nastavte URL, na které váš systém bude přijímat notifikace.

Po uložení lze danou URL otestovat – nechat na ní zaslat testovací callback notifikaci.

Ostré i testovací notifikace mají formu HTTP POST požadavku a obsahují následující parametry:

Pokud se notifikaci nepodaří doručit, nezkouší se to znova. Místo toho se pošle na email klienta zpráva s oznámením této skutečnosti.

Obsah notifikace je potřeba brát vždy jako nedůvěryhodný, protože ho teoreticky může odeslat kdokoli, kdo zná Callback URL. Proto také callback neobsahuje žádné podrobnosti o objednávce a klient by vždy měl následně získat detaily o objednávce voláním API zdroje Order s příslušným identifikátorem.

Nejčastější chybové hlášky

Authorization header missing

Neposíláte s požadavkem Access Token. Ten je potřeba k autentizaci.

Authorization failed. Invalid access token.

Váš token je nesprávný, nebo již expiroval. Vyžádejte si nový.

Issue ID not provided or invalid.

Neposíláte POST request pro vytvoření objektu Ask se správnou hlavičkou. Posílejte data v JSON a hlavičku Content-Type: application/json.

Typické workflow

API předpokládá u klienta následující workflow pro zadávání jednotlivých inzerátů:

1. Vyhledání titulu pomocí fulltextu a zjištění jeho ID. Data jsou prezentována živému uživateli, i s obrázky obálek. Případná volba kritéria roku vydání.
2. Vyplnění údajů nového inzerátu (cena, stav, popis).
3. Odeslání inzerátu.

Pokud je položka objednána zákazníkem TrhuKnih, pak TrhKnih pošle klientovi notifikaci na callback URL a ten si opět přes API stáhne detaily objednávky.

Pokud klient prodá položku sám mimo portál TrhKnih.cz, jeho systém by měl automaticky zavolat API TrhuKnih a inzerát smazat.

Přístup k cizím identifikátorům

Je možné zvolit ze dvou přístupů ke skladování cizích identifikátorů:

1. Použití identifikátorů TrhKnih – při vytváření inzerátu přes API si u sebe uložíte ID vzniklého objektu Ask. Pomocí tohoto identifikátoru můžete dělat s inzerátem přes API úpravy (např. jeho smazání, když knihu prodáte u sebe). Tento identifikátor Vám také bude uveden v detailech případné objednávky, takže podle něj pak najdete ve svém systému příslušný záznam a označíte si jej jako prodaný.
2. Použití vašich identifikátorů – při vytváření inzerátu uvedete vlastní identifikátor do atributu callback_data. V detailech případné objednávky je toto pole uvedeno, takže pak podle vlastního ID můžete ve své databázi dohledat záznam a smazat ho, resp. upravit jeho stav. Nevýhoda tohoto přístupu je v případech, kdy potřebujete měnit nebo mazat inzerát přes API TrhKnih.cz. Pak potřebujete znát jeho ID v rámci systému TrhKnih.cz a je proto nutno ho nejprve zjistit zavoláním GET na resource Ask s příslušným filtrem callback_data, kde uvedete svůj interní identifikátor.

Úprava API v srpnu 2019

V souvislosti ze zavedením Zásilkovny činíme od srpna 2019 na API několik drobných změn. Po zralé úvaze je nepublikujeme jako novou verzi API, ale dokumentujeme je tímto způsobem. Veškerá výše uvedená dokumentace je též aktualizována.

Soupis změn od srpna 2019

• Přejmenování číselníku shipping_cat na weight_cat. U POST a PUT metod nad resource Ask je tato změna zpětně kompatibilní (podporujeme starý zápis).
• Zrušení hodnot "do 10 kg" (ID 5),"do 15 kg" (ID 6),"do 20 kg" (ID 7) přejmenovaného číselníku weight_cat.
• Zrušení atributu weight_category na resource Order (metoda GET).
• Zavedení nových atributů shipping_carrier shipping_product na resource Order.
• Zavedení nových atributů packetery_branch_name packetery_branch_id na resource Order pro případy, kdy má objednávka zvolenu dopravu pomocí Zásilkovny.
• Metoda PATCH na resource Order nyní přijímá i tvar podacího čísla Zásilkovny.

Aktualizace v únoru 2023

Bylo doplněno vyhledávání podle ISBN a Resouce Issue nyní vrací ISBN identifikátor i ve výsledcích.