| Оглавление |
|---|
The use of OTAPI methods in the documentation is described for OT Box and mobile application for it as an example.
OTAPI methods can be used and varied in the operation of any sites on various CMS.
General work with OTAPI
All methods are available on documentation page: http://docs.otapi.net/en.
...
Add method name and parameters in GET/POST form to the address depending on query and its size. Some parameters may not nootherwiset fit in GET query, so it is always easier to make POST.
...
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/Android or applicationType=MobileApplication/iOS depends on system.
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/Android or applicationType=MobileApplication/iOS depends on system.
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 session before 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.
...
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:
...
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:
...
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->выбор по языкуfrom GetCommonInstanceOptionsInfo depending on current language, since for example admin can leave VKontakte for Russian and remove for English. Check in TranslatableOptions->choice by language->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
Social networks authorization
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/Android or applicationType=MobileApplication/iOS depends on system. 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
Open "Demonstration MetaUI" plugin:
Choose "Banner settings" in dropdown list and press "Open" button:
Fill in the data and add website (website is required):
After that follow next steps:
You can get a full list of banners configured for application by http://You can get a full list of banners configured for application by http://docs.otapi.net/en/Documentations/Method?name=/GetBanners method, passing parameter applicationType=WebSite (applicationType=MobileApplication/Android or applicationType=MobileApplication parameter./iOS depends on system), instanceKey and language. Send request and get the link:
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:
| Тип действияAction type | ПараметрParameter |
|---|---|
Url | Absolute address of the link to open when you click banner |
Category | ID of the category that should be opened when clicking the banner |
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.
...
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.
...
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=
...
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=
...
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:
Property | Description | Where to show | Comments |
|---|---|---|---|
| DisplayName | vendor name | everywhere | Thanks to this, website admin will be able to change names later, but nothing will change in Mobile Application logic. |
| DisplayPictureUrl | vendor image | everywhere | Only if available, otherwise there is an image stub in recommended vendors, do not display in other places. Thanks to this, website admin will be able to change images but nothing will change in Mobile Application logic.
|
| Credit/Level | vendor rating from 1 to 20 | in product card | Only if available and more than 0, otherwise it does not need to be displayed. |
| Credit/TotalFeedbacks | number of feedbacks | in product card on vendor's page | Only if available and more than 0, otherwise it does not need to be displayed. |
| Credit/PositiveFeedbacks | number of positive feedbacks | in product card on vendor's page | Only if available and more than 0, otherwise it does not need to be displayed. Display as% of total reviews if available. |
| Scores/DeliveryScore | delivery scrore from 1.0 to 5.0 | in product card on vendor's page | Only if available and more than 0, otherwise it does not need to be displayed. |
| Scores/ItemScore | item score from 1.0 to 5.0 | in product card on vendor's page | Only if available and more than 0, otherwise it does not need to be displayed. |
| Scores/ServiceScore | service score from 1.0 to 5.0 | in product card on vendor's page | Only if available and more than 0, otherwise it does not need to be displayed. |
Search
Basic documentation on search.
...
- 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;
- otherwiseOtherwise, a regular search page by phrase.
This approach will allow you to localize search logic and services will be responsible for page display logic.
Product card
Use http://docs.otapi.net/en/Documentations/Method?name=BatchGetSimplifiedItemFullInfo when you open the card for the first time, it's necessary to send the following parameters: RootPath,Vendor,MostPopularVendorItems16,Description
...
| Раскрыть | ||
|---|---|---|
| ||
<Request />
equal to
<Request>
<Current />
</Request>equal to <Request>
<Current Quantity="1" />
</Request> |
| Раскрыть | ||
|---|---|---|
| ||
<Request>
<Current Quantity="5" />
</Request>
Request to current options:
<Request>
<Current ConfigurationId="idconfiguration" />
</Request>
or
<Request>
<Current ConfigurationId="idconfiguration" Quantity="5" />
</Request>
or
<Request>
<Current>
<Property Id="idcolor" ValueId="idRed"
</Current>
</Request>
or
<Request>
<Current>
<Property Id="idcolor" ValueId="idRed"
<Property Id="idSize" ValueId="idMiddle"
</Current>
</Request>
or
<Request>
<Current Quantity="5">
<Property Id="colorid" ValueId="idRed"
<Property Id="idSize" ValueId="idMiddle"
<Property Id="idModel" ValueId="idSomeModel"
</Current>
</Request> |
| Раскрыть | ||
|---|---|---|
| ||
<Request>
<Selected ConfigurationId="идКонфигурацииidConfiguration" Quantity="1" />
<Selected ConfigurationId="идКонфигурацииidConfiguration" Quantity="2" />
...
</Request>
илиor
<Request>
<Selected Quantity="1">
<Property Id="идЦветаidColor" ValueId="идКрасногоidRed"
<Property Id="идРазмераidSize" ValueId="идСреднегоidMiddle"
</Selected>
<Selected Quantity="2">
<Property Id="идЦветаidColor" ValueId="идЗеленогоidGreen"
<Property Id="идРазмераidSize" ValueId="идСреднегоidMiddle"
</Selected>
...
</Request>
Запрос со всем вместе может быть любой комбинацией других видов запросов, напримерA query with everything together can be any combination of other types of queries, for example:
<Request>
<Current Quantity="5">
<Property Id="идЦветаidColor" ValueId="идКрасногоidRed"
</Current>
<Selected Quantity="2">
<Property Id="идЦветаidColor" ValueId="идЗеленогоidGreen"
<Property Id="идРазмераidSize" ValueId="идСреднегоidMiddle"
</Selected>
</Request> |
Что такое What's Current/Selected - и как правильноand what's correct? Current или or Selected?
Если нужен только 1 одновременно выбранный конфиг, то про Selected можно вообще не думать.
Если нужно несколько (как на 1688), то в Selected шлем всё где введено количество.
Избранные товары
If you need only 1 simultaneously selected config, then you can not think about Selected at all.
If you need several (as in 1688), then in Selected send everything where the quantity is entered.
Favourite goods
Get list of items: Получить список товаров: Метод http://docs.otapi.net/ruen/Documentations/Method?name=BatchGetUserData , blockList=Note.
Добавить товар в избранное Add item to favorites: http://docs.otapi.net/ruen/Documentations/Method?name=AddItemToNote , fieldParameters=<Fields/>
Удалить товар из избранного Remove item from favorites: http://docs.otapi.net/ruen/Documentations/Method?name=RemoveItemFromNote , перед удалением требуется подтверждение удаления. confirmation to delete is required before removing.
Move item into cart:Переместить в корзину http://docs.otapi.net/ruen/Documentations/Method?name=MoveItemFromNoteToBasket
Изменить кол-во товара в избранном Change item quantity in favorites: http://docs.otapi.net/ruen/Documentations/Method?name=EditNoteItemQuantity
Изменить комментарийChange comment: http://docs.otapi.net/ruen/Documentations/Method?name=EditNoteItemFields , <Fields><FieldInfo Name="Comment" Value="Текст комментарияText for comment"/></Fields>
Изменить конфигурацию товараChange item configuration:
1. доступные конфигурации получить методами you can get available configurations by the following methods http://docs.otapi.net/ruen/Documentations/Method?name=BatchGetSimplifiedItemFullInfo и and http://docs.otapi.net/ruen/Documentations/Method?name=BatchGetSimplifiedItemConfigurationInfo - так же, как и в карточке товараsimilar to item card.
2. сохранение новой конфигурации осуществляется добавлением новой и удалением старой, т.е. последовательными вызовами new configuration is saved by adding a new one and deleting the old one, i.e. consecutive calls http://docs.otapi.net/ruen/Documentations/Method?name=AddItemToNote (важно передать в метод все fieldParameters от старой записи, иначе можно потерять часть информации, например комментарий пользователя к товару) и it is important to pass all fieldParameters from the old record into the method, otherwise you may lose some of information, for example, user’s comment on a product) and http://docs.otapi.net/ruen/Documentations/Method?name=RemoveItemFromNote
Избранные продавцы
Favourite sellers
Vendors listСписок продавцов: Метод http://docs.otapi.net/ruen/Documentations/Method?name=BatchGetUserData , blockList=FavoriteVendors
Добавить продавца в избранное Add vendor to favorites: http://docs.otapi.net/ruen/Documentations/Method?name=AddVendorToFavorites , fieldParameters=<Fields/>
Удалить продавца из избранного Remove vendor from favorites: http://docs.otapi.net/ruen/Documentations/Method?name=RemoveVendorFromFavorites Требуется подтверждение удаления , confirmation to delete is required before removing.
Корзина
Cart
Get list of itemsПолучить список товаров: Метод http://docs.otapi.net/ruen/Documentations/Method?name=BatchGetUserData , blockList=Basket.Список товаров должен быть разделен по провайдерам,
т.к. в один заказ можно оформить товары только одного провайдера. Пользователя нужно уведомить о минимальной сумме заказа (если она установлена в конфигурации), получить её можно с помощью метода: The list of goods should be divided by providers, as you can order goods of only one provider in one order. User should be notified about minimum order amount (if it is set in configuration), you can get it using http://docs.otapi.net/ruen/Documentations/Method?name=GetCommonInstanceOptionsInfo method (Result->Order->MinOrderCost)
Удалить товар из корзины Remove item from cart: http://docs.otapi.net/ruen/Documentations/Method?name=RemoveItemFromBasket , перед удалением требуется подтверждение удаления.confirmation to delete is required before removing.
Empty cartПолная очистка корзины http://docs.otapi.net/ruen/Documentations/Method?name=ClearBasket , перед очисткой требуется подтверждение.confirmation to delete is required before removing.
Move selected item from cart to favorites:Перенести товар из корзины в избранное http://docs.otapi.net/ruen/Documentations/Method?name=MoveItemFromCartToNote для переноса нескольких отмеченных товаров делается несколько вызовов MoveItemFromCartToNote several calls are made to transfer several marked products MoveItemFromCartToNote
Change quantity of items in the cart: Изменение количества товара в корзине http://docs.otapi.net/ruen/Documentations/Method?name=EditBasketItemQuantity
Добавление/изменение комментария к товару Add/edit comment to item: http://docs.otapi.net/ruen/Documentations/Method?name=EditBasketItemFields <Fields><FieldInfo Name="Comment" Value="Текст комментарияComment text"/></Fields>
Редактирование веса товараEdit item weight: http://docs.otapi.net/ruen/Documentations/Method?name=EditBasketItemFields <Fields><FieldInfo Name="Weight" Value="Число нового веса товараNew weight of an item"/></Fields>
Изменить конфигурацию товараEdit item configuration:
1. доступные конфигурации получить методами you can get available configurations by http://docs.otapi.net/ruen/Documentations/Method?name=BatchGetSimplifiedItemFullInfo и and http://docs.otapi.net/ruen/Documentations/Method?name=BatchGetSimplifiedItemConfigurationInfo - так же, как и в карточке товара methods - similar to item card.
2. сохранение новой конфигурации осуществляется добавлением новой и удалением старой, т.е. последовательными вызовами new configuration is saved by adding a new one and deleting the old one, i.e. consecutive calls http://docs.otapi.net/ruen/Documentations/Method?name=AddItemToBasket (важно передать в метод все fieldParameters от старой записи, иначе можно потерять часть информации, например комментарий пользователя к товару) и it is important to pass all fieldParameters from the old record into the method, otherwise you may lose some of information, for example, user’s comment on a product) and http://docs.otapi.net/ruen/Documentations/Method?name=RemoveItemFromBasket
Профиль
Profile
Get basic information about user (name, email, etcПолучение основной информации о пользователе (Имя, email и т.п.): http://docs.otapi.net/ruen/Documentations/Method?name=GetUserInfo , редактирование этой информации возможно с помощью метода you can edit this information with http://docs.otapi.net/ruen/Documentations/Method?name=UpdateUser method.
Адрес доставки. Адрес доставки создается и редактируется отдельно от основной информации о пользователе. Всего возможно N адресов доставки, где N берется из настройки Delivery address. Delivery address is created and edited separately from basic information about the user. N delivery addresses are possible in total where N is taken from the setting http://docs.otapi.net/ruen/Documentations/Method?name=GetCommonInstanceOptionsInfo UserProfile->MaxProfilesCount. Методы для работы с адресом доставкиMethods for working with delivery address:
- http://docs.otapi.net/ruen/Documentations/Method?name=GetUserProfileInfoList
- http://docs.otapi.net/ruen/Documentations/Method?name=ValidateUserProfile
- http://docs.otapi.net/ruen/Documentations/Method?name=CreateUserProfile
- http://docs.otapi.net/ruen/Documentations/Method?name=UpdateUserProfile
- http://docs.otapi.net/ruen/Documentations/Method?name=DeleteUserProfile
Для пользователя, необходим интерфейс, который позволяет выбрать профиль используемый по умолчанию Interface is required for user that allows to select default profile https://www.screencast.com/t/1fZ9HuauBjf . Выбранный профиль необходимо сохранить в предпочтения пользователяSelected profile must be saved in user preferences: http://docs.otapi.net/ruen/Documentations/Method?name=UpdateUserPreferences , поле ProfileId.ProfileId field.
Get a list of content pages for profile screenПолучение списка контентных страниц для экрана профиля: http://docs.otapi.net/ruen/Documentations/Method?name=GetContentMenuItemTree , параметрыparameters:
applicationType=MobileApplication/Android or applicationType=MobileApplication/iOS depends on system
menuList=Profile
includeContent=true
Список стран, в которые возможна доставка, нужно получить с помощью методаGet list of countries for delivery: http://docs.otapi.net/ruen/Documentations/Method?name=GetDeliveryCountryInfoList .
Get list of citiesСписок городов нужно получать методом: http://docs.otapi.net/ruen/Documentations/Method?name=SearchCities (пока пользователь вводить символы для поиска города, т.е. параметр QueryText пуст, нужно отправить IsMainCity=true для получения списка городов по умолчанию). В момент когда пользователь выбрал город из списка, сохраняем в профиле City и CityCode и автоматически заполняем поле Region.
Важно: CountryCode - обязательно поле для оформления заказа, CityCode - не обязательное поле, если пользователь выбрал город из списка, то система должна передать код в сервисы, если же пользователь ввёл город, которого нет в списке SearchCities, сохраняем только узле City.
Список заказовwhile user enters characters to search for the city, i.e. QueryText parameter is empty, you need to send IsMainCity = true to get a list of default cities). When user selects city from the list, save it in the City profile and CityCode profile and automatically fill in the Region field.
Important: CountryCode - obligatory field for placing an order, CityCode - optional field, system must transfer the code to the services if user selected a city from the list. Save only City node if user entered city that is not in SearchCities list.
Orders list
http://docs.otapi.net/ruen/Documentations/Method?name=SearchOrdersForUser
АктивныеActive: <OrderSearchParametersForUser><IsCancelled>false</IsCancelled><IsCompleted>false</IsCompleted></OrderSearchParametersForUser>
ОтмененныеCancelled: <OrderSearchParametersForUser><IsCancelled>true</IsCancelled></OrderSearchParametersForUser>
ЗакрытыеCompleted: <OrderSearchParametersForUser><IsCompleted>true</IsCompleted></OrderSearchParametersForUser>
Список полей для отображенияThe list of fields to display:
ID заказа, который передается в API во все возможные методы: Id
Номер заказа, отображаемый покупателю: DisplayId
Дата заказа: CreatedDateTime
Статус: StatusName
Сумма: TotalAmount
Уже оплачено: TotalAmount минус RemainAmount
К оплате: RemainAmount
Стоимость товаров: GoodsAmount
Позиций товаров: такой информации нет - не показываем это поле
Заказ. Подробная информация
- Order ID passed in API into all possible methods: Id
- Order number displayed to buyer: DisplayId
- Order date: CreatedDateTime
- Statusс: StatusName
- Sum: TotalAmount
- Already paid: TotalAmount minus RemainAmount
- For payment: RemainAmount
- Goods price: GoodsAmount
- Items positions: do not show this field if there is no such information
Order. Detailed information
Get order informationПолучить информацию о заказе: http://docs.otapi.net/ruen/Documentations/Method?name=GetSalesOrderDetails
Отображаем для пользователя информацию о заказе (узел OrderInfo, подробнее здесь Display order information for user (OrderInfo node, details here http://docs.otapi.net/ruen/Documentations/Type?name=OtapiOrderInfo), особенностиproperties:
- DisplayId - идентификатор заказаorder ID.
- Id - идентификатор заказа, покупателю показывать не надо, этот Id передается в другие методы OTApiorder ID, don't show to the buyer, this Id is passed to other OTApi methods.
- CanCancel - если заказ можно отменить, показываем кнопку "Отменить заказ" display "Cancel order" button if order can be canceled - http://docs.otapi.net/ruen/Documentations/Method?name=CancelSalesOrder
- Для отображения состояния заказа (выбор цветовой гаммы и т.п.), нужно использовать флаги: IsPaid, IsCancelled, IsCompleted
- Use flags: IsPaid, IsCancelled, IsCompleted to display order status (choice of color scheme, etc.)
Display goods list in the order (SalesLinesList node, details about each line is here Отображаем список товаров в заказе (узел SalesLinesList, подробнее о каждой строке здесь http://docs.otapi.net/ruen/Documentations/Type?name=SalesLine)
- Id - идентификатор строки заказа, этот Id передается в другие методы OTApiorder line ID, this Id is passed to other OTApi methods.
- CanBeClosed - возможность отметить что товар получен opportunity to note that goods were received - http://docs.otapi.net/ruen/Documentations/Method?name=CloseLinesOrder
- CanBeCancelled - возможность отменить строку opportunity to cancel the line - http://docs.otapi.net/ruen/Documentations/Method?name=CancelLinesOrder
- CanBeConfirmed - возможность подтвердить строку opportunity to confirm the line - http://docs.otapi.net/ruen/Documentations/Method?name=ConfirmPriceLinesOrder
- необходима возможность массового удаления/подтверждения строк заказа.
- You need the ability to mass delete / confirm order lines.
Shippings list Список посылок - http://docs.otapi.net/ruen/Documentations/Method?name=GetSalesOrderShippings
Заказ. Оформление заказа и выбор способа доставки
В один заказ можно оформить товары только одного провайдера.
При оформлении заказа, потребуется форма выбора адреса доставки или, если адрес ранее на создавался, форма создания адреса/ов доставки (якорь на документацию по профилям доставки).
Order. Placing an order and choosing delivery method
You can place goods of only one provider into one order.
When placing an order, you will need a form for choosing delivery address or, if an address was previously created, a form for creating delivery address / s (delivery profile documentation anchor).
When placing an order, you will need to select a delivery method from provided list: При оформлении заказа, потребуется выбрать способ доставки из предоставленного списка: запрос http://docs.otapi.net/ruen/Documentations/Method?name=SearchDeliveryModes request, параметры xmlSearchParametersxmlSearchParameters parameters:
- ProviderType - ид провайдераprovider ID;
- Weight - вес товаров, в случае оформления из корзины, потребуется получить список товаров методом goods weight, you will need to get a list of goods by http://docs.otapi.net/ruen/Documentations/Method?name=GetPartialBasket , получить сумму веса каждой позиции (для каждого товара нужно умножить вес товара на заказываемое количество method in case of making order from the cart, get the sum of each item weight (for each product you need to multiply item weight by ordered quantity);
- CountryCode - код страны доставки из выбранного адреса доставкиdelivery country code from selected delivery address;
- CityCode - код города доставки из выбранного адреса доставки. delivery city code from selected delivery address.
Parameters exampleПример параметров: <DeliveryModeSearchParameters><CountryCode>RU</CountryCode><CityCode>7700000000000</CityCode><Weight>75.000</Weight><ProviderType>Taobao</ProviderType></DeliveryModeSearchParameters>.
При отображении способов доставки, необходимо учесть флаг IsPickupPointMode.
IsPickupPointMode flag must be considered when displaying delivery methods.
- Show user Delivery address and zip code fields (take field values from selected delivery address) if flag = false.
- Take delivery address and zip code from selected pickup location if flag = true. Provide user with an interface for choosing a pick-up point: show all available pick-up points for current delivery method
- Если флаг = false, показываем пользователю поля Адрес доставки и Индекс (значения полей берем из выбранного адреса доставки).
- Если флаг = true, Адрес доставки и Индекс берем из выбранного пункта выдачи. Предоставляем пользователю интерфейс по выбору пункта выдачи: показываем все доступные пункты выдачи для текущего способа доставки http://docs.otapi.net/ruen/Documentations/Method?name=SearchDeliveryPickupPoints (по умолчанию должен быть выбран пункт выдачи, который сохранен в выбранном адресе/профиле доставки).by default, the pick-up point must be selected, which is stored in selected address / delivery profile).
Save ExternalDeliveryId to user preferences after successful order После успешного оформления заказа, нужно сохранить ExternalDeliveryId в предпочтения пользователя (http://docs.otapi.net/ruen/Documentations/Method?name=UpdateUserPreferences) , а так же обновить параметры адреса доставки, если интерфейс сразу этого не сделал as well as update delivery address parameters, if the interface has not done it immediately (http://docs.otapi.net/ruen/Documentations/Method?name=UpdateUserProfile).
Из корзины
Перед тем как оформить заказ из корзины, необходимо "проверить" актуальность цен и возможность оформления:
From cart
"check" relevance of prices and possibility to buy before placing an order from the cart:
- call после того как клиент выбрал галочками товары которые он хочет оформлять, вызываем метод http://docs.otapi.net/ruen/Documentations/Method?name=RunBasketChecking с выбранными идентификаторами корзины, в ответ получаем и запоминаем "идентификатор активности"
- показываем клиенту оверлей, фразу "Пожалуйста, подождите. Товары в корзине проходят проверку на наличие. Время проверки зависит от количества товаров в корзине" и прогресс бар
- method with selected cart identifiers after customer checked off goods that he wants to buy, we get and save "activity identifier" in response;
- show overlay to client and a phrase "Please wait. Products in the cart are checked for availability. Verification time depends on quantity of goods in the cart" and progress bar;
- call function вызываем функцию http://docs.otapi.net/ruen/Documentations/Method?name=GetBasketCheckingResult передав в нее идентификатор активности
- если в ответе нет ошибки и IsFinished != true, показываем прогресс клиенту из узла ProgressPercent и через одну секунду еще раз вызываем метод GetBasketCheckingResult
- из узла Messages для нужного элемента корзины показываем текст и статус (статус отображаем путем изменения цвета строки, Ok - зеленый, Warning - желтый, Error - красный)
- если IsFinished == true, скрываем прогресс бар и
- если в Messages есть хотя бы один Error - проматываем экран до первой ошибки и предоставляем пользователю возможность исправить ошибку (например выбрать другое количество товаров и по новой запустить проверку корзины)
- если ошибок нет, но есть хотя бы один Warning - проматываем экран до первого предупреждения и предоставляем пользователю возможность повторно нажать на кнопку "оформить заказ", повторное нажатие должно сразу начать процедуру оформления заказа без повторной проверки корзины (важно: если пользователь изменил количество, конфигурацию или выбрал галочками другие товары - процесс проверки корзины должен начинаться заново)
- если нет ни ошибок ни предупреждений, сразу открываем экран оформления заказа.
Важно при каждом изменении выбранных товаров запускать проверку корзины заново, а так же заново показывать сообщения об ошибке/успехе от сервисов.
- passing activity identifier to it;
- show the progress to the customer from ProgressPercent node and call GetBasketCheckingResult method in one second again if there is no error in the response and IsFinished! = true;
- show text and status (display status by changing line color, Ok - green, Warning - yellow, Error - red) from Messages node for necessary item in the cart
- if IsFinished == true hide progress bar and
- scroll the screen to the first error and allow customer to correct the error (for example, select different quantity of products and run checking the cart again) if there is at least one Error in Messages;
- scroll the screen up to the first warning and allow customer to click "place order" button again if there are no errors, but there is at least one Warning. Clicking again should immediately start the process of placing an order without checking the cart again (important: cart checking process should start again if customer changed quantity, configuration or ticked other products);
- immediately open checkout screen if there are no errors or warnings.
It is important to start cart checking again each time customer changes selected products, as well as re-display error / success messages from the services.
You can place an order "from the cart" calling Заказ можно оформить "из корзины", для этого нужно вызвать метод http://docs.otapi.net/ruen/Documentations/Method?name=CreateOrder method, передав в негоpassing:
- элементы корзины (якорь на документацию по корзине)
- способ доставки
- профиль пользователя
- не обязательно: можно предложить пользователю ввести комментарий к заказу.
Дозаказ
- cart elements (cart documentation anchor)
- delivery methid
- customer profile
- optional: comment for the order.
Follow-up Order
Allow customer to make a follow-up order (if customer has such an opportunity) when making an order. Get orders that allow to make a follow-up order, call При оформлении заказа, нужно предложить пользователю возможность сделать дозаказ (если такая возможность у пользователя имеется). Получаем заказы, в которые можно сделать дозаказ, вызов http://docs.otapi.net/ruen/Documentations/Method?name=SearchOrdersForUser с параметрами xmlSearchParameters=<OrderSearchParametersForUser><ProviderType>ИдПровайдера(например: with parameters xmlSearchParameters= <OrderSearchParametersForUser><ProviderType>IDProvider(for example, Taobao)</ProviderType><IsAvailableForRecreation>true</IsAvailableForRecreation></OrderSearchParametersForUser>если такие заказы есть, предлагаем покупателю выбрать: оформляет он новый заказ или делает дозаказ. Для дозаказа нужно вызвать метод . Allow customer to choose if he makes a new order or a follow-up order if there are such orders. Call http://docs.otapi.net/ruen/Documentations/Method?name=RecreateOrder method for follow-up order.
Быстрый заказ
Quick order
It is possible to make an order from item card by "Quick order" button. Call Заказ можно оформить из карточки товара, кнопка "Быстрый заказ", для этого нужно вызвать метод http://docs.otapi.net/ruen/Documentations/Method?name=AddOrder , передав в него:
- список оформляемых товаров (для быстрого заказа из карточки 1688, это несколько товаров разной конфигурации). Для каждого товара обязательно нужно передать ид товара, ид конфигурации и количество (остальные возможные параметры передавать не нужно)
- способ доставки
- профиль пользователя
- не обязательно: можно предложить пользователю ввести комментарий к заказу.
Оплата заказа и пополнение лицевого счета
method sending:
- a list of ordered goods (for quick ordering from card from 1688.com, these are several products of different configurations). It is necessary to pass product ID, configuration ID and quantity for each product (no other parameters need to be passed);
- delivery method
- customer profle
- optional: comment for the order.
Order payment and recharging personal account
If the order is not paid, be sure to offer customer to pay it. Call Если заказ не оплачен, обязательно предлагаем пользователю его оплатить. Если на лицевом счете клиента есть средства - запрос http://docs.otapi.net/ruen/Documentations/Method?name=GetAccountInfo , узле AvailableAmount (при отображении обязательно используем CurrencySign) , предлагаем пользователю кнопку, которая оплатит заказ с лицевого счета. На кнопке пишем сумму доступную для оплаты, это должна быть или RemainAmount из информации о заказе method if there are funds in customer's personal account, AvailableAmount node (definitely use CurrencySign for display), offer customer a button that will pay for the order from personal account. Write available payment amount on the button, this should be RemainAmount from order information http://docs.otapi.net/ruen/Documentations/Method?name=GetSalesOrderDetails (при условии что на лицевом счете больше чем RemainAmount) или AvailableAmount (при условии что на лицевом счете меньше чем provided that personal account has more than RemainAmount) or AvailableAmount (provided that personal account is less than RemainAmount).
При нажатии на кнопку вызываем метод Call http://docs.otapi.net/ruen/Documentations/Method?name=PaymentPersonalAccount и обновляем страницу заказа. method when clicking the button and refresh order page.
Order can be paid through payment systems. Request a list of available payment systemsЗаказ можно оплатить и через платежные системы. Запрашиваем список доступных платежных систем: http://docs.otapi.net/ruen/Documentations/Method?name=GetPaymentModes . Картинка ПС - AbsoluteImageUrl, название ПС - Name. При клике на платежную систему, отображаем кнопку "Оплатить" и если узел CustomField Image of PS - AbsoluteImageUrl, name of PS - Name. Display "Pay" button after clicking payment system and display email input field if CustomField node == "Email" - отображаем поле ввода почты, если узел CustomField , display phone number input field if CustomField node == "Phone" - отображаем поле ввода номера телефона.
При клике на кнопку Оплатить, вызываем метод Call http://docs.otapi.net/ruen/Documentations/Method?name=GetPaymentParameters . Передаем параметры Amount (RemainAmount из информации о заказе after clicking "Pay" button. Pass the following parameters: Amount (RemainAmount from order information), CurrencyCode, PaymentSystemId, OrderId, в SuccessUrl и FailUrl адреса возврата, которые приложение сможет перехватить. По полученному ответу формируем http-форму, открывем её в браузере, и отправляем её.:and FailUrl return addresses that application can intercept.
Form http-form based on received response, open it in browser and submit it:
- RequestUrl - url to send the form to;
- RequestMethod, if it doesn’t come, send a POST form (sometimes you have to send GET, according to parameter);
- IsNewWindow - you need to open the form in a new window or in the current one, parameter is apparently not relevant for a mobile application - we always open request in a new browser window;
- IsIFrame - display iframe src
- RequestUrl - url на который нужно отправить форму
- RequestMethod , если не пришел отправляем POST форму (иногда приходится отправлять GET, согласно параметру)
- IsNewWindow - нужно открыть форму в новом окне или в текущем, для мобильного приложения параметр видимо не актуален - всегда открываем запрос в новом окне браузера
- IsIFrame - вместо form отображаем в браузере iframe src={RequestUrl}?{Parameters вида type param1=value1¶m2=value2} in browser instead of form;
- IsImmmediate - пока игнорируем в мобильном приложении
- Parameters - список параметров платежа6 которыее надо обработать в зависимости от свойства IsUserData7
- Если IsUserData==false, параметр нужно вставить в форму, для передачи в платежную систему.
- Если IsUserData==true, параметр нужно просто вывести на экран.
Если в метод GetPaymentParameters не передать OrderId , то лицевой счет клиента пополнится на сумму Amount.
После успешного или неуспешного платежа, браузер вернется на один из переданных адресов, соответственно приложение должно их перехватить, закрыть браузер, и показать соответствующий экран.
- ignore in mobile application at the moment;
- Parameters - list of payment parameters to be processed depending on property IsUserData7
- parameter must be inserted into the form to pass to payment system if IsUserData==false;
- display parameter on the screen if IsUserData==true.
Customer’s personal account will be replenished by Amount if you don't pass OrderId into GetPaymentParameters method.
Browser will return to one of the transmitted addresses after successful or unsuccessful payment, accordingly application should intercept them, close browser and show appropriate screen.