Autopurchase module helps to process orders (automatic performance) on trade provider (Taobao, 1688, etc.).
There are 3 types of ordering systems involved in the process:
Your ordering system (ОТ API customer).
OT Platform ordering system.
Trader provider ordering system (Taobao).
The whole process can be outlined in the following scheme (using processes numeration mentioned above):
1 → 2 — Add orders into OT Platform system
2 ↔ 3 — Autopurchase operation (orders export; statuses synchronization (goods and order), delivery tracking codes, etc.
2 → 1 — Operation with orders after Autopurchase processing
It is required to add orders from your system to OT Platform ordering system via API since Autopurchase module works only with orders in OT Platform ordering system. Further Autopurchase process is available when orders are added.
Autopurchase module requires registration on trade provider website and does not replace communication with vendors (available products coordination, shipping questions, defects, etc.). It is required to discuss personally all terms and conditions of cooperation with vendor who added goods to trade provider website (if necessary).
It is required to create user in OT Platform admin panel. Follow these steps:
Click the link: http://open-demo.otcommerce.com/ik.php
Enter your Instance Key:
Enter login and password to admin panel that you received from tech support with your Instance Key:
Go to Users > Customers and create any user. (You can contact OT manager in Skype chat created for your project if you have questions.)
Save login and password of created user (write down or memorize) for further settings.
Go to Configuration > Delivery > External and add external delivery with free (null) cost. (You can contact OT manager in Skype chat created for your project if you have questions.) This action is required because orders in OT Platform are bind to delivery. Configuration itself is not important, therefore we make it free. ortant we set the shipping free).
Save (write down or memorize) delivery ID for further settings.
Types of sessions
Admin/operator session — required for all operator’s actions including operations with Autopurchase module and receiving information about orders to synchronize them and change their statuses. Available by AuthenticateInstanceOperator method sending your admin login and password (received from tech support with your Instance Key)
User/Customer session — required to add orders from user’s name. It is username and password of a user from your site. Available by Authenticate method sending user login and password previously created. You can get session ID using AuthenticateInstanceOperator method.
Provider session — required for operations with Autopurchase module. It is bound with external systems like Taobao and (in this example) depends on your Taobao account and login. Read more how to get in description of Autopurchase module.
Add orders into ОТ Platform system
Use AddOrder to add orders into ОТ Platform system. AddOrder always creates one order, but the order can be any number of products
The following things required:
User/Customer session (created login and password during initial settings)
- Order description in xml format
Order in xml format
General information about order:
DeliveryModeId — delivery identifier (added earlier)
Comment — comments to order (optional)
UserProfileId — customer profile identifier (available by GetUserProfileInfoList method by customer session)
Orders lines list (products descriptions):
Id — product identifier
ConfigurationId — product configuration identifier (goods options), value 0 should be send if product doesn’t have options.
Quantity — product quantity
Weight — product weight, unimportant in this case, optional value
Comment — comment to product (optional value)
PromotionId — product discount identifier, optional value for order without discount
It’s recommended to save orders IDs for synchronization with your system or send your identification information as comments.
All parameters will be pre-tested. Goods will be deleted from order if it can’t be ordered.
In response AddOrder method will give information about ready order or an error message. It is necessary to verify list of products in ready order and the one that was sent into the method.
One can proceed with orders operations if all of them were sucessfully ordered and you are satisfied with their components: control, synchronization and autopurchase.
One can cancel the order by CancelSalesOrder method sending customer session and order ID if gaps are unacceptable and attempt to re-add order with other parameters.
Possible reasons of errors
It’s possible to check possible errors list for the order and solve the problem despite the fact that a clear failure reason can’t be sent.
Product is no longer available (ended in warehouse, etc.). Remove item from goods list or select the same at another seller.
No such configuration on website (or ended) . Choose another configuration (color, size, etc.) or select the same at another seller.
No such seller on website . Select the same product at another seller.
Mistake in any document field . Check the data you entered is correct.
AddOrder method result: order from your system was sent to ОТ Platform system (that is it was sent from block 1 to clock 2).
Order payment simulation
Admin session is required.
It’s impossible to send unpaid order into Autopurchase because system is configured for active website with payment systems. It’s necessary to set order payment simulation under the scheme described below until we develop a different solution on this issue .
All actions are divided into 2 parts:
Deposit funds to customer account.
Order payment from customer account.
Real money transfer is not required!
Deposit funds to customer account
It’s possible to deposit funds with PostTransaction method. Required:
Customer (account) ID.
Value true is sent to isDebit (because we deposit).
Comment and date are optional.
Customer ID and sum can be found in order information received in answer to AddOrder (or get separately by GetSalesOrderDetailsForOperator method — admin session also, order ID, empty string can be sent to filter parameter, value in queryType is 0. Method will be useful further on.)
Order payment from customer account
Method SalesPaymentReserve will be used for payment from customer account.
Order is paid and it’s possible to export it to trade provider system if both operations were successful.
Method GetSalesOrderDetailsForOperator is used to check order status. It will be also used to get information from provider such as track numbers, status, etc.
If you have account at Taobao.com, you can add Taobao as trade provider.
Autopurchase does not work for Tmall products.
About 1.5 years ago part ofTmall discounts have been blocked inTaobao api and are not provided any more.
The exclusive method of getting Tmall discounts, developed by OpenTrade Commerce, which is used in OT System, does not allow to get these discounts by Autopurchase module, as the automatize purchase system works with discounts provided via Taobao api only.
You need the following data for connection:
List of Taobao usernames , which will be used to purchase (you can use unlimited number of logins). Attention! Phone number is not used as login. Login is a nickname of customer account:
Parcels recipient info (warehouse information) in Chinese:
Name of recipient (If not specified, transliterated name of the buyer will be set) — Note! The name has to be 2 to 14 characters.
Recipient mobile number (11 characters).
Region code (you can find it by selecting the inner delivery region in admin).
Postal code (zip-code).
Warehouse address in Chinese except the region. For example, if the region was selected as Beijing, you don’t have to write the city name in the address field. Or if you’ve selected any district of Beijing above, you don’t have to write its name.
Mobile number: 11147043234
Region code : 150784
Postal code: 021400
If you have any questions, you are welcome to contact OT manager in your project’s Skype chat.
Getting provider session
If you use many accounts in the provider system (such as Taobao), then each account will have its own session. All the sessions after receipt are stored in OT Platform system and used not only for export, but also, for example, for automatic background synchronization.
As the estimated lifetime of Taobao session is 24 hours, we reccomend you to pass through all the accounts and get sessions for them every day before starting to work with them .
If the session has already been received, it is possible to educe it by GetProviderOrdersIntegrationSessionInfoList method. Unfortunately, the geting process requires operator manual actions and can not be fully automated.
To get the session, you need:
URL with processor on your site, where Taobao will return operator after login.
Call up GetProviderOrdersIntegrationSessionAuthenticationInfo method, by passing your return address (paragraph 1). As a reply you’ll get the address that you have to open for operator.
Open the received address for operator in browser.
Operator have to enter Taobao account and confirm that he allows working with it in OT Platform System.
After that your browser will get back to the return address (paragraph 1), and parameters will show completed session or error text.
The session can be saved or reopened again by requesting the list by GetProviderOrdersIntegrationSessionInfoList method.
All other operations with Autopurchase module undescribed above except getting can be run for an indefinite time and be interactive (require operator actions), therefore they are implemented in the system of background activity. Each used method gives background activity ID, all actions take place within it and it can be controlled and managed via general methods.
There are 4 manual actions with Autopurchase module.
1. Order export into provider
RunOrderExportingToProvider method gets:
structure where order ID and order lines IDs are specified.
The whole order (exactly all available lines) will be exported if order lines are not listed. But it is possible to export part of order if specific order lines are listed.
First, there is a check for goods availability, configurations, prices accuracy. Each discrepancy will send an issue to operator what to do with such product. Activity is suspended in case of question until gets a response. Read more about it in section about background activity.
Then goes attempt to export. If successful, order (or several) will be visible in provider system (in Taobao) and order lines in OT Platform system will contain information which line belongs to which provider order. Further synchronization will be processed according to this information. Information about error (if it occurs) will be reported in background activity.
Incorrect address settings for autopurchase (data for Taobao: address in China, phone number, etc. It is required to enter correct data).
Limit of unpaid orders in provider system (booked orders limit exceeded. each trade provider has limit for booked orders number. It is required to deposit funds on trade provider website and buy part of goods.)
Missed inconsistencies upon discrepancy check such as insufficient quantity, etc.
Other errors like bad connection with provider, works in provider system or OT Platform system, etc.
In addition, OT Platform system settings can include export check if it was successful. In this case, system will report an error, for example, item was with a discount but it was booked without discount.
2. Manual synchronization
RunOrdersSynchronizingWithProvider method gets:
It is possible to run synchronization manually even if it runs periodically automatically in background.
All exported orders are checked during synchronization, statuses change if they changed on provider side (for example, vendor sent parcel), tracking numbers are set, etc.
Synchronization is one-sided and order will not be cancelled in provider system if it was cancelled in OT Platform system (Taobao allows in only manually on the website). Therefore, it is required to cancel order manually in provider personal account for the order to get cancelled status. Order will have uniform status in all systems after synchronization.
3. Manual binding of orders
RunOrderLinkingWithProvider method gets:
structure with order ID and provider orders list.
It is not always possible to book (export) goods automatically. The main reason in Taobao case is special TMall discounts that are unavailable automatically.
It is possible to buy manually and bind orders to use synchronization benefits. Further on they will be synchronized similarly to automatically exported orders.
System itself will try to define matching products in chosen orders and will ask operator what to do with them if it does not find.
4. Unbind order
RunOrderUnlinkingFromProvider method gets:
structure with order ID and provider orders list.
All bound lines will be unbound if order lines are not listed.
First, it is important to unbind order lines before retry if export sometimes goes wrong or wrong orders are bound or you don’t want to synchronize them.
Orders processing in OT Platform system
Detailed information about order
It is possible to check orders for necessary information if you saved OT Platform orders ID in your system.
GetSalesOrderDetailsForOperator method gives detailed information about order. It includes admin session, order ID. Filter parameter can be blank and queryType value can be 0.
It is worth paying attention to order lines list in method response (SalesLinesList property). The following things are important in each of them:
StatusId/StatusName — item status, it changes according to status of provider order. Compliances can be set according to “Autopurchase module settings” section of this manual.
VendPurchId — provider order ID.
VendPurchWaybill — invoice number , delivery tracking number sent by vendor.
VendPurchAccountId — account name that purchased goods.
VendPurchStatus — original status of goods in provider order that was not sent to OT Platform.
VendPurchItemId / VendPurchConfigurationId / VendPurchPromotionId — goods ID / configurations / discounts in provider order.
Search of order lines by provider order ID
You can get information on order in OTPlatform if you know provider order ID (for example, it is visible in orders list in personal account on Taobao).
Use SearchOrderLines method with xmlSearchParameters parameter like this to get information:
Search of order line by tracking number
You can get information on order in OTPlatform if you know delivery tracking number. For Taobao it is invoice number printed on parcel and delivered to your warehouse. It is available there as a bar code that you can pick if you have scanner.
Use SearchOrderLines method with xmlSearchParameters parameter like this to get information: