Начальная работа с OTAPI при разработке мобильного приложения

General work with OTAPI

All methods are available on documentation page: http://docs.otapi.net/en.

Send GET/POST request to http://otapi.net/service/ to get response from api in xml format.

Send GET/POST request to http://otapi.net/service-json/ to get response from api in json format.

Add method name and parameters in GET/POST form to the address depending on query and its size. Some parameters may not fit in GET query, so it is always easier to make POST.

The ErrorCode node necessarily comes in the response from api, if it is not equal to 'Ok' and not equal to 'BatchError' - it is necessary to process the error. Errors must be separated by value in the ErrorCode and / or SubErrorCode nodes.

Some ErrorCode that can be processed globally at the application level:

• SessionExpired - buyer's or administrator's session has expired, it's necessary to offer user log in and repeat his actions.
• AccessDenied - access to this method is forbidden for this user.
• InstanceKeyBan - application key is blocked, contact managers in your skype chat for details. It's advisable to show "Technical work is done on the site" for application user.
  
  

In some cases, the error message must be shown to the user. It is stored in the Errordescription node and comes with the translation for the language specified when querying in the 'language' parameter.

Application start

You need to get application settings when you start it: http://docs.otapi.net/en/Documentations/Method?name=GetCommonInstanceOptionsInfo with parameter applicationType=MobileApplication.

Application should get a list of available languages from the settings and provide user with an interface to choose application language (if there is more than one language in the list). Further queries to api are called with this language. When starting, the application should take the first language from the list in the settings, check user session (anonymous or authorized) with this language and get application language from the user’s preferences (for more details see working with the user block).

It is also necessary to request a list of translations for application interface at the start: http://docs.otapi.net/ru/Documentations/Method?name=GetApplicationUITranslations with language and parameter passing applicationType=MobileApplication.

The list of successfully received settings must be cached. It is worth clearing settings cache in the background without slowing down application’s operation with this request. It’s worth clearing cache in background either every N hours or every time the application starts. Settings are the same for the entire application and do not differ for different users.

The first time mobile application starts, it must ask user for permission to receive push notifications. It is necessary to send application push token to the services http://docs.otapi.net/ru/Documentations/Method?name=SetUserPushNotificationToken if the user agreed to receive push notifications. Application should monitor relevance of the push token and update it if necessary in the future.

Receiving session (user authorization)

Working with the user - highlights

Some otapi methods require customer's session parameter. It's necessary to get a sesstion bfore working with logic for users. Initially, you need to get an anonymous session using http://docs.dev.otapi.net/en/Documentations/Method?name=GetAnonymousSession method so that the shopping cart, preferences (for example) and so on could be saved on it. All data will be automatically transferred if the previous anonymous session was transferred during authorization. Obtained session must be saved in the application memory and used later for all requests.

Any method using user session may return SessionExpired error, which means that session has expired. In this case you need to transfer user to authorization with the corresponding message, and return user to the place where the error occurred when new session is successfully received.

The easiest way to force session verification by http://docs.otapi.net/en/Documentations/Method?name=GetUserStatusInfo method. It is the least time consuming.

Registration

User registration is carried out by http://docs.otapi.net/en/Documentations/Method?name=RegisterUser method
Check input data before calling this method:

• Email, Login, Password - obligatory parameters;
• Password length must be at least 6 characters;
• Email line is really an email address.

Additional obligatory flag field "I accept the user agreement" should be in the registration form. Registration without this flag is not allowed.

Check Result-> IsEmailVerificationUsed field in the response after successful registration using RegisterUser method. Show message to user "An email was sent to your mail with a link to activation to activate account" if IsEmailVerificationUsed = "true". You need to authorize user immediately (set a new SessionId for him received in response to services) if IsEmailVerificationUsed = "false".

Activation after registration

Together with the message that email was sent, you need to display input field for activation code. You should call http://docs.otapi.net/en/Documentations/Method?name=ConfirmEmail when user checks email and enters the code in the application. There is a field Result->SessionId->Value in response ConfirmEmail which contains authorized user session. Based on this session, you must immediately authorize user in the application.

Authorization

