TrhKnih.cz API – v1.0

Základní informace

API je v experimentálním provozu od února 2016.

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 trhknih@gmail.com.

Zabezpečení

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

https://api.trhknih.cz/v1

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 trhknih@gmail.com.

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ý.

POST https://api.trhknih.cz/v1/oauth2/token HTTP/1.1

$ curl -d @cred.json -H "Content-Type: application/json" https://api.trhknih.cz/v1/oauth2/token

kde soubor cred.json je

{
    "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ř.:

GET https://api.trhknih.cz/v1/ask HTTP/1.1
Authorization: Bearer c45df156ea5c3073285a72b9eeb3ddea1475d6068f60b48518fbd5f051cce041

$ curl -H "Authorization: Bearer 4c5d758242d389091585c69c98e0537ee61d9afbbcd397ee865bcd9ce107744b" https://api.trhknih.cz/v1/ask

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.

GET https://api.trhknih.cz/v1/issue/9b8oa1l7 HTTP/1.1

$ curl https://api.trhknih.cz/v1/issue/9b8oa1l7


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"
}

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í

POST https://api.trhknih.cz/v1/ask HTTP/1.1

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

$ curl -d @ask.json -H "Content-Type: application/json" https://api.trhknih.cz/v1/ask

kde soubor ask.json je

{
    "issue_id": "21mpj9se",
    "price": 390,
    "shape": "dobrý",
    "note": "Natržená strana 210, jinak v pořádku.",
    "registered_shipping": 1,
    "shipping_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 nebo osobní převzetí. Případně oboje.

Přeprava poštou je specifikována jako

 "registered_shipping": 1,
 "shipping_cat": 1

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

shipping_cat váha knihy
1 do 500g
2 do 1kg
3 do 2kg
4 do 5kg
5 do 10kg
6 do 15kg
7 do 20kg

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.

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,
 "shipping_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:

GET https://api.trhknih.cz/v1/ask/fgi9mw3v1 HTTP/1.1

$ curl https://api.trhknih.cz/v1/ask/fgi9mw3v1


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

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

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

GET https://api.trhknih.cz/v1/ask HTTP/1.1

$ curl https://api.trhknih.cz/v1/ask


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:

PUT https://api.trhknih.cz/v1/ask/fgi9mw3v1 HTTP/1.1

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

$ curl -X PUT -d @ask.json -H "Content-Type: application/json" https://api.trhknih.cz/v1/ask/fgi9mw3v1

kde soubor ask.json je

{
    "price": 50,
    "shape": "dobrý",
    "note": "Natržená strana 209.",
    "registered_shipping": 1,
    "shipping_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í

DELETE https://api.trhknih.cz/v1/ask/fgi9mw3v1 HTTP/1.1

$ curl -X DELETE https://api.trhknih.cz/v1/ask/fgi9mw3v1

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

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.

GET https://api.trhknih.cz/v1/order/incoming/16001234 HTTP/1.1

$ curl https://api.trhknih.cz/v1/order/incoming/16001234


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

{
    "id": 16001234,
    "state": 2,
    "timestamp": 1656761148,
    "note": "Pošlete prosím obzvlášť pečlivě zabalené. Děkuji.",
    "buyer": {
        "email": "alena.rybova@example.org",
        "phone": "777123456"
    },
    "shipping": {
        "type": "registered",
        "price": 50,
        "weight_category": 2,
        "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:

state význam
2 objednáno
3 zaplaceno
4 odesláno
5 doručeno
6 vráceno
7 stornováno

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

Atribut shipping.weight_category udává celkovou spočítanou váhu objednávky a nabývá stejných hodnot jako shipping_cat u zdroje Ask.

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:

GET https://api.trhknih.cz/v1/orders/incoming HTTP/1.1

$ curl https://api.trhknih.cz/v1/orders/incoming


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:

PATCH https://api.trhknih.cz/v1/order/incoming/16001234 HTTP/1.1

{
    "tracking_number": "RR1234567890CZ"
}

$ curl -X PATCH -d @order.json -H "Content-Type: application/json" https://api.trhknih.cz/v1/order/incoming/16001234

kde soubor order.json je

{
    "tracking_number": "RR1234567890CZ"
}

V tuto chvíli podporuje TrhKnih.cz pouze zísilky Českou poštou. 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.

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í.

GET https://api.trhknih.cz/v1/search/issue?q=harry+potter+rowling&year=2001 HTTP/1.1

$ curl 'https://api.trhknih.cz/v1/search/issue?q=harry+potter+rowling&year=2001'


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.

Resource: User/Settings

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

GET https://api.trhknih.cz/v1/user/settings/handover-locality HTTP/1.1

$ curl https://api.trhknih.cz/v1/user/settings/handover-locality


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:

order_id číslo objednávky
timestamp čas objednávky jako UNIX timestamp
message poznámka

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 inzeá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 filterm callback_data, kde uvedete svůj interní identifikátor.