Annotation
LitRes offers its partners an opportunity to legally sell e-content using a number of methods:

1. Method No. 1: totally independently. A partner will also promptly receive a list of new books from us (see 1. Interface to obtain the list of new books), book files (see 2. Interface to receive book files) and provides us with sales statistics (see 3. Interface for partners to submit their sales statistics). The method only applies to e-texts; media content (audio books etc.) is not available as part of the scheme. Please mind that the list of books for which full transfer is supported, is limited. In fact, 33-50% of book offerings will be unavailable using this scheme.
2. Method No. 2: using partner-side catalog, but with files delivered by LitRes server. Here partners must connect to our list of new book offerings (see 1. Interface to obtain the list of new books) and notification system (see 4. Interface to notify LitRes of partner sales). Billing feature operates of partner side, and partners make payments to LitRes via wire transfer. Connection using this method enables selling media content.
3. Method No. 3: using LitRes-side catalog. Here partners only have to develop design or a ready-to-use xslt set for our engine, all other works are performed on our side. In this case, partners only promote their sites for a certain sales percentage. If this approach is used, the entire LitRes catalog including media content is automatically made available to partners.

Table of contents

General notes on partner operations

• This document only describes technical aspects of interaction between LitRes and partners. Legal, organizational and contractual matters are considered separately. For instance, the mere existence of a connection method does not necessarily mean that you are able to use it. To discuss the terms of partner connection please contact litres@litres.ru;
• Interaction between partners and LitRes implies that LitRes not only provides content to partners, but also automatically notifies them of the requirement to delete or update the content. If partners do not timely perform the required procedures for deletion/update, they will be solely responsible before right-holders. Selling books for which the rights were revoked, constitutes piracy.

General information about LitRes partner services

• All text data are transferred and processed in UTF-8 encoding. This applies also to SHA calculation.
• HTTPS protocol is used for interactions. GET and POST methods are interchangeable for all queries to LitRes servers, HTTP 1.1 is supported.
• If delivered as XML or passed to server as query parameters, date and time are always specified in ISO format (2008-10-08 13:29:51) for Moscow timezone.
• For all fractional numbers (e.g., price), dot is used as delimiter. Number "15,50" is not correct, while correct numbers are "15.50" and "15.5".
• All prices are specified in rubles, any conversion operations (if partners use other currencies) must be performed on a partner side, preferably using the exchange rate specified by Central Bank of Russia with deviation of max. 5%.
• Apart from the content of documentation, non-restricted and non-regulated content may be placed, added to or deleted from XML (nodes, text and attributes). Partner side software must correctly drop out and process the situations where, for instance, the structure <a b="c"><d/></a> is the one described in the documentation, but the structure <a b="c" y="x" s="z"><i/><d/><m>text</m></a> is the one that is actually returned. Attributes and parameters that you are interested in will remain available at the previous address a/@b and a/d – we can guarantee that, however the additional content may (and will) appear and disappear. Just be ready to that.

1 Interface to obtain the list of updates

The following URL is used to obtain the list of updates:
https://partnersdnld.litres.ru/get_fresh_book/
This interface returns both new books and the books with changed status. In particular, a book may be updated which should result in its automatic update on a partner site. Similarly, a book may become non-sellable instead of sellable, and in this case partners must immediately cease selling the book (buyers who purchased the book earlier will still have access to their properly paid copies). The book may be assigned a new price, get a new annotation, etc. – any fields may be updated, and partners must also update them on their sites.
Updates must be retrieved max. once in ten minutes and min. once in three hours. Recommended update frequency: once in 15 minutes. Too infrequent updates result in issues related to selling non-sellable books. Delays are especially harmful if LitRes server response to partner sales notification for partners using Partner Side Showcase (method No. 2) is ignored by partner software. In this case, the sales operation is considered accomplished despite LitRes refusal to register it (see 4. Interface to notify LitRes of partner sales), so it becomes impossible to download properly paid file.
Requesting a list of updates (especially with data selection for a long period, e.g. in the course of the initial load) takes quite a lot of time on LitRes side, so you have to setup the script to operate with timeout up to twenty  minutes and exclude submitting repeated queries before the response to the first query is received.
To test the process for downloading the list of updates and review the basics of creation of queries to API, you can use the test file https://www.litres.ru/static/get_fresh_book_tester.html (see the source code of this page).

1.1 Query format

Query parameters (all parameters are mandatory unless otherwise specified):

• checkpoint – time of new books download start in ISO format (e.g., 2017-12-06 19:35:39). You get the list of new books with the time value that is greater than or equal to checkpoint and less than /fb-that updates/@timestamp (see XML description below). If you want to receive continuous new books feed, save /fb-updates/@timestamp received from the server and use it as checkpoint the next time. To receive the full base (in the course of the initial load) use "2013-01-01 00:00:00" checkpoint.
• place – partner ID. This is usually a four-digit code provided to a partner at the time of contract signing (see 8. Data provided to partners).
• type – type of requested content, optional parameter. By default, type=0 is used. Supported values:
• 0 – e-texts/books.
• 1 – audio books.
• 4 – PDF books.
• 11 – books in English (Adobe DRM protected).
• all – all types of books. In this case, customers should expect to get books of the unknown type.
• uuid – the parameter enables providing information only about a book with specific ID; optional parameter. See description below for updated-book/@external_id – unique book ID. uuid parameter is intended for manual books inspection, its future operability is not guaranteed. uuid is taken account of together with checkpoint. If you need guaranteed XML for a book, please use 2005-01-01 checkpoint and specify uuid value.
• endpoint – the end of the period for which information is requested. Optional parameter. It is only recommended for use when the full base of updates is received to low-performing hardware. By restricting the queries with monthly periods, you will be able to avoid processing of giant XML due to processing all the titles in several passes. Time formatting is similar to that in checkpoint parameter. endpoint parameter is intended for parallel work with books, and its future operability is not guaranteed.

• moreplaces (only valid for partners having several sites) – names of the sites delimited by commas, for which books availability must be checked. Example: «PRTN,TEST». The result will be added to the nodes /fb-updates/updated-book/other-place.
  timestamp– current UNIX timestamp, time accurate to the second starting from 00:00:00 UTC January 1, 1970. Mandatory parameter.

  Windows programmers! Please check your timestamps on http://www.timestampgenerator.com/. Please mind, that you can't calculate the timestamp based on the local time value. Timestamp is calculated based on UTC without daylight saving settings. Wikipedia contains plenty of details for the timestamp theory, and a huge set of source files for any language, from Perl to PL/SQL.

• sha – signing the query. Created as: sha256_hex (timestamp.':'.secret_key.':'.checkpoint) – please mind the delimiting parameters of semicolon. Parameters for sha signature calculation will be used as they were passed in the query, secret_key – a secret key for notifications that is passed to partners at the moment of connection (see 8. Data transferred in the course of partner connection). Mandatory parameter.
  If you have problems with creating a correct SHA, you can use the following command for unix console:

  perl -e '\
  $stamp = 1323780017;\
  $key="<secretkey>";\
  $checkpoint="2013-11-25 00:00:00";\
  use Digest::SHA;\
  print "\n\nGood SHA is: ".Digest::SHA::sha256_hex("$stamp:$key:$checkpoint")."\n";'