Users' authorization is carried out by http://docs.otapi.net/en/Documentations/Method?name=Authenticate method.
Authorization form should contain the following fields: login (userLogin), password (userPassword) and remember me flag (rememberMe). Check input data before calling Authenticate method:

• userLogin, userPassword are obligatory parameters

sessionId parameter in Authenticate method is the session identifier of an unauthorized customer.

Login as well as user's email can be transferred as userLogin. Probably it is worthwhile to somehow suggest this in the interface.

Social networks authorization

Social Networks Authorization (OT API)

Get the list of available social networks in settings Список социальных сетей надо брать в настройках от GetCommonInstanceOptionsInfo в зависимости от текущего языка, так как например админ может оставить ВКонтакт для русского, и убрать для английского. Смотреть в TranslatableOptions->выбор по языку->ExternalAuthentications.

Password recovery

Password recovery is done by http://docs.otapi.net/en/Documentations/Method?name=RequestPasswordRecovery method.  
Field userIdentifier may contain user login or email. After calling RequestPasswordRecovery, show user the message "Further instructions were sent to your email" and display a form with confirmation code and two text fields for entering the password. User checks code in the email, returns to the application, enters the code and new password. If both fields with password match, then you need to call http://docs.otapi.net/en/Documentations/Method?name=ConfirmNewPassword. ConfirmNewPassword response has Result-> SessionId-> Value field that contains an authorized user session. Based on this session, you need to authorize user in the application immediately.

Application home page

Get collections

Use http://docs.otapi.net/en/Documentations/Method?name=BatchSearchRatingLists method to get collections. We pass the following parameters at the first request:

<BatchRatingListSearchParameters><UseDefaultParameters>true</UseDefaultParameters></BatchRatingListSearchParameters>

