--- /dev/null
+README.html
--- /dev/null
+******************************
+Tolino cloud API documentation
+******************************
+
+Servers the Tolino Vision 3/4 HD talk to (Firmware 14.x).
+
+.. contents::
+ :depth: 1
+
+.. include:: headers.rst
+.. include:: domains.rst
+.. include:: login.rst
+.. include:: pageplace.bosh-bosh-rest-ping.rst
+.. include:: pageplace.bosh-bosh-rest-userid-xxx.rst
+.. include:: pageplace.bosh-bosh-rest-v2-resellerconfig.rst
+.. include:: thalia-auth-oauth2-authorize.rst
+.. include:: thalia-auth-oauth2-token-post.rst
--- /dev/null
+=======
+Domains
+=======
+Domains that are used by the Tolino Vision 3 HD.
+
+
+Buch.de
+=======
+``auth.buch.de``
+ FIXME
+
+
+Google
+======
+``clients3.google.com``
+ Check if the internet is reachable
+
+
+MyTolino.com
+============
+``management.mytolino.com``
+ - List of resellers
+ - eInk handshake (FIXME)
+
+
+Pageplace
+=========
+``bosh.pageplace.de``
+ "bosh" could be short name for "BOokSHelf"
+
+ - ping
+ - reseller configuration
+ - current time
+ - sync main data (books, reading status, notes)
+ - ebook upload
+ - ebook cover upload
+
+``cdp.pageplace.de``
+ - Book images?
+ - Book downloads
+
+``family.pageplace.de``
+ Family sharing
+
+``inventory.pageplace.de``
+ FIXME
--- /dev/null
+=======
+Headers
+=======
+
+``User-Agent``
+ ``Dalvik/1.6.0 (Linux; U; Android 4.4.2; tolino Build/KOT49H)``
+
+ Used for normal API requests
--- /dev/null
+=============
+Login process
+=============
+
+This happens in the web browser.
+
+1. Fetch URL of login page: `GET https://thalia.de/auth/oauth2/authorize`_
+2. Show login page with username + password form
+3. Redirect to internal e-book reader login with code.
+
+ Example redirect: ``Location: epublishing://login?code=GK6jDC``
+4. Request OAuth access token: `POST https://thalia.de/auth/oauth2/token`_
+5. Fetch user data: `GET https://bosh.pageplace.de/bosh/rest/userid/xxx`_
--- /dev/null
+===============================================
+``GET http://bosh.pageplace.de/bosh/rest/ping``
+===============================================
+
+Used to check if the ebook reader is online (internet reachable).
+
+Request
+=======
+GET Parameters
+ ``responseStatus=204``
+ Always there
+
+
+Response
+========
+Status Code
+ ``204 No Content``
--- /dev/null
+{
+ "initAppResponse": {
+ "config": null,
+ "deviceKey": null,
+ "update": 0,
+ "updateVersion": null,
+ "userId": "2086910932"
+ }
+}
--- /dev/null
+======================================================
+``GET https://bosh.pageplace.de/bosh/rest/userid/xxx``
+======================================================
+Step 5 in the `Login process`_.
+
+Example ``xxx`` value: ``665fc389ef4e47258c5db9fa7821bd19``.
+
+FIXME: What is the ``xxx`` value? Hardware ID? User ID?
+If yes, where does the server know it from?
+
+FIXME: Find out how to transform the ``x_buchde.user_id`` from
+`POST https://thalia.de/auth/oauth2/token`_ into that user ID here,
+and if it is really the same.
+
+
+Request
+=======
+No body in the request, despite the ``Content-Type`` header.
+
+Header
+ ``t_auth_token``
+ OAuth token obtained from `POST https://thalia.de/auth/oauth2/token`_.
+
+ Example: ``eyJhbGciOiJSUzI1NiJ9.eyJhdWRpZW5jZSI6InRyZWFkZXJ2aXNpb24zIiw...``
+ ``Accept``
+ ``application/json; charset=UTF-8``
+ ``m_id``
+ FIXME: Maybe reseller ID?
+
+ Example: ``3``
+ ``hardware_id``
+ Seems to be the same as the ``xxx`` value in the URL.
+
+ Example: ``665fc389ef4e47258c5db9fa7821bd19``
+ ``Content-Type``
+ ``application/json; charset=UTF-8``
+ ``client_type``
+ Example: ``TOLINO_VISION_3``
+ ``client_version``
+ Example: ``14.1.0``
+
+
+Response
+========
+HTTP status code: ``200 OK``
+
+Example:
+
+.. include:: pageplace.bosh-bosh-rest-userid-xxx.response.json
+ :code:
--- /dev/null
+<!DOCTYPE html>
+<html>
+<head>
+ <title>GET https://bosh.pageplace.de/bosh/rest/v2/resellerconfig</title>
+ <meta charset="utf-8" />
+</head>
+<body>
+ <section id="get-https-bosh-pageplace-de-bosh-rest-v2-resellerconfig">
+ <h1><code>GET https://bosh.pageplace.de/bosh/rest/v2/resellerconfig</code></h1>
+ <section id="request">
+ <h2>Request</h2>
+ <dl>
+ <dt>Header</dt>
+ <dd>
+ <dl>
+ <dt><code>ifmodifiedsince</code></dt>
+ <dd>Example: <code>1603111725000</code></dd>
+ <dt><code>reseller_id</code></dt>
+ <dd>Example: <code>3</code></dd>
+ <dt><code>hardware_type</code></dt>
+ <dd>Example: <code>tolino_vision_3</code></dd>
+ <dt><code>os_version</code></dt>
+ <dd>Android version Example: <code>4.4.2</code></dd>
+ <dt><code>language_code</code></dt>
+ <dd>Example: <code>en</code></dd>
+ <dt><code>hardware_id</code></dt>
+ <dd>Example: <code>665fd389ea4e47228c5db8fa7821bd23</code></dd>
+ <dt><code>client_type</code></dt>
+ <dd>Example: <code>TOLINO_VISION_3</code></dd>
+ <dt><code>client_version</code></dt>
+ <dd>
+ <p>Tolino firmware version</p>
+ <p>Example: <code>14.1.0</code></p>
+ </dd>
+ </dl>
+ </dd>
+ </dl>
+ </section>
+ <section id="response">
+ <h2>Response</h2>
+ </section>
+ </section>
+</body>
+</html>
\ No newline at end of file
--- /dev/null
+{
+ "reseller_id": 3,
+ "client_type": "TOLINO_VISION_3",
+ "version": "1.7.0",
+ "lastModified": 1603111725000,
+ "config": {
+ "URL_HANDSHAKE": "https://management.mytolino.com/index.html?reseller=3&platform=eink",
+ "STRING_BRAND_NAME": "Thalia.de",
+ "URL_SHOP_EBOOK_SEARCH": "https://ereader.thalia.de/de.thalia.ers.sun/api/2004/sun/suche?einsprung=firmware&search_complex=",
+ "FAMILY_SHARING_ACTIVE": "true",
+ "LCP_ACTIVATED": "true",
+ "URL_SHOP_EBOOK_START_PAGE": "https://ereader.thalia.de/de.thalia.ers.sun/api/2004/sun/startseite?einsprung=firmware",
+ "SHOP_BASE": "https://ereader.thalia.de/de.thalia.ers.artikel/api/2004/artikel/details/?einsprung=reco",
+ "URL_OAUTH_ACCESSTOKEN_FAMILY": "https://thalia.de/auth/oauth2/token?client_secret=gU5a7CA9",
+ "IS_EXTERNAL_LINK_ENABLED": "true",
+ "URL_RESELLER_LOGO": "http://www.tpereader.thalia.de/logos/Prod/thalia_de_sw_klein.png",
+ "IS_LCP_ACTIVATED": "false",
+ "URL_BOOKSHELF": "https://bosh.pageplace.de/bosh/rest",
+ "OAUTH_CLIENT_ID": "treadervision3",
+ "ENABLE_DATA_RECOVERY": "true",
+ "URL_DEVICE_MANAGEMENT": "https://management.mytolino.com/index.html?reseller=3&platform=eink",
+ "URL_BROWSER_START_PAGE": "https://www.google.de",
+ "ADVERTISING_REDIRECT_BASE": "redirect.mytolino.com",
+ "URL_OAUTH_AUTHORIZATION": "https://thalia.de/auth/oauth2/authorize?response_type=code&scope=SCOPE_BOSH SCOPE_BUCHDE SCOPE_MANDANT_ID.2004 SCOPE_LOGIN FAMILY&redirect_uri=epublishing://login&x_buchde.skin_id=17",
+ "RECOMMENDATIONS_IS_SHUFFLE_ENABLED": "false",
+ "URL_OAUTH_ACCESSTOKEN": "https://thalia.de/auth/oauth2/token?client_secret=gU5a7CA9",
+ "URL_FAMILY_SHARING_MANUAL": "https://mytolino.de/family-sharing-handbuch-ereader",
+ "URL_OAUTH_REVOKETOKEN": "https://thalia.de/auth/oauth2/revoke"
+ },
+ "configLanguageSpecific": [
+ {
+ "language": "FR",
+ "languageConfig": {
+ "STRING_ARRAY_SUPPORT_CONTACT": "E-mail: info@thalia.de##Hotline: +49 (0) 251 530 94 44##(Du lundi au vendredi de 9 h à 18 h)",
+ "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Choisissez vos coups de cœur personnels parmi plus d'un million d'ebooks dans l'ebook-shop de Thalia.##Lisez parallèlement sur la tablette ou sur le smartphone avec l'appli eReading de Thalia.##Synchronisez vos ebooks en sécurité, confortablement et gratuitement à travers le tolino Cloud sur plusieurs appareils.##Avec votre tolino, utilisez gratuitement tous les hotspots de la Deutsche Telekom."
+ }
+ },
+ {
+ "language": "EN",
+ "languageConfig": {
+ "STRING_ARRAY_SUPPORT_CONTACT": "E-Mail: info@thalia.de##Hotline: +49 (0)251 530 94 44##(German speaking customer care:##Monday to Friday, 9 a.m. to 6 p.m.)",
+ "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Browse through over 1,000,000 e-books in the Thalia shop.##Use the Thalia eBooks app to read in parallel on your tablet, computer or smartphone.##Synchronize your titles across various devices securely and free of charge via the tolino Cloud.##Use all Deutsche Telekom HotSpots free of charge with your tolino."
+ }
+ },
+ {
+ "language": "ES",
+ "languageConfig": {
+ "STRING_ARRAY_SUPPORT_CONTACT": "E-Mail: info@thalia.de##Línea directa: +49 (0) 251 530 94 44##(Lunes a viernes de 9:00 a 18:00 horas)",
+ "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Seleccione de entre más de un millo de libros electrónicos en la tienda de eBooks de Thalia su destacados personalizados.##Lea de forma paralela con la aplicación de lectura digital de Thalia en su tableta o smartphone.##Sincronice sus libros electrónicos de forma segura, cómoda y gratuita a través de la tolino Cloud en distintos dispositivos.##Utilice con su dispositivo tolino de forma gratuita todos los HotSpots de la Deutsche Telekom."
+ }
+ },
+ {
+ "language": "NL",
+ "languageConfig": {
+ "STRING_ARRAY_SUPPORT_CONTACT": "E-Mail: info@thalia.de##Hotline: +49 (0) 251 530 94 44##(Maandag t/m vrijdag 9:00 uur - 18:00 uur)",
+ "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Kies uit meer dan een miljoen ebooks in de Thalia eBook-Shop uw persoonlijke favorieten.##Lees met de Thalia eReading-app ook parallel op de tablet of smartphone.##Synchroniseer uw ebooks veilig, comfortabel en kosteloos via de tolino Cloud op verschillende apparaten.##Maak met uw tolino gratis gebruik van alle HotSpots van de Deutsche Telekom."
+ }
+ },
+ {
+ "language": "DE",
+ "languageConfig": {
+ "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Wählen Sie aus über einer Million eBooks im Thalia eBook-Shop Ihre persönlichen Highlights.##Lesen Sie mit der Thalia eReading App auch parallel auf dem Tablet oder Smartphone.##Synchronisieren Sie Ihre eBooks sicher, komfortabel und kostenlos über die tolino Cloud auf verschiedenen Geräten.##Nutzen Sie mit Ihrem tolino alle HotSpots der Deutschen Telekom kostenlos.",
+ "STRING_ARRAY_SUPPORT_CONTACT": "E-Mail: info@thalia.de##Rufnummer: 0251 5309 444##(Montag bis Freitag 9 - 18 Uhr, Samstag 9:30 - 18 Uhr)"
+ }
+ },
+ {
+ "language": "IT",
+ "languageConfig": {
+ "STRING_ARRAY_SUPPORT_CONTACT": "E-mail: info@thalia.de##Hot line: +49 (0) 251 530 94 44##(da lunedì a venerdì, dalle ore 9 alle ore 18)",
+ "STRING_ARRAY_ACTIVATION_ADVANTAGES": "Scegli le tue letture preferite tra oltre un milione di eBook nell'eBook shop Thalia.##Con l'app Thalia eReading, leggi in parallelo anche sul tablet o lo smartphone.##Sincronizza i tuoi eBook in modo sicuro, comodo e gratuito su dispositivi diversi tramite tolino Cloud.##Con il tuo tolino, sfrutta gratis tutti gli hot spot di Deutsche Telekom."
+ }
+ }
+ ]
+}
--- /dev/null
+=============================================================
+``GET https://bosh.pageplace.de/bosh/rest/v2/resellerconfig``
+=============================================================
+
+Fetch information about a given tolino reseller (shop):
+
+- Authentication URLs
+- Browser start page
+- Brand name ("Thalia.de")
+- if LCP encryption is available
+
+etc.
+
+
+Request
+=======
+Header
+ ``ifmodifiedsince``
+ Timestamp with microseconds of last reseller config file version
+
+ Example: ``1603111725000``
+ ``reseller_id``
+ Example: ``3``
+
+ Required. "400 Bad Request" if missing.
+ ``hardware_type``
+ Example: ``tolino_vision_3``
+ ``os_version``
+ Android version
+
+ Example: ``4.4.2``
+ ``language_code``
+ Example: ``en``
+ ``hardware_id``
+ Example: ``665fd389ea4e47228c5db8fa7821bd23``
+ ``client_type``
+ Example: ``TOLINO_VISION_3``
+
+ Required. "400 Bad Request" if missing.
+ ``client_version``
+ Tolino firmware version
+
+ Example: ``14.1.0``
+
+
+Response
+========
+
+``HTTP/1.1 304 Not Modified`` if the ``ifmodifiedsince`` header is equal or
+later than the modification date.
+
+
+Success
+-------
+``HTTP/1.1 200 OK`` for the content
+
+Example for headers ``reseller_id:3`` and ``client_type:TOLINO_VISION_3``:
+
+.. include:: pageplace.bosh-bosh-rest-v2-resellerconfig.response-ok.json
+ :code:
--- /dev/null
+===============================================
+``GET https://thalia.de/auth/oauth2/authorize``
+===============================================
+Fetch URL of actual login page.
+
+First step in the `Login process`_.
+
+Source
+======
+This URL is provided in the reseller configuration,
+key ``config.URL_OAUTH_ACCESSTOKEN``.
+
+
+Request
+=======
+GET Parameters
+ ``response_type``
+ Example: ``code``
+ ``scope``
+ Example: ``SCOPE_BOSH%20SCOPE_BUCHDE%20SCOPE_MANDANT_ID.2004%20SCOPE_LOGIN%20FAMILY``
+ ``redirect_uri``
+ Example: ``epublishing://login``
+ ``x_buchde.skin_id``
+ Example: ``17``
+ ``client_id``
+ Example: ``treadervision3``
+Headers
+ ``User-Agent``
+ Browser user agent.
+ ``lcp``
+ Example: ``1``
+ ``X-Requested-With``
+ Example: ``de.telekom.epub``
+
+
+Response
+========
+Redirect to actual login page.
+
+Status code: HTTP/1.1 302
+
+Header
+ ``Location``:
+ Example: ``https://thalia.de/de.thalia.ecp.authservice.application/oauth2/login?response_type=code&scope=SCOPE_BOSH%20SCOPE_BUCHDE%20SCOPE_MANDANT_ID.2004%20SCOPE_LOGIN%20FAMILY&redirect_uri=epublishing://login&x_buchde.skin_id=17&client_id=treadervision3``
--- /dev/null
+<!DOCTYPE html>
+<html>
+<head>
+ <title>POST https://thalia.de/auth/oauth2/token</title>
+ <meta charset="utf-8" />
+</head>
+<body>
+ <section id="post-https-thalia-de-auth-oauth2-token">
+ <h1><code>POST https://thalia.de/auth/oauth2/token</code></h1>
+ <ol type="1">
+ <li>Log in to obtain an access token.</li>
+ <li>Generate access token from a refresh token.</li>
+ </ol>
+ <p>Step 4 of the <a id="id2" class="problematic" href="#id1">`Login process`_</a>.</p>
+ <section id="source">
+ <h2>Source</h2>
+ <p>This URL is provided in the reseller configuration, key <code>config.URL_OAUTH_ACCESSTOKEN</code>.</p>
+ </section>
+ <section id="request">
+ <h2>Request</h2>
+ <dl>
+ <dt>GET parameters</dt>
+ <dd>
+ <dl>
+ <dt><code>client_secret</code></dt>
+ <dd>
+ <p>Provided in the reseller configuration.</p>
+ <p>Example: <code>gU5a7CA9</code></p>
+ </dd>
+ </dl>
+ </dd>
+ <dt>Headers</dt>
+ <dd>
+ <dl>
+ <dt><code>Content-Type</code></dt>
+ <dd><code>application/x-www-form-urlencoded</code></dd>
+ <dt><code>User-Agent</code></dt>
+ <dd><code>DT_EINK_10_NETRONIX DT_EINK_UPD_PP_14.1.0</code></dd>
+ <dt><code>Cookie</code>:</dt>
+ <dd>Example: <code>gcor=SIDYBbxYkmvUvoO8hy@2Sfx4QAAA9o; ab_bucket=9; ab_container=3; OAUTH-JSESSIONID=9C95C20ECEE74164E76F60C205147822.15acdb90</code></dd>
+ <dt><code>Cookie2</code></dt>
+ <dd><code>$Version=1</code></dd>
+ </dl>
+ </dd>
+ <dt>POST parameters</dt>
+ <dd>
+ <dl>
+ <dt><code>grant_type</code>:</dt>
+ <dd><code>authorization_code</code></dd>
+ <dt><code>redirect_uri</code></dt>
+ <dd>
+ <p><code>epublishing://login</code></p>
+ <p>The e-reader internal login process</p>
+ </dd>
+ <dt><code>code</code></dt>
+ <dd>
+ <p>Obtained from login form page redirect.</p>
+ <p>Example: <code>GK6jDC</code></p>
+ </dd>
+ <dt><code>client_id</code></dt>
+ <dd>Example: <code>treadervision3</code></dd>
+ </dl>
+ </dd>
+ </dl>
+ </section>
+ <section id="response">
+ <h2>Response</h2>
+ <p>HTTP status code <code>200 OK</code></p>
+ <pre class="code" source="thalia-auth-oauth2-token-post.response.json">{
+ "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJhdWRpZW5jZSI6InRyZWFkZXJ2aXNpb24zIiwiZXhwaXJlcyI6IjE2MTIxMzgzOTczMzMiLCJ4X2J1Y2hkZS51c2VyX2lk...",
+ "expires_in": 14399,
+ "refresh_token": "ad351547-bcb3-43b2-9914-d88f0a3704c8",
+ "scope": "FAMILY SCOPE_BOSH SCOPE_BUCHDE SCOPE_LOGIN",
+ "token_type": "bearer",
+ "x_buchde.mandant_id": "2004",
+ "x_buchde.user_id": "39549013"
+}</pre>
+ </section>
+ </section>
+ <section class="system-messages">
+ <h1>Docutils System Messages</h1>
+ <div id="id1">
+ <h1>System Message: ERROR/3 (thalia-auth-oauth2-token-post.rst line 7) <a href="#id2">id2</a></h1>
+ <p>Unknown target name: "login process".</p>
+ </div>
+ </section>
+</body>
+</html>
\ No newline at end of file
--- /dev/null
+{
+ "access_token": "eyJhbGciOiJSUzI1NiJ9.eyJhdWRpZW5jZSI6InRyZWFkZXJ2aXNpb24zIiwiZXhwaXJlcyI6IjE2MTIxMzgzOTczMzMiLCJ4X2J1Y2hkZS51c2VyX2lk...",
+ "expires_in": 14399,
+ "refresh_token": "ad351547-bcb3-43b2-9914-d88f0a3704c8",
+ "scope": "FAMILY SCOPE_BOSH SCOPE_BUCHDE SCOPE_LOGIN",
+ "token_type": "bearer",
+ "x_buchde.mandant_id": "2004",
+ "x_buchde.user_id": "39549013"
+}
--- /dev/null
+============================================
+``POST https://thalia.de/auth/oauth2/token``
+============================================
+Step 4 of the `Login process`_.
+
+Uses:
+
+1. Log in to obtain an access token.
+2. Generate access token from a refresh token.
+
+
+Request
+=======
+GET parameters
+ ``client_secret``
+ Provided in the reseller configuration.
+
+ Example: ``gU5a7CA9``
+
+Headers
+ ``Content-Type``
+ ``application/x-www-form-urlencoded``
+ ``User-Agent``
+ ``DT_EINK_10_NETRONIX DT_EINK_UPD_PP_14.1.0``
+ ``Cookie``:
+ Example: ``gcor=SIDYBbxYkmvUvoO8hy@2Sfx4QAAA9o; ab_bucket=9; ab_container=3; OAUTH-JSESSIONID=9C95C20ECEE74164E76F60C205147822.15acdb90``
+ ``Cookie2``
+ ``$Version=1``
+
+POST parameters
+ ``grant_type``:
+ ``authorization_code``
+ ``redirect_uri``
+ ``epublishing://login``
+
+ The e-reader internal login process
+ ``code``
+ Obtained from login form page redirect.
+
+ Example: ``GK6jDC``
+ ``client_id``
+ Example: ``treadervision3``
+
+
+Response
+========
+HTTP status code ``200 OK``
+
+.. include:: thalia-auth-oauth2-token-post.response.json
+ :code:
git.cweiske.de / tolino-api-docs.git / commitdiff