Example of correct request for a list of new books (please do not forget to replace checkpoint, timestamp and sha with current values): 
https://partnersdnld.litres.ru/get_fresh_book/?checkpoint=2015-10-08%2000:00:00&place=TEST&timestamp=1444248000&sha=4a44dc15364204a80fe80e9039455cc1608281820fe2b24f1e5233ade6af1dd5

1.2 Server response format

New books are delivered as XML. Apart from nodes and attributes described below, the delivered XML may also contain any extra data that must be ignored by partners.
Root element is always fb-updates. And the root element always contains timestamp attribute. Example of an empty response (in case of no updates available):
<fb-updates timestamp="2008-10-08 14:34:05"/>

The value is passed to /fb-updates/@timestamp that represents server time (accurate to the second) until which (non-inclusive) you are currently receiving new books. In order to receive continuous stream of updates, you should save this value and pass it in checkpoint parameter when submitting the next query (see 1.1. Query format). 

Each new book is passed as /fb-updates/updated-book to partners.

<fb-updates xmlns:l="https://www.w3.org/1999/xlink" timestamp="2018-04-19 11:33:14">
    <updated-book id="32498526" created="2018-04-18 16:35:49" last_release="2018-04-18 16:35:49" updated="2018-04-18 16:35:49" valid_till="2018-12-31" valid_from="2013-01-01" size="579411" sent_by_name="nvcvet@gmail.com" sent_by_id="9351951" must_import="0" options="0" price="0.90" you_can_sell="0" allow_read="0" allow_sell="0" has_trial="0" allow_full_free="0" public_domain="0" show_card="0" contract_author="9339265" contract_title="АСТ" subject_id="44580" external_id="b4854f32-430a-11e8-9a05-0cc47a52085c" cover="jpg" type="0" adult="16" file_parts="6" available="-1" available_date="2018-04-18 16:18:02" copyright_read_online="1" contract_ends="2018-12-31" udk="821.111-312.4" art_cover="jpg" lvl="2" sell_open="0" can_preorder="0" litex="1" chars="46369" images="1" drm="0" publisher="АСТ" date_written_s="1969" date_written_d="1969-01-01" lang="ru" src_lang="en" cover_h="1960" cover_w="1400" art_cover_w="1400" art_cover_h="1960" lang3="rus" src_lang3="eng" status="approved" rating="6030" url="" inapp_price="0.90">
        <files>
            <file size="579409" type="fb2.zip"/>
            <file size="51846" type="html"/>
            <file size="583471" type="html.zip"/>
            <file size="47604" type="txt"/>
            <file size="20832" type="txt.zip"/>
            <file size="623059" type="rtf.zip"/>
            <file size="663336" type="a4.pdf"/>
            <file size="708752" type="a6.pdf"/>
            <file size="447161" type="mobi.prc"/>
            <file size="1474324" type="epub"/>
            <file size="590189" type="ios.epub"/>
            <file size="578047" type="fb3"/>
        </files>
        <book-title title="Наследство Боксдейла"/>
        <annotation>
            <p>
            «– Видишь ли, мой дорогой Адам, – мягко объяснял каноник, прохаживаясь с главным суперинтендентом Дэлглишем под вязами возле своего пасторского дома, – как бы нам ни было кстати это наследство, оно не принесет мне радости, если моя приемная бабушка Элли получила в свое время эти деньги недостойным способом.
            </p>
            <p>
            Каноник имел в виду, что они с женой не смогут воспользоваться пятьюдесятью тысячами фунтов, оставленными им его приемной бабушкой Элли, если шестьдесят семь лет назад она отравила своего престарелого мужа мышьяком, чтобы получить их. Поскольку в 1902 году это обвинение было снято с тетушки Элли судом, который, по мнению ее хемпширских соседей, в качестве публичного зрелища мог состязаться с церемонией коронации, щепетильность каноника казалась не совсем уместной…»
            </p>
        </annotation>
        <authors>
            <author id="dc3b5610-2a80-102a-9ae1-2dfe723fe7c7">
                <subject_id>44580</subject_id>
                <url>fillis-dzheyms/</url>
                <first-name>Филлис Дороти</first-name>
                <middle-name/>
                <last-name>Джеймс</last-name>
                <full-name-rodit>Филлис Дороти Джеймс</full-name-rodit>
                <lvl>2</lvl>
                <relation>0</relation>
            </author>
            <author id="e4f1d9b0-2a80-102a-9ae1-2dfe723fe7c7">
                <subject_id>44696</subject_id>
                <url>i-doronina/</url>
                <first-name>Ирина</first-name>
                <middle-name>Яковлевна</middle-name>
                <last-name>Доронина</last-name>
                <full-name-rodit>Ирины Дорониной</full-name-rodit>
                <lvl>1</lvl>
                <relation>1</relation>
            </author>
            <author id="c9a05514-1ce6-11e2-86b3-b737ee03444a">
                <subject_id>2835185</subject_id>
                <url>raznoe-4/</url>
                <first-name>Литагент</first-name>
                <middle-name/>
                <last-name>АСТ</last-name>
                <full-name-rodit/>
                <lvl>2</lvl>
                <relation>2</relation>
            </author>
        </authors>
        <genres>
            <genre title="зарубежные детективы" id="5219" bisac="FIC022000" master="1"/>
            <genre title="классические детективы" id="5261" bisac="FIC022000"/>
        </genres>
        <relations>
            <related uuid="BA8F3184-9049-4EAF-A47B-9D711D9135DC" relation="6" type="0"/>
        </relations>
        <copyrights>
            <copyright id="9339265" title="АСТ" percent="100.00"/>
        </copyrights>
        <livelib livelib_id="1001260109" rating="7.263" avg_mark="3.8246" count_readers="2271" widget_url="book/1100906/ratingbutton2015.png" widget_url2="book/1100906/ratingbuttonwhite.png" mark_1="2" mark_2="5" mark_3="48" mark_4="78" mark_5="885"/>
    </updated-book>
    <updated-book id="32523047" created="2018-04-19 09:14:23" last_release="2018-04-19 09:14:23" updated="2018-04-19 09:14:23" valid_till="2021-11-01" valid_from="2016-11-01" size="5653231" sent_by_name="sabanova" sent_by_id="9355626" must_import="0" options="68" price="5.99" you_can_sell="0" allow_read="0" allow_sell="0" has_trial="0" allow_full_free="0" public_domain="0" show_card="64" contract_author="9356032" contract_title="Эксмо" subject_id="44790" external_id="0a6e477f-4398-11e8-aa6b-0cc47a520474" cover="jpg" type="1" adult="0" file_parts="0" available="-1" available_date="2018-04-19 09:11:16" copyright_read_online="0" contract_ends="2021-02-12" art_cover="jpg" lvl="4" sell_open="0" can_preorder="0" litex="0" chars="4368" drm="0" publisher="" lang="ru" cover_h="1500" cover_w="1071" art_cover_w="1071" art_cover_h="1500" lang3="rus" status="approved" url="" inapp_price="5.99">
        <files>
            <group value="Ознакомительный фрагмент. MP3" group_id="1">
                <file id="37754271" size="5653231" filename="Sample.mp3" seconds="4368" mime_type="audio/mpeg" file_description="MP3"/>
            </group>
            <group value="Стандартное качество. MP3" group_id="5">
                <file id="37754255" size="5669432" filename="01.mp3" seconds="354" mime_type="audio/mpeg" file_description="MP3"/>
                <file id="37754231" size="14099251" filename="02.mp3" seconds="880" mime_type="audio/mpeg" file_description="MP3"/>
                <file id="37754263" size="11474467" filename="03.mp3" seconds="716" mime_type="audio/mpeg" file_description="MP3"/>
                <file id="37754215" size="5472573" filename="04.mp3" seconds="341" mime_type="audio/mpeg" file_description="MP3"/>
                <file id="37754239" size="24781451" filename="05.mp3" seconds="1548" mime_type="audio/mpeg" file_description="MP3"/>
                <file id="37754247" size="8470594" filename="06.mp3" seconds="529" mime_type="audio/mpeg" file_description="MP3"/>
            </group>
            <group value="Мобильная версия. MP4" group_id="19">
                <file id="37754223" size="31707503" filename="Sovetnik_Po_Kulture.m4b" seconds="4366" mime_type="audio/m4b" file_description="M4B-файл"/>
            </group>
        </files>
        <book-title title="Советник по культуре"/>
        <annotation>
            <p>
            Николай Стверцов прибыл на планету Ниона в качестве советника по культуре посольства Земной Федерации. Он должен сыграть важную роль в межгалактическом проекте «Восхождение». Проект призван помочь пяти расам Нионы достичь более высокого уровня развития. Но, узнав о страшной тайне изготовления шейота, который является главным предметом экспорта с отсталой планеты, Стверцов начинает сомневаться в правильности политики Земной Федерации на Нионе…
            </p>
        </annotation>
        <authors>
            <author id="ea92d3b4-2a80-102a-9ae1-2dfe723fe7c7">
                <subject_id>44790</subject_id>
                <url>aleksey-kalugin/</url>
                <first-name>Алексей</first-name>
                <middle-name>Александрович</middle-name>
                <last-name>Калугин</last-name>
                <full-name-rodit>Алексея Калугина</full-name-rodit>
                <lvl>4</lvl>
                <relation>0</relation>
                <exid>1-00000025829</exid>
            </author>
            <author id="556f2637-8bde-11e6-9c73-0cc47a1952f2">
                <subject_id>10117645</subject_id>
                <url>audioagent-litres-chtec-pablik/</url>
                <first-name>Аудиоагент</first-name>
                <middle-name/>
                <last-name>ЛитРес Чтец</last-name>
                <full-name-rodit>Аудиоагента ЛитРес Чтец</full-name-rodit>
                <lvl>1</lvl>
                <relation>2</relation>
            </author>
            <author id="a4d115a3-a4f2-11e6-a11d-0cc47a5203ba">
                <subject_id>10389074</subject_id>
                <url>raznoe-10389074/</url>
                <first-name>Аудиоагент</first-name>
                <middle-name/>
                <last-name>1 редакция-прямой договор</last-name>
                <full-name-rodit/>
                <lvl>1</lvl>
                <relation>2</relation>
            </author>
            <author id="f703f2a3-24cc-11e7-b088-0cc47a52085c">
                <subject_id>11119920</subject_id>
                <url>dumanskiy-andrey/</url>
                <first-name>Андрей</first-name>
                <middle-name/>
                <last-name>Думанский</last-name>
                <full-name-rodit>Думанского Андрея</full-name-rodit>
                <lvl>1</lvl>
                <relation>2</relation>
            </author>
            <author id="f703f2a3-24cc-11e7-b088-0cc47a52085c">
                <subject_id>11119920</subject_id>
                <url>dumanskiy-andrey/</url>
                <first-name>Андрей</first-name>
                <middle-name/>
                <last-name>Думанский</last-name>
                <full-name-rodit>Думанского Андрея</full-name-rodit>
                <lvl>1</lvl>
                <relation>6</relation>
            </author>
        </authors>
        <genres>
            <genre title="научная фантастика" id="5073" bisac="FIC028020"/>
            <genre title="социальная фантастика" id="5078" bisac="FIC028000"/>
        </genres>
        <relations>
            <related uuid="76316fbc-2c44-102b-839c-b3fddb510218" relation="8" type="0"/>
        </relations>
        <copyrights>
            <copyright id="9354189" title="ЛитРес: чтец" percent="26.00"/>
            <copyright id="9354794" title="Эксмо" percent="50.00"/>
            <copyright id="9356032" title="Думанский Андрей" percent="100.00"/>
        </copyrights>
    </updated-book>
    <removed-book id="24261892" uid="fc3ba230-4753-11e7-b2fb-0cc47a52085c" removed="2018-04-19 10:34:13"/>