and parameter applicationType=MobileApplication. Received data for each collection has a serial number for sorting <Order> 0 </Order>, you need to display collections on the application screen according to this sorting. It is recommended to show collections only from cache. Collections in cache must be updated in background: every 60 minutes, request BatchSearchRatingLists method and save result in the cache. When receiving a response, you need to check HasTranslateErrors node (http://docs.dev.otapi.net/en/Documentations/Type?name=BatchRatingListsSearchResultAnswer), if the node is "true", then you do not need to cache the response. You must check HasError node (http://docs.dev.otapi.net/en/Documentations/Type?name=RatingListSearchResult) for each RatingList element in the response, if the node is true, then this collection item does not need to be cached.

Thus, we get a situation when buyer sees collections from cache. At the same time, collections in the cache have no errors. Situation is possible when we show user outdated information, while we are sure that this information is error-free.

Get banners

You can get a full list of banners configured for application by http://docs.otapi.net/en/Documentations/Method?name=GetBanners method, passing applicationType=MobileApplication parameter.

Each banner will have its name, image address, type of action, and action parameter. The current types of actions and the meaning of their parameters are listed below.

The current types of actions and their parameters purpose are listed below:

Short categories menu

TODO:

Social networks

TODO:

User Preferences

• Currencies. The list of available currencies must be shown from application settings GetCommonInstanceOptionsInfo Currencies node.
• Delivery country. The list of available countries must be shown from application settings GetCommonInstanceOptionsInfo DeliveryCountries node. The list of countries must be displayed taking into account current language of application (all translations can be found in TranslatableOptions node).
• Application language. Show the list of available application languages from application settings GetCommonInstanceOptionsInfo Languages node.

Customer may have a number of preferences-settings on which otapi answers or behavior of the system / application depend on in the future.

You can get currently selected preferences using http://docs.otapi.net/en/Documentations/Method?name=GetUserPreferences method.

User preference can be changed using http://docs.otapi.net/en/Documentations/Method?name=UpdateUserPreferences method.

Application interface should allow users to change their preferences.

Categories list

Send a request first: http://docs.otapi.net/en/Documentations/Method?name=GetRootCategoryInfoList - we get a list of website root categories. This list can be cached for 24 hours. Then make a separate request for attempt to expand each category - http://docs.otapi.net/en/Documentations/Method?name=GetCategorySubcategoryInfoList. Each list can be also cached for 24 hours using parent category identifier in the key.

category contains other categories (that is it can be expanded) if the flag <IsParent> true </IsParent> has come for it.

Don't show category in catalog if it is hidden <IsHidden>true</IsHidden>.

Flag <IsVirtual>true</IsVirtual> means that category doesn't contain goods (only other subcategories).

Absolute image address for category can be returned (image is set by administrator in admin panel) in the optional <IconImageUrl> node http://open-demo.otcommerce.com/uploaded/category/zh_odezhda.jpg </IconImageUrl>.

Recomended vendors page

http://docs.otapi.net/en/Documentations/Method?name=BatchSearchRatingLists method, xmlSearchParameters=

<BatchRatingListSearchParameters><RatingLists><RatingList><CategoryId>0</CategoryId><ItemRatingType>Best</ItemRatingType><IsRandomSearch>false</IsRandomSearch><ContentType>Vendor</ContentType><FramePosition>0</FramePosition><FrameSize>20</FrameSize></RatingList></RatingLists></BatchRatingListSearchParameters>

FrameSize - number of vendors on the page, TotalCount will be returned in the response - the total number of recommended vendors. You can draw pagination based on TotalCount and FrameSize.

Recomended brands page

http://docs.otapi.net/en/Documentations/Method?name=BatchSearchRatingLists method, xmlSearchParameters=

<BatchRatingListSearchParameters><RatingLists><RatingList><CategoryId>0</CategoryId><ItemRatingType>Best</ItemRatingType><IsRandomSearch>false</IsRandomSearch><ContentType>Brand</ContentType><FramePosition>0</FramePosition><FrameSize>20</FrameSize></RatingList></RatingLists></BatchRatingListSearchParameters>

FrameSize - number of brands on the page, TotalCount will be returned in the response - the total number of recommended brands. You can draw pagination based on TotalCount and FrameSize.

Vendors display

The following properties should be used on recommended vendors page, in product card in vendor's block, for viewing all goods of vendor and for displaying information about the vendor:

Search

Basic documentation on search.

Use only one convenient search method to search for goods: http://docs.otapi.net/en/Documentations/Method?name=BatchSearchItemsFrame

To open a category / seller / brand or search query for the first time, call BatchSearchItemsFrame method with the blockList parameter: SubCategories,HintCategories,Vendor,Brand,Category,RootPath,SearchProperties,AvailableSearchMethods. Send search parameters in xmlParameters (for example, category ID <CategoryId>otc-3</CategoryId> or search or search query <ItemTitle>dress</ItemTitle>). We recommend sending <UseOptimalFrameSize>true</UseOptimalFrameSize> with search parameters. This will allow to get optimal number of products per page for this request.

Display information received in the response.

AvailableSearchMethods node contains all search methods available for current query. Allow customer to change search method if there are more than one search methods.

Find detailed information about the current search method that the query is now made in Items node, using values from Provider and SearchMethod nodes (for example: <Provider> Taobao </Provider> <SearchMethod> Extended </SearchMethod>) in AvailableSearchMethods. Using this information we provide user with filters available on the current search page. The correspondence of fields from information about search method and search parameters can be found in basic documentation.

Show SubCategories (Subcategories), HintCategories (You may be interested) to user. Categories that match current search query (Specify category) come up in Items - Categories node. Show goods from Items - Items node. Check the flag IsSellAllowed = true and SellDisallowReason = "IsFiltered" for the product - then we show the stub for the product - product is not allowed for purchase. Show error: NotFound - product was deleted, NotAvailable - product is unavailable instead of product image if product ErrorCode is not equal to "OK". For all other error codes just show the word "Error".

It is a good practice to change display depending on which nodes are returned in response to BatchSearchItemsFrame request. If:

• Vendor node has arrived, show user vendor's page with vendor description;
• Brand node has arrived, show brand page with brand description;
• Category node has arrived, show category page with category description;
• otherwise, a regular search page by phrase.

This approach will allow you to localize search logic and services will be responsible for page display logic.

Карточка товара

При первом открытии карточки, нужно использовать метод: http://docs.otapi.net/ru/Documentations/Method?name=BatchGetSimplifiedItemFullInfo , нужно передавать следующие blockList: RootPath,Vendor,MostPopularVendorItems16,Description

Отображаем карточку товара:

• Хлебные крошки категорий для данного товара (RootPath).
• Название (Item.Title).
• Видео (Item.Videos) и фото (фото представлены в трех размерах: маленький, средний, большой), в качестве главного фото, всегда показываем первое изображение из списка.
• По желанию можно показать особенности товара (показываем все Item.Features у которых есть DisplayName) и вес товара (Item.Weight).
• По желанию можно показать информацию о продавце Vendor и его несколько товаров VendorItems.
• Все характеристики товара (Item.Properties) и описание товара (Description) занимают большую часть экрана, их обычно отображают в конце карточки.
• Отображаем список всех конфигураций товара (Item.Configurators, где Item.Configurators.Property - это свойство, а Item.Configurators.Property.Value - значение свойства).
  Если есть атрибут MultiInputPropertyId узла Item.Configurators.Property, данное свойство необходимо нарисовать в виде таблицы, с возможностью выбрать количество каждого значения этого свойства, пример: https://www.screencast.com/t/Ye5kaULlmWJ .

Отображаем цену товара:

используем метод: http://docs.otapi.net/ru/Documentations/Method?name=BatchGetSimplifiedItemConfigurationInfo , нужно передавать следующие blockList: AdditionalPrices (первый раз запрос можно сделать с пустым xmlRequest)

• Проверяем возможность купить данный товар и причину отказа от покупки (Configuration.Availability).
• Отмечаем какие свойства выбраны пользователем (Configuration.Configurators.Property.Value - Selected="true"), а какие не доступны для выбора (Configuration.Configurators.Property.Value - Disabled="true").
• Отображаем зависимость цены от количества (если пришел узел QuantityRanges).
• Если пришел узел MultiInputConfigurations, то показываем цену каждой конфигурации из MultiInputConfigurations, иначе показываем цену из узла Current:
  • Price - цена за 1шт. (если есть атрибуты Min и Max - то нужно показать не одну цену, а диапазон цен)
  • OldPrice - цена без скидки за 1шт. (если скидки нет, узел отсутствует)
  • DiscountPercent - процент скидки для OldPrice. (если скидки нет, узел отсутствует)
  • InternalDelivery - цена внутренней доставки (если узел отсутствует, показывать не надо)
  • AvailableQuantity - доступное количество для покупки.
• Выводим итоговую стоимость из узла TotalCost.
• Добавляем информацию о возможной добавочной стоимости (AdditionalPrices).

<Request />
равнозначен
<Request>
    <Current />
</Request>
равнозначен
<Request>
    <Current Quantity="1" />
</Request>

<Request>
    <Current Quantity="5" />
</Request>
Запрос на текущие опции:
<Request>
    <Current ConfigurationId="идКонфигурации" />
</Request>
или
<Request>
    <Current ConfigurationId="идКонфигурации" Quantity="5" />
</Request>
или
<Request>
    <Current>
        <Property Id="идЦвета" ValueId="идКрасного"
    </Current>
</Request>
или
<Request>
    <Current>
        <Property Id="идЦвета" ValueId="идКрасного"
        <Property Id="идРазмера" ValueId="идСреднего"
    </Current>
</Request>
или
<Request>
    <Current Quantity="5">
        <Property Id="идЦвета" ValueId="идКрасного"
        <Property Id="идРазмера" ValueId="идСреднего"
        <Property Id="идМодели" ValueId="идНекойМодели"
    </Current>
</Request>

<Request>
    <Selected ConfigurationId="идКонфигурации" Quantity="1" />
    <Selected ConfigurationId="идКонфигурации" Quantity="2" />
    ...
</Request>
или
<Request>
    <Selected Quantity="1">
        <Property Id="идЦвета" ValueId="идКрасного"
        <Property Id="идРазмера" ValueId="идСреднего"
    </Selected>
    <Selected Quantity="2">
        <Property Id="идЦвета" ValueId="идЗеленого"
        <Property Id="идРазмера" ValueId="идСреднего"
    </Selected>
    ...
</Request>

Запрос со всем вместе может быть любой комбинацией других видов запросов, например:
<Request>
    <Current Quantity="5">
        <Property Id="идЦвета" ValueId="идКрасного"
    </Current>
    <Selected Quantity="2">
        <Property Id="идЦвета" ValueId="идЗеленого"
        <Property Id="идРазмера" ValueId="идСреднего"
    </Selected>
</Request>