</fb-updates>	

Contents of updated-book node that is of importance for partners:

• updated-book/@id – unique system ID of the book. Required for retrieval of a book cover, trial fragments. Unlike updated-book/@external_id , it is unique within the scope of a single entity (e.g., it may be a book with ID=12345, or an author with ID=12345).
• updated-book/@you_can_sell – the parameter has the value greater than zero if you are allowed to add the book to your resource, or zero (0) if you are not. Please mind that the value may change either way, and the partner store must consider this attribute. Therefore, if the book that you're currently selling previously used the you_can_sell attribute with a value greater than zero, and now you_can_sell="0" is displayed, you must immediately discontinue selling this book (the card for this book may still remain since the book itself remains in the system). Non-selling partners should also take account of this attribute, and add or remove books according to its value.
• updated-book/@last_release – time of adding the most recent file version. If last_release is modified, partners that add files to their servers should request a new file from us.
• updated-book/@updated – time of the most recent movement operation for the book. It changes when the text, cover, marketing rights, scene change, etc. are updated.
• updated-book/@size – size of the ZIP-archived book (in bytes).
• updated-book/@adult – any age restrictions for the book (in years). The value of 0 shows that no restrictions apply.
• updated-book/@price – current sale price of the book on LitRes. Partners must expect the price to change over time. The price is only a recommended price, but if partners sell the book at a price lower than that on LitRes, they will still pay the price specified here to LitRes by making up the difference at their own expense. Therefore, you should track changes in prices attentively.
• updated-book/@external_id – a unique ID of the book. It is used for the global identification of titles, in particular when the text file is requested from LitRes (see 2.1. Query format), or in sales notifications (see 4.1. Format of sales notification query from a partner), etc. External_id – a string variable, not more than 50 digits. This must always be processed and passed to LitRes server in lower case (this is critical when calculating SHA).
• updated-book/@cover – a string value indicating the presence of a book cover. If the string is empty, there's no cover. If it contains a value, it indicates the format of an original book cover (JPG or PNG). Fixed-size covers are always in JPG format (see 5. Obtaining LitRes book covers).
• updated-book/@file_parts – number of trial fragments for online reading (integer value).
• updated-book/@wap_parts – number of trial fragments for mobile online reading (integer value).
• updated-book/@contract_ends – approximate expiry date of the contract for the title.
• updated-book/@type – title type. Supported values:
• 0 – text.
• 1 – audio book.
• 4 – PDF book.
• 11 – book in English (Adobe DRM protected).
• updated-book/@chars – depending upon the title type, this value may contain various data:
• Type 0 – number of characters in the book (including white spaces).
• Type 1 – total duration of the audio book (in seconds).
• Type 4 – number of pages in the PDF book.
• updated-book/@isbn – one or several ISBNs for the book;
• updated-book/@date_written_s – date of book creation (arbitrary string value). However, in most cases the year of book creation in YYYY format is stored here).
• updated-book/@date_written_d – date of book creation in YYYY-MM-DD.
• updated-book/@images – (valid for type 0 titles) – number of images for the title, including book cover. For instance, if the value of 2 is specified for a type 0 title in this parameter, this means that the book has only one illustration.
• updated-book/authors – a section that contains a description for all authors, translators, artists, narrators and other people who took part in book creation. For each person a separate updated-book/authors/author subsection is allocated, containing the list of proper parameters:
  • @id – a unique ID of the author (artist, narrator, etc.).
  • url – relative URL pointing to author's page. For instance, this path may be added to your domain: www.litres.ru/<string value from this parameter>;
  • first-name – author's first name.
  • last-name – author's last name.
  • full-name-rodit – author's first and last name in Genitive case.
  • lvl – author's level that is assigned based on the value judgment of LitRes editors and reflects author's popularity/influence. The parameter may take integer values from 1 to 5 (5 for the most popular authors).
  • relation – a parameter that defines the type of person that took part in creating this title. Supported values: 
    • 0 – author.
    • 1 – translator.
    • 2 – аgent.
    • 3 – artist.
    • 4 – compiler.
    • 5 – paraphrast.
    • 6 – narrator.
    • 7 – contractor.
    • 8 – manufacturer.
    • 9 – editor.
    • 10 – actor.
    • 11 – director.
    • 15 – producer.
    • 19 – composer.
    • 23 – sound producer.
    • 27 – script writer.
• updated-book/genres – a section where all genres for this title are described. Each genre is represented by a separate updated-book/genres/genre node with the following parameter:
• @id – a unique ID of the genre.
• @title – name of the genre in Russian.
  (Note. For the list of all genres see 7. Obtaining the LitRes tree of genres).

• updated-book/sequences – a section where all series of books are described. For each series, a separate updated-book/authors/sequences/sequence is allocated that contains the list of parameters:
• @name – name of the series.
• @number – sequential number of the book in the series (optional).
• @uuid – a unique ID of the series.

The list of series may have a tree/folded structure. In this case, the book is bound to the utmost "leaves" of the tree, e.g., to updated-book/authors/sequences/sequence/sequence/@uuid.

• updated-book/book-title/@title – name of the book.
• updated-book/book-title/@subtitle – subtitle (detailed description) for the book title.
• updated-book/annotation – text of the annotation of the book, divided into paragraphs with <p>…</p> tags.
• updated-book/lang – language of the title (two-digit lowercase code in ISO format). Supported values:
• ru – Russian.
• uk – Ukrainian.
• en – English.
• de – German.
• fr – French.
• ab – Abkhaz.
• az – Azerbaijani.
• ay – Aymara.
• sq – Albanian.
• ar – Arabic.
• hy – Armenian.
• as – Assamese.
• af – Afrikaans.
• ts – Bantu.
• eu – Basque.
• ba – Bashkir.
• be – Belarusian.
• bn – Bengali.
• my – Burmese.
• bh – Bihari.
• bg – Bulgarian.
• br – Breton.
• cy – Welsh.
• hu – Hungarian.
• wo – Wolof.
• vi – Vietnamese.
• gd – Gaelic.
• nl – Dutch.
• el – Greek.
• ka – Georgian.
• gn – Guarani.
• da – Danish.
• gr – Ancient Greek.
• iw – Ancient Hebrew.
• dr – Old Russian.
• zu – Zulu.
• he – Hebrew.
• yi – Yiddish.
• in – Bahasa Indonesia.
• ia – Interlingua.
• ga – Irish.
• is – Icelandic.
• es – Spanish.
• it – Italian.
• kk – Kazakh.
• kn – Kannada.
• ca – Catalan.
• ks – Kashmiri.
• qu – Qechua.
• ky – Kyrgyz.
• zh – Chinese.
• ko – Korean.
• kw – Cornish.
• co – Corsican.
• ku – Kurdish.
• km – Khmer.
• xh – Xhosa.
• la – Latin.
• lv – Latvian.
• lt – Lithuanian.
• mk – Macedonian.
• mg – Malagasy.
• ms – Malay.
• mt – Maltese.
• mi – Maori.
• mr – Marathi.
• mo – Moldavian.
• mn – Mongolian.
• na – Nauru.
• ne – Nepali.
• no – Norwegian.
• pa – Punjabi.
• fa – Farsi.
• pl – Polish.
• pt – Portuguese.
• ps – Pushto.
• rm – Romansh.
• ro – Romanian.
• rn – Rundi.
• sm – Samoan.
• sa – Sanskrit.
• sr – Serbian.
• si – Sinhala.
• sd – Sindhi.
• sk – Slovak.
• sl – Slovenian.
• so – Somali.
• st – Sesotho.
• sw – Swahili.
• su – Sundanese.
• tl – Tagalog.
• tg – Tadjik.
• th – Thai.
• ta – Tamil.
• tt – Tatar.
• te – Telugu.
• bo – Tibetan.
• tr – Turkish.
• tk – Turkmen.
• uz – Uzbek.
• ug – Uighur.
• ur – Urdu.
• fo – Faroese.
• fj – Fiji.
• fi – Finnish.
• fy – Frisian.
• ha – Hausa.
• hi – Hindi.
• hr – Serbo-Croatian.
• cs – Czech.
• sv – Swedish.
• sn – Shona.
• eo – Esperanto.
• et – Estonian.
• jv – Javanese.
• ja – Japanese.
• updated-book/src_lang – source language of the title (two-digit lowercase code in ISO format). For Shakespeare's "Hamlet" translated into Russian, "en" is specified in src_lang, and "ru" in lang.
• updated-book/files/group/ – (valid for type 1, 4 content) – list of media files associated with this title. Files are grouped by encoding type (updated-book/files/group/@value). Each type has the corresponding @group_id. Any single title may have multiple alternative forms. For instance, a book may exist in two versions: "Standard quality. MP3, 192 Kbps" and "Mobile version. MP4, 16 Kbps". Both groups duplicate the same content, presenting it, however, in different formats. The updated-book/files/group/@value module may contain the following values with corresponding group_id:

For type 1 content (audio books):

For type 4 content (PDF):

It's important to understand that the list of groups may be extended, and you have to correctly process any unknown values.
For each file in the group specify:

• @id – numerical ID of the file. When a user downloads media files (see 4.5. Downloading media content (all types except 0 and 11), this ID is passed to LitRes server.
• @size – file size (in bytes).
• @filename – recommended file name.
• @seconds – duration (makes sense for files like MP3).
• @mime_type – content type. Supported values:
• audio/mpeg – MP3 file.
• audio/x-pn-realaudio – Real Audio file.
• audio/wav – WAV file.
• audio/x-ms-wma – WMA file.
• audio/m4b – M4B file.
• application/zip – ZIP file.
• application/x-rar-compressed – RAR file.
• application/pdf – PDF file.

It's important to understand that the list of content types may be extended, and you have to correctly process any unknown values.

• @file_description – brief description of the file type.
• updated-book/files/file – (valid for type 0 and 11 content) – list of file types with indication of size of the file containing electronic text of the book. For each file type specify:
  • @type – file type.
    Supported values for type 0 content:
    
    • fb2.zip.
    • rtf.zip.
    • a6.pdf.
    • a4.pdf.
    • html.zip.
    • txt.zip.
    • rtf.zip.
    • doc.prc.zip.
    • rb.
    • epub.
    • mobi.prc.
    • txt.
    • isilo3.pdb.
    • lit.
    • ios.epub.

Supported values for type 11 content:

• epub.
• a4.pdf.
• @size – file size in bytes (is not specified for type 11).
• updated-book/@contract_author, updated-book/@contract_title – numerical ID and text name of the right holder for this text. If no updated-book/@contract_title is specified, this means that the author is the right holder. Partners may specify right holder's name at their sites in order to increase system transparency for users and authors.
• updated-book/@copyrights – right holders' details:

• copyrights_title – name of the right holder (the value corresponds to contract_title parameter).
• copyrights_id – numerical ID of the right holder (the value corresponds to contract_author parameter).
• ownership rate – share of participation of this right holder in the book.

• updated-book/@rating – rating of the book that is based on multiple indicators (volume of annual sales of the title, popularity of the author, user ratings, etc.) and reflects the actual popularity of the book among LitRes users. The parameter may take integer values from 0 to ∞ (the greater is the value, the more popular is the book). The parameter may be excluded from delivery. For instance, if the book is new and has never been sold yet.
• updated-book/@relations – ID of the books related to the ID passing the information, type of relation and type of related book. Supported values of relation types (relations) that are of potential interest to partners:

• 5 – collection.
• 6 – part.
• 7 – reprint.
• 8 – other media type.

• updated-book/other-place – information about book availability on specified site (see the moreplaces query parameter in 1.1. Query format). Response may contain a number of such nodes: it depends upon the number of sites specified in the query. Each node contains the following attributes:
  • @place – name of the site passed in the moreplaces parameter of the query
  • @you_can_sell – permission for adding the book to the @place site. Supported values:
    
    • 1 – partner may add the book to the @place site and sell it there
    • 0 – partner is prohibited to add the book to the @place site and sell it there.

In addition to the information about the new books, response may also contain the set of removed-book commands. The books to be removed are classified based on fb2-ID in the removed-book/@uuid attribute, and must be completely removed from the partner system (in case they were added there), including from the shopping baskets of users that have already purchased the book.

Removed-book instructions may contain the @s_uid_new attribute where new ID for the removed book is stored. In this case, we don't mean the deletion of the book, but its replacement. The partner, therefore, may replace the old book in the shopping basket of users who have already paid for it, with the new one (purchased books are replaced on LitRes side). Record of the old book must be deleted in any case.

2 Interface to obtain book file

To get the book file, the following URL is used:
https://partnersdnld.litres.ru/get_the_book/

2.1 Query format

This URL receives queries that contain parameters to be specified below: Response contains the ZIP archive with fb2 file (e-book) or file in any other format (if the file field is filled out). 

Query parameters (book, sha, place parameters are mandatory):

• book – fb2-ID of the book (retrieved from updated-book/@external_id, for details see 1.2. Server response format). Mandatory parameter.
• sha – signing the query. In Perl, the key is generated as follows: lc Digest::SHA::sha256_hex($BookID.':'.$Key); where $Key is your secret key provided to partners in the course of their connection (see 8. Data transferred in the course of partner connection). Please mind that $BookID expects the ID of the book to be in lower case. Mandatory parameter.
• place – partner ID, usually a four-digit code (see 8. Data transferred in the course of partner connection). Mandatory parameter.
• type – an optional attribute indicating the format for returning the e-book file. The default format is fb2.zip, other supported values:
• fb2.zip.
• rtf.zip.
• a6.pdf.
• a4.pdf.
• html.zip.
• txt.zip.
• rtf.zip.
• doc.prc.zip.
• rb.
• epub.
• mobi.prc.
• txt.
• isilo3.pdb.
• lit.
• ios.epub.
• file – ID of the file from updated-book/files/group/file/@id (1.2. Server response format). Optional parameter used to retrieve PDF and audio files (filling out the type field is not required in this case). If no parameter is passed, only files in fb2.zip format and its derivative formats will be delivered.

2.2 Server response format

Server will deliver the requested file in the appropriate format. You can further retrieve all the required information about the book from the fb2 file, including full-size book cover, name, list of authors, etc. When delivering a file, the server passes a recommended file name in the attachment field of http response (the recommended name consists of transliterated name, series, author's last name, etc.).

3 Interface for partners to submit their sales statistics

Partners shall provide LitRes with operational statistics (max. 24-hour delay of sales notifications) for sale of titles. In order to receive the statistics, partners connected via method no. 1 use http query from our server to partner server (see 4.1. Format of partner sales notification query) for details of report on connection using method No. 2).

Partner server must respond with a list of all sales (not statistical data, but the list of sale transactions). Sales data are retrieved from partners hourly.

3.1 Format of query to partner server

Partner shall inform us of the statistics URL at the moment of connection (see 8. Data provided by partners).

HTTP server with the specified URL must process GET queries with the following parameters:

• checkpoint – time accurate to the second from which (inclusively) the list of sales is to be returned. It is assumed that partner server will return the purchases made until [the present moment minus one second].

• sha– signing the query. Generated by means of sha calculation from the value obtained as a result of concatenation of checkpoint and secret key values. In Perl, the key is generated as follows:

  lc Digest::SHA::sha256_hex($CheckPoint.$Key)

  where $Key is the secret key provided to LitRes by partner at the moment of connection (see 8. Data provided to partners).

LitRes will submit queries to the statistics URL once per hour. Partners are expected to continually provide complete statistics each time the litres-partner-sales/@timestamp parameter is substituted as checkpoint in the next query. No omissions (mandatory) or repetitions (preferably) are allowed.

my $CheckPoint=$query->param('checkpoint');
 
my $NowSth=$dbh->prepare("SELECT now()");
$NowSth->execute();
my $EndPoint=$NowSth->fetchrow();
 
my $GetSalesSth=$dbh->prepare("
    SELECT fb2_id as `item-id`, price, time, id as `pay-id`
    from sales
    where time >= ? and time < ?
");
 
$GetSalesSth->execute($CheckPoint,$EndPoint);
 
print '<litres-partner-sales partner="PRT" timestamp="'.$EndPoint.'">'. FetchQueryXML($GetSalesSth).'</litres-partner-sales>';

3.2 Format of response from partner server

Responding to the query from LitRes, partner server must return an XML where the root element has the name of litres-partner-sales. 

<litres-partner-sales checkpoint="2008-09-01 18:00" partner="IMOB" timestamp="2008-10-08 17:12">
	<sale item-id="236C2AF7-38AB-41C4-AE10-F592EDE67F75" price="10.00" time="2008-09-01 18:45" pay-id="566" currency="RUR"/>
	<sale item-id="8A7F4723-9F7B-4C97-BF17-130DAB87519A" price="17.00" time="2008-09-01 19:08" pay-id="567" currency="RUR"/>
	<sale item-id="03D9D905-3387-4B04-94F5-BEF119059D13" price="3.00" time="2008-09-02 08:50" pay-id="568" currency="RUR"/>
</litres-partner-sales>

Mandatory content of litres-partner-sales tag:

• litres-partner-sales/@timestamp – server time until which (non-inclusively) you have to return the complete list of sale transactions.
• litres-partner-sales/@partner – partner ID (see 8. Data provided to partners).
• litres-partner-sales/sale – partner-provided description of a single sale transaction. It must contain the following attributes:
• @item-id – fb2-ID of the book (see 1.2. Server response format, updated-book/@external_id);
• @price – sales price of the book.
• @time – time in ISO format when the sale was completed.
• @pay-id – a unique ID of the payment in a partner system that helps avoid duplicated payment accounting.
• @currency – currency code. Supported valued: EUR, USD, GBP, AUD, CAD, RUR, NZD. Optional attribute. Default value is RUR (Russian ruble), and any values other than "ruble" must be explicitly agreed at the time of connection to LitRes system.

Using currencies other than rubles is only possible subject to previous approval by LitRes.

4 Interface to notify LitRes of partner sales

If partner connection method implies that partners maintain the showcase by their own efforts, and customers download content from LitRes server, ensure that the following requirements are met:

1. Partners allocate a domain name that will be used for delivering files (see 8. Data provided by partners). For instance, a partner that maintains the www.bobook.ru showcase may allocate the dnlbook.bobook.ru domain for downloading books. This domain is redirected to LitRes server. You need to specify this domain name at the time of connection to the service.
2. In the course of selling (not after sale completion) books to a user, partner submits a notification to LitRes server (see 4.1. Format of sale notification query from partner) and receive a response (see 4.2. Format of server response to the notification query). After (and only after that!) LitRes returns Success status, partner completes sale of a book to user. If LitRes refuses to register a sale transaction, partner shall immediately cease selling the book to a user . If the notification was successfully submitted, the sale transaction is irrevocably registered in our system and immediately made available to right holders.
3. A book that was sold, and the sale transaction was registered with LitRes, is available for downloading by user via a dedicated URL. A link for book download includes SHA signature of a purchaser and is submitted by a partner to a domain selected at the time of connection (see p. 1 above). If the sale transaction was not registered by LitRes server, or a link was incorrect (incorrect SHA), customers are redirected (with HTTP 302 code) to error page (see 8. Data provided by partners), provided by the partner at the time of registration.
4. LitRes guarantees proper service for up to 20 downloads of any book in any format by each customer. Click-throughs made by partner's customers who exceeded their download limit are redirected (HTTP code 302) to the page provided by the partner. Count of already performed downloads is stored on LitRes server and reduced by 1 monthly (offering max. 32 downloads per year). Broken downloads resume and repeated downloads within a minute do not add to download count. It's desired that a partner tracked the count of queries by their own efforts and timely notified their customers in advance when the download limit is expiring.

Partner sales notifications are considered to be reliable sales data and used by LitRes for the purposes of reporting to right holders. No statistics from partners connected via method No. 2 is required as per section 3.

4.1 Format of partner sales notification query

To notify LitRes that one of partner's users have purchased a book and should receive a permission for download, the partner shall immediately after completing the sale transaction send a HTTP query to a dedicated URL (on the LitRes domain registered specifically for them in compliance with section 8. Data provided by partners), for instance: http://dnlbook.bobook.ru/partner_user_purchases_a_book/.

The partner passes the following parameters:

• user – mandatory parameter. Buyer ID in partner's system. It is further used to create download URL. Positive integer up to 4294967295. If the query passes lfrom parameter, user value may be a string of up to 128 digits.
• art – mandatory parameter. Lower case FB2-ID of the book purchased by user (see updated-book/@external_id in section 1.2. Server response format).

• sha– mandatory parameter. Signature for SHA256 query. In Perl, the key is generated as follows:

  Digest::SHA::sha256_hex($user.':'.$art.':'.$Key)

  where $Key is the secret key for notifications set to partners at the moment of connection (see 8. Data transferred in the course of partner connection). Please mind that $art expects the ID of the book to be in lower case.

• price – mandatory parameter. Sales price at which the partner sold the book. If this price is lower than that specified by LitRes, the price of LitRes will still be used for settlements. Partners must specify their sale revenue with due diligence. Let's assume that the book costs 10 rubles on LitRes. A partner sells the book for SMS, sending SMS costs user 50 rubles, and the partners gets 20 rubles out of this amount. However, the partner must report selling the book for 20 rubles.
• mail – buyer's e-mail. Is a mandatory parameter, except for reserve=reserve parameter (see below). In this case, mail parameter is optional though desirable, and allows to validate the email on LitRes side.
• reserve – optional parameter. Sign of a two-step order that includes reservation. If reserve=reserve parameter is specified, LitRes server does not perform purchase for the customer. Instead, it checks availability of the product and reserves it. Server response passes reserve ID. If reserve parameter passes a number, it is considered to be the reserve ID, and this reserve is treated as a purchase (all the rest of the parameters must also be passed and comply with the reserve data). Reservation time – 15 minutes. Reserved products will be safely processed as a purchase even if it was discontinued and is currently not available.
• lfrom – optional parameter. Referral number. A partner may be assigned a referral number to register sale transaction on LitRes instead of partner site. In this case, lfrom is mandatory to specify, and user may be a string ID of up to 128 digits.

4.2. Format of server response to the notification query

LitRes server returns an XML-formatted operation result in response to notification query. Response options:

• <response status="0" reserve-id="333333" message="OK" reserve-price="89.90"/> – reservation successful. Reserve-id attribute passes the reserve Id, and reserve-price – reference LitRes price for this book in rubles current as of the time of making the reservation.
• <response status="0" order-id="333333" message="OK"/> – sale transaction is successfully registered, order-id contains the internal ID for the purchase on LitRes.
• <response status="error_code" message="text_message"/> – an error occurred, brief description of the error is provided. In this case, a link to download this book is invalid, and the sale transaction is not registered. The following error codes are possible:
• 1001 – incorrect SHA.
• 1002 – incorrect book ID.
• 1003 – the book is already purchased (not returned for POD books).
• 1004 – the book is unavailable for sale.

4.3 Download of text-formatted books (Type 0)

To download a text book from LitRes server, partners may generate URL according to the following rules:

• HTTP query with domain agreed by the parties and pointing to LitRes server (see 8. Data provided by partners) (e.g., http://dnlbook.bobook.ru).
• The domain name is followed by a mandatory part of the URL: /get_litres_file/ (e.g., http://dnlbook.bobook.ru/get_litres_file/).

• Then the current UNIX timestamp follows: time accurate to the second, starting from 00:00:00 UTC Jan 1, 1970. The link is considered valid if the timestamp is behind the current time for more than 12 hours. Times with obsolete timestamp are not processed (e.g., http://dnlbook.bobook.ru/get_litres_file/1223476707/). To reduce sensitivity of URL to time desynchronization between the partner server and LitRes, we recommend using a timestamp overdue for 60 seconds.

  Windows programmers! Please check your timestamps on http://www.timestampgenerator.com/. Please mind, that you can't calculate the timestamp based on the local time value. Timestamp is calculated based on UTC without daylight saving settings. Wikipedia contains plenty of details for the timestamp theory, and a huge set of source files for any language, from Perl to PL/SQL.

• Then user ID follows (e.g., http://dnlbook.bobook.ru/get_litres_file/1223476707/666/).

• Then a lowcase fb2-ID of the book is specified. The ID may contain invalid characters, and in this case the URL must be "escaped" (e.g., http://dnlbook.bobook.ru/get_litres_file/1223476707/666/fb2-test-id-123).

• Then, you need to add the extension after the dot delimiter. Select the extension based on the file type requested by user. The following extensions are accepted:

• .fb2.zip – zipped FB2.
• .html.zip – zipped HTML.
• .txt.zip – zipped TXT.
• .rtf.zip – zipped RTF.
• .a4.pdf – PDF optimized for A4 printing.
• .a6.pdf – PDF optimized for eBook reader.
• .isilo3.pdb – iSilo (an old cross-platform reader) format.
• .doc.prc.zip – palm doc file. The format is supported in a number of old and new reader applications.
• .lit – Microsoft Reader file.
• .rb – Rocket eBook and REB1100 format.
• .epub – ePub, a new promising e-book format by Adobe.
• mobi.prc – mobi reader files. Currently, the most important thing for these formats is that they are all supported by Amazon Kindle, though there are really nice readers for PalmOS, Windows Mobile and desktop OS that support mobi.(e.g., http://dnlbook.bobook.ru/get_litres_file/1223476707/666/fb2-test-id-123.fb2.zip)

• SHA signature is added to this link as a GET or POST parameter. In Perl, the key is generated as follows:

  Digest::SHA::sha256_hex($TimeStamp.':'.$UserID.':'.$FB2_id.':'.$Key)

  where $Key is your secret key for download that is provided to partners at the time of connection (see 8. Data transferred in the course of partner connection).

(e.g., http://dnlbook.bobook.ru/get_litres_file/1223476707/666/fb2-test-id-123.fb2.zip?sha=4e07408562bedb8b60ce05c1decfe3ad16b72230967de01f640b7e4729b49fce). Please mind that $FB2_id expects the ID of the book to be in lower case.

If you have problems with creating a correct SHA, you can use the following command for Unix console: 

perl -e '\
$time = 1323780017;\
$user=5;\
$art=lc("c4ca9de1-7457-102b-94c2-fc330996d25d");\
$key="<secretkey>";\
use Digest::SHA;\
print "\n\nGood SHA is: ".Digest::SHA::sha256_hex("$time:$user:$art:$key")."\n";'

4.4 Download of Adobe DRM books in English (Type 11)

To download Adobe DRM-protected books in English (type 11), partners shall generate an URL the same way that the URL for text books is generated (type 0), see 1.1. Query format. 
In response to the query, LitRes server does not return the file itself, but a HTTP redirect with the status of 302 to a unique URL, from which the URLLink.acsm license file will be downloaded (i.e., the actual Adobe DRM-protected book).

4.5 Download of media content (all types, except 0 and 11)

To download media content from LitRes server, partners may generate URL according to the following rules:

• HTTP query with domain agreed by the parties and pointing to LitRes server (http://dnlbook.bobook.ru).
• The domain name is followed by a mandatory part of the URL: /get_litres_mm_file/ (e.g., http://dnlbook.bobook.ru/get_litres_mm_file/).

• It is followed by the current UNIX timestamp, time accurate to the second starting from 00:00:00 UTC January 1, 1970. The link is considered valid if the timestamp is behind the current time for more than 12 hours. Times with obsolete timestamp are not processed (e.g., http://dnlbook.bobook.ru/get_litres_mm_file/1223476707/). To reduce sensitivity of URL to time desynchronization between the partner server and LitRes, we recommend using a timestamp overdue for 60 seconds.

  Windows programmers! Please check your timestamps on http://www.timestampgenerator.com/. Please mind, that you can't calculate the timestamp based on the local time value. Timestamp is calculated based on UTC without daylight saving settings. Wikipedia contains plenty of details for the timestamp theory, and a huge set of source files for any language, from Perl to PL/SQL.

• It is followed by user ID (e.g., http://dnlbook.bobook.ru/get_litres_mm_file/1223476707/666/).

• Then a lowcase fb2-ID of the book is specified. The ID may contain invalid characters, and in this case the URL must be "escaped" (e.g., http://dnlbook.bobook.ru/get_litres_mm_file/1223476707/666/fb2-test-id-123).

• Then the file ID is specified (see 1.2. Server response format, updated-book/files/group/file/@id attribute). There may be numerous files like this for a single book (e.g., http://dnlbook.bobook.ru/get_litres_mm_file/1223476707/666/fb2-test-id-123/55689).

• Then the file name is specified that is passed in an updated-book/files/group/file/@filename attribute (see 1.2. Server response format) (e.g., http://dnlbook.bobook.ru/get_litres_mm_file/1223476707/666/fb2-test-id-123/55689/Filatov_Rasskazy_4umnogo_goroda_sample.mp3).

• SHA signature that is generated in a similar way to generating book download links, is added to this link as GET and POST parameter (see 2.1. Query format).
  (e.g., http://dnlbook.bobook.ru/get_litres_mm_file/1223476707/666/fb2-test-id-123/55689/Filatov_Rasskazy_4umnogo_goroda_sample.mp3?sha=4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a). Please mind that $FB2_id expects the book ID to be in lower case, and all files within the book to use the same signature.

4.6 Links life span, number of downloads

Partner links remain valid within 12 hours from the timestamp specified for them. Theoretically, users are allowed to perform up to unlimited number of downloads, i.e. we do not prevent bona fide users from downloading purchased books so many times and in such formats as they want. However, to prevent unauthorized use, there's an actual limitation of 11 repeated downloads, and the count reduces by 2 on a monthly basis. In this case, the following downloads are not viewed as repeated:

• Repeated downloads of text books performed within a 3-minute span from any IP.
• Repeated downloads of text books performed within a 15-minute span from a subnet generated by a 255.255.255.0 mask based on user IP.
• Repeated downloads of text books performed within an hour from the same IP.
• Repeated downloads of non-text books performed within an 8-hour span from any IP.
• Repeated downloads of non-text books performed within a 3-day span from a subnet generated by a 255.255.255.0 mask based on user IP.
• Repeated downloads of non-text books performed within a week from the same IP.

These settings are selected by means of trial-and-error choice, and at the moment they completely prevent any download blocking for bona fide users. We recommend partners to apply more stringent rules, especially for downloads from various IPs, because LitRes may at any time unilaterally change these heuristic settings without previous notification.

4.7 Redirection of users in case of errors

If a user goes to a book download URL and an error occurs, they will be redirected to the URL specified by the partner (see 8. Data provided by partners), and an error message is displayed. In this case, an error parameter is added to the URL that may take the following values:

• sha – incorrect SHA signature.
• unknownbook – the book with this ID is currently unavailable for download.
• not_purchased – the book was not sold to this user.
• not_ready_pending_acsm – the URL to download the Adobe DRM-protected book in English (type 11) is not ready yet. It is still being generated.
• downloads_overquote – the permitted number of downloads exceeded.
• expired – the link contains an expired timestamp (over 12 hours).
• internal – LitRes service internal error.

For instance, if the partner specified URL http://www.partner.ru/dnld_err/?err= (see 8. Data provided by partners) and SHA calculation error occurred, redirect is performed to: http://www.partner.ru/dnld_err/?err=sha.

4.8 Test of notification interface

There is a TEST partner registered on LitRes site for testing purposes, a test tester.litres.ru domain, and a secret key 93w4jfhs8imksGo-oa3s85d6Akmkkbnsi9. For this test partner, a 65830123-26b8-4b07-8098-c18229e5026e (Psychology of Art) is always available. 
You can use the test file https://www.litres.ru/static/get_fresh_book_tester.html to test the list of updates loading, and review the principle of generating queries to API. Later you can download the file and modify it to meet your requirements to testing various queries. 

Sample queries to API:

• A test URL to request an already purchased book: https://tester.litres.ru/partner_user_purchases_a_book/?user=1&art=65830123-26b8-4b07-8098-c18229e5026e&sha=ef2d127de37b942baad06145e54b0c619a1f22327b2ebbcfbec78f5564afe39d.
• A request containing incorrect SHA: https://tester.litres.ru/partner_user_purchases_a_book/?user=2&art=65830123-26b8-4b07-8098-c18229e5026e&sha=e7f6c011776e8db7cd330b54174fd76f7d0216b612387a5ffcfb81e6f0919683.
• A request for purchasing of a book by user 2, that is completed successfully for the purposes of testing: https://tester.litres.ru/partner_user_purchases_a_book/?user=2&art=65830123-26b8-4b07-8098-c18229e5026e&sha=7902699be42c8a8e46fbbb4501726517e86b22c56a189f7625a6da49081b2451.
• A request for a book that is unavailable to the partner: https://tester.litres.ru/partner_user_purchases_a_book/?user=2&art=65930123-26b8-4b07-8098-c18229e5026e&sha=2c624232cdd221771294dfbb310aca000a0df6ac8b66b696d90ef06fdefb64a3.
• Valid (though expired) URL for a user to download a PDF book: https://tester.litres.ru/get_litres_file/1227611964/1/65830123-26b8-4b07-8098-c18229e5026e.a4.pdf?sha=19581e27de7ced00ff1ce50b2047e7a567c76b1cbaebabe5ef03f7c3017bb5b7.

5 Obtaining LitRes book covers

Most (though not all!) books have covers. Default cover usually has the width of 250-300 px, however this is not guaranteed because there may be wider or narrower covers. A partner generates a link to cover image according to the following rules:

• HTTPS request to LitRes (https://partnersdnld.litres.ru).
• The domain name is followed by a mandatory part of the URL: /pub/c/ (https://partnersdnld.litres.ru/pub/c).
• Then you should specify the desired cover format. For a default cover, it is simply /cover (https://partnersdnld.litres.ru/pub/c/cover).
• There are also fixed-size cover versions – with the width of 30, 37, 89, 95, 100, 120, 123, 185, 200, 250, 330 or 415 px (the height is proportional) and with the height of 70, 120, 140, 190, 270, 400 or 1500 (width is proportional). To get a properly formatted standard-size cover, you should replace the /cover with your desired size for covers in /cover_# (e.g., /cover_415.jpg – an image with the width of 415) or /cover_h# (e.g., /cover_h140 – an image with the height of 140) formats. To create a cover with the maximum height, use /cover_max1500 value. Please mind that fixed-size covers are always in jpg format.
• Then you should use an ID and a file format of a book from the list of new books (fb-updates/updated-book/@id). The cover may be in PNG or JPG format. You should check the format in the updates feed, see 1.2. Server response format, updated-book/@cover);
• Generate the complete URL of the cover, e.g.: https://partnersdnld.litres.ru/pub/c/cover_h140/32544407.jpg.

6 Obtaining trial fragments of books

Trial fragments are available on LitRes server for most books. A link for a trial fragment is generated based on the type of a book.

6.1 Trial fragments for text books

For text formats (fb2.zip, fb3, ePub, rtf.zip, txt, txt.zip, a4.pdf, a6.pdf) trial fragments are available from LitRes server via the following type of link: https://partnersdnld.litres.ru/pub/t/123456.fb2.zip, where 123456 is the book ID from the updated-book/@id attribute, and you can use any other extension instead of fb2.zip.

6.2 Trial fragments for PDF books

Trial fragments are available for all PDF books. URLs for trial fragments are generated as https://partnersdnld.litres.ru/get_pdf_trial/123456.pdf, where 123456 is the book ID from the updated-book/@id attribute (section 1.2. Server response format). A fragment is a PDF file that usually contains few starting pages of a book (for instance, 25 pages).

6.3 Fragments of audio books

Fragments are available for all audio books. URLs for fragments are generated as https://partnersdnld.litres.ru/get_mp3_trial/123123.mp3, where 123123 is the book ID from the updated-book/@id attribute (section 1.2. Server response format), trial fragment is represented by an mp3 file.

7 Obtaining the LitRes tree of genres

The complete tree of genres permanently resides here: https://partnersdnld.litres.ru/genres_list_2/. It is recommended to update it once in two weeks or in case of detection of books of unknown genres. 
The tree contains root genres (type="root"), where (or in sub-genres) (type="container") final genres are contained (type="genre"). 
Books from the catalog are always assigned only final genres from this tree (having a type="genre" attribute). However, please mind that the tree of genres may change and final genres (type="genre") may eventually become sub-genres (type="container").
All elements in the tree have identical attributes:

• @id – a unique ID of the genre/sub-genre.
• @token – string ID of the genre/sub-genre.
• @title – name of the genre/sub-genre in Russian.
• @type – the type of the element in the tree Supported values:
  • root – root genre.
  • container – sub-genre that is conventionally defined as a folder for final genres.
  • genre – the final genre.

<genres>
  <genre id="5003" title="Бизнес-книги" type="root">
    <genre id="5049" title="Банковское дело" token="bankovskoe_delo" type="genre"/>
    <genre id="5047" title="Кадровый менеджмент" token="kadrovyj_menedzhment" type="container">
      <genre id="5334" title="Аттестация персонала" token="attestaciya_personala" type="genre"/>
      <genre id="5330" title="Гендерные различия" token="gendernyye_razlichiya" type="genre"/>
      <genre id="5332" title="Конфликты" token="konflikty" type="genre"/>
    </genre>
  </genre>
  <genre id="5013" title="Юмористическая литература" type="root">
    <genre id="5201" title="Анекдоты" token="anekdoty" type="genre"/>
    <genre id="5202" title="Зарубежный юмор" token="zarubezhnyy" type="genre"/>
  </genre>
</genres>

8 Data transferred in the course of partner connection

Data provided to partners

Data provided by partners (must be provided BEFORE connection)