Miravia Open Platform
3. Manage products in bulk - Feed API
The Feed API within the Open Platform allows for bulk product listing and updates. Sellers or developers can use this API to automate the process of uploading or modifying a large number of product listings in a more programmatic way, rather than using the manual interface.
0.Recommend Prerequisites:
- Control some of the most common validation errors that are occurring in this process.
- There are in total of 5 API endpoints included in the FeedAPI, please find below the recommended flowfrom Miravia to call our Feed API.
- Step 1 CreateFeedDocument : Initiate a task to create documents which can be access by Miravia, specifying the content type for the feed that you are submitting. returns a feedDocumentId value and a URL for uploading the feed contents. We only support "application/json" at the moment.
- HTTP Request Example
- Step 2 CreateFeed : Call the CreateFeed operation to specify the feed document identifier, the feed type.
- Step 3 GetFeed After you call the createFeed operation, Miravia receives the request and begins to process the feed. You must confirm that processing has completed before you continue.
- Feed document example (JSON format)
- Product_listing
- Post_product_pricing_quantity
- Update_product_Sellable_stock
FeedAPI API call flow
There are in total of 5 API endpoints included in the FeedAPI, please find below the recommended flowfrom Miravia to call our Feed API:
Recommend Prerequisite- Validation
In our feed API for product listing process, we have included a new step, to control some of the most common validation errors that are occurring in this process.
This step will be called the validation step. Please check the flow of the Product Listing execution to check how it is included:
Status meaning:
As mentioned in the diagrams, if the status is VALIDATION_FAILED for one product, in order to fix the problem and upload successfully to our platform, it will be required to fix the issue. In the next section we will see the possible problems and solutions for this state.
Examples of different status in the feed result document:
Status = SUCCESS
| { "test_feeds_1688987061799_1": { "feedId": 4311119, "gmtCreate": 1688987068000, "gmtModified": 1688987099000, "id": 743122248, "index": "test_david_feeds_1688987061799_1", "status": "SUCCESS" } } |
Status = FAIL
| "test_feeds_1688989764597_2": { "detail": "{\"traceId\":\"21038fb816889897745181021d0a66\",\"message\":\"{\\\"errorCode\\\":\\\"500\\\",\\\"errorDetail\\\":[{\\\"code\\\":\\\"THD_INVENTORY_ERR_INV_PARAM_ILLEGAL\\\",\\\"seller_sku\\\":\\\"\\\",\\\"field\\\":\\\"Product\\\",\\\"message\\\":\\\"THD_INVENTORY_ERR_INV_PARAM_ILLEGAL:illegal parameter:quantity\\\"}],\\\"errorMsg\\\":\\\"E500: Create product failed\\\",\\\"errors\\\":[{\\\"code\\\":\\\"THD_INVENTORY_ERR_INV_PARAM_ILLEGAL\\\",\\\"field\\\":\\\"Product\\\",\\\"sellerSku\\\":\\\"\\\",\\\"message\\\":\\\"THD_INVENTORY_ERR_INV_PARAM_ILLEGAL:illegal parameter:quantity\\\"}],\\\"success\\\":false}\"}", "feedId": 4311392, "gmtCreate": 1688989774000, "gmtModified": 1688989805000, "id": 743142121, "index": "test_feeds_1688989764597_2", "status": "FAIL" }, |
Status = VALIDATION_FAIL (old format)
| { "test_feeds_1689066564800_1": { "detail": "{\"traceId\":\"21038fb816890665678652449d0a66\",\"message\":\"{\\\"errorCode\\\":\\\"THE_FIELD_OF_BRAND_HAS_AN_ERROR_PLEASE_CHECK\\\",\\\"errorDetail\\\":[{\\\"code\\\":\\\"THE_FIELD_OF_BRAND_HAS_AN_ERROR_PLEASE_CHECK\\\",\\\"field\\\":\\\"brand\\\",\\\"message\\\":\\\"You do not have permissions to create product with this brand, please apply here : https://sellercenter.proyectoarise.es/apps/setting/brand/application?spm=a2a4n.27653341.page_title.d_apply_new.41dd4edfkrx8ol\\\"}],\\\"errorMsg\\\":\\\"This field 'brand' has an error value of 'No Brand David', please check the errorDetail field\\\",\\\"errors\\\":[{\\\"code\\\":\\\"THE_FIELD_OF_BRAND_HAS_AN_ERROR_PLEASE_CHECK\\\",\\\"field\\\":\\\"brand\\\",\\\"message\\\":\\\"You do not have permissions to create product with this brand, please apply here : https://sellercenter.proyectoarise.es/apps/setting/brand/application?spm=a2a4n.27653341.page_title.d_apply_new.41dd4edfkrx8ol\\\"}],\\\"success\\\":false}\"}", "feedId": 4324379, "gmtCreate": 1689066568000, "gmtModified": 1689066598000, "id": 745064197, "index": "test_feeds_1689066564800_1", "status": "VALIDATION_FAIL" } } |
In the near future, this status will contain the response format of the Validation endpoint API response, to align all responses.
Please check the errorDetail field, it will contain the API response for validation:
| { "error_value":"No Brand David", "error_key":"brand", "error_detail":"You do not have permissions to create product with this brand, please apply here : https://sellercenter.proyectoarise.es/apps/setting/brand/application?spm=a2a4n.27653341.page_title.d_apply_new.41dd4edfkrx8ol" } |
Complete example: Status = VALIDATION_FAIL (incoming format)
| "test_feeds_1688989416297_1": { "detail": "{\"traceId\":\"21038fb816889894212008983d0a66\",\"message\":\"{\\\"errorCode\\\":\\\"THE_FIELD_OF_BRAND_HAS_AN_ERROR_PLEASE_CHECK\\\",\\\"errorDetail\\\":[{\\\"error_value\\\":\\\"No Brand David\\\",\\\"error_key\\\":\\\"brand\\\",\\\"error_detail\\\":\\\"You do not have permissions to create product with this brand, please apply here : https://sellercenter.proyectoarise.es/apps/setting/brand/application?spm=a2a4n.27653341.page_title.d_apply_new.41dd4edfkrx8ol\\\"}],\\\"errorMsg\\\":\\\"This field 'brand' has an error value of 'No Brand David', please check.\\\",\\\"errors\\\":[{\\\"error_value\\\":\\\"No Brand David\\\",\\\"error_key\\\":\\\"brand\\\",\\\"error_detail\\\":\\\"You do not have permissions to create product with this brand, please apply here : https://sellercenter.proyectoarise.es/apps/setting/brand/application?spm=a2a4n.27653341.page_title.d_apply_new.41dd4edfkrx8ol\\\"}],\\\"success\\\":false}\"}", "feedId": 4311345, "gmtCreate": 1688989421000, "gmtModified": 1688989451000, "id": 743138714, "index": "test_david_feeds_1688989416297_1", "status": "VALIDATION_FAIL" } |
Step 1 CreateFeedDocument
Initiate a task to create documents which can be access by Miravia, specifying the content type for the feed that you are submitting. returns a feedDocumentId value and a URL for uploading the feed contents. We only support "application/json" at the moment.
Request example:
{ "content_type":"application/json" }
Response example:
{ "feed_result":{ "result":{ "feed_document_id":"e702ddea-e703-43e2-b30a-5f9c5944c044.4000002768003", "url":"https://airse-open-feed.oss-eu-central-1.aliyuncs.com/e702ddea-e703-43e2-b30a-5f9c5944c044.4000002768003.json?Expires=1658472289&OSSAccessKeyId=LTAI5tPS8gpPYr9xZ5WcvRLU&Signature=G10tIi2NDqh%2BIIkcBkEYJCHvwgo%3D" }, "success":true }, "code":"0", "request_id":"21038f5516584686892251082" }
Upload your feed document
Upload your feed document (which must be in JSON format) using the URL of the CreateFeedDocument API response.
Request Method: PUT
HTTP Request Example
<dependency> <groupId>org.apache.httpcomponents</groupId> <artifactId>httpclient</artifactId> <version>${your version}</version> </dependency> HttpPut httpPut = new HttpPut("/feed/createFeedDocument api response url"); BasicHttpEntity httpEntity = new BasicHttpEntity(); httpEntity.setContent("your file InputStream"); httpEntity.setContentLength("your file size"); httpEntity.setContentType("/feed/createFeedDocument api input parameter content_type"); httpPut.setEntity(httpEntity); CloseableHttpClient httpClient = HttpClients.createDefault(); CloseableHttpResponse response = httpClient.execute(httpPut, HttpClientContext.creat
- After successful transmission, it will respond with http code 200.
- The feed document format will be shown at the end of the article.
Step 2 CreateFeed
Call the CreateFeed operation to specify the feed document identifier, the feed type.
Request example:
{ "feed_type":"PRODUCT_LISTING", "feed_document_id":"9d350a9a-7861-46b5-b404-2e05f22765c2.1001" }
- "feed_document_id" cannot be reused
Response example:
{ "feed_result":{ "result":52, "success":true }, "code":"0", "request_id":"21038f5516584687399921083" }
Step 3 GetFeed
After you call the createFeed operation, Miravia receives the request and begins to process the feed. You must confirm that processing has completed before you continue.
*If you perform a GET request to the feed for information from 14 days ago or earlier, it will not be found, as it has exceeded the retention period
Feed Document processing completed response
{ "feed_result":{ "result":{ "processing_end_time":"2022-07-22 13:46:03", "created_time":"2022-07-22 07:45:40", "processing_status":"DONE", "result_feed_document_id":"ddead6cc-fb4b-487c-9ddb-e97557e847bc.4000002768003", "feed_type":"PRODUCT_LISTING", "processing_start_time":"2022-07-22 13:46:02", "feed_id":52 }, "success":true }, "code":"0", "request_id":"21038f5516584771545771123" }
Feed document is processing the response
{ "feed_result":{ "result":{ "created_time":"2022-07-22 07:19:26", "processing_status":"IN_PROGRESS", "feed_type":"PRODUCT_LISTING", "processing_start_time":"2022-07-22 13:20:02", "feed_id":51 }, "success":true }, "code":"0", "request_id":"21038f5516584771752521124" }
The following processingStatus values confirm that processing is complete:
- DONE - feed processing is complete.
- CANCELLED - the feed was cancelled before it began to process. If you want to resubmit the feed, go to CreateFeedDocument
- FATAL - the feed was abandoned due to a fatal error. Some, none, or all of the operations within the feed might have completed successfully.
Get the result from the response URL
Request Method: GET
Content-Type: application/json
Response Example
Processing success
{ "Product":{ "feedId":54, "gmtCreate":1658456282000, "gmtModified":1658456282000, "id":25, "index":"Product", "status":"SUCCESS" } }
Processing Failure
{ "Product":{ "detail":"{\"traceId\":\"210380cf16584781216872846dac87\",\"message\":\"{\\\"errorCode\\\":\\\"500\\\",\\\"errorDetail\\\":[{\\\"code\\\":\\\"THD_IC_ERR_F_IC_INFRA_PRODUCT_036\\\",\\\"seller_sku\\\":\\\"\\\",\\\"field\\\":\\\"Product\\\",\\\"message\\\":\\\"THD_IC_ERR_F_IC_INFRA_PRODUCT_036:Insert sku outer id relation failed, outerId already exists, sell ID:4,000,002,768,003,sku ID:2,068,481,467,064,734,outer ID:test-product-creatation-for-api-chasetest11123,serverIP:33.27.90.239\\\"}],\\\"errorMsg\\\":\\\"E500: Create product failed\\\",\\\"errors\\\":[{\\\"code\\\":\\\"THD_IC_ERR_F_IC_INFRA_PRODUCT_036\\\",\\\"field\\\":\\\"Product\\\",\\\"sellerSku\\\":\\\"\\\",\\\"message\\\":\\\"THD_IC_ERR_F_IC_INFRA_PRODUCT_036:Insert sku outer id relation failed, outerId already exists, sell ID:4,000,002,768,003,sku ID:2,068,481,467,064,734,outer ID:test-product-creatation-for-api-chasetest11123,serverIP:33.27.90.239\\\"}],\\\"success\\\":false}\"}", "feedId":55, "gmtCreate":1658456522000, "gmtModified":1658456522000, "id":26, "index":"Product", "status":"FAIL" } }
Feed document example (JSON format)
PRODUCT_LISTING
Optional attributes can be added or removed, the rules are the same as the createproduct api
"Product A":{
"Skus":{
"Sku":[
{
"ean_code":"9354593066792",
"package_width":"1.0",
"quantity":3,
"package_height":"1.0",
"special_price":"24.93",
"price":"27.42",
"package_length":"1.0",
"Images":{
"Image":[
"https://fb-es.mrvcdn.com/kf/E02f8c174fe6b46dc9459e9c05834846aO.jpg"
]
},
"sku_attributes":{
},
"SellerSku":"test_feeds_21072023_2_1",
"package_weight":"1.0",
"package_content":"1"
}
]
},
"PrimaryCategory":62202804,
"predictedCategory":true,
"Images":{
"Image":[
]
},
"Attributes":{
"short_description":"Útilparafavorecerlafisiológicarelajación.",
"name":"ForzaVitaleQuietis(MelissaComposta)100Ml_CHANGE NAME FROM FEED",
"description":"CHANGE DESCRIPTION",
"delivery_option_sof":"Yes",
"brand":"ForzaVitale"
}
},
"Product C":{
"Skus":{
"Sku":[
{
"ean_code":"8447101048098",
"package_width":"1.0",
"quantity":3,
"package_height":"1.0",
"special_price":"24.93",
"price":"27.42",
"package_length":"1.0",
"Images":{
"Image":[
"https://fb-es.mrvcdn.com/kf/E02f8c174fe6b46dc9459e9c05834846aO.jpg"
]
},
"sku_attributes":{
},
"SellerSku":"test_nacho_feeds_21072023_2_2",
"package_weight":"1.0",
"package_content":"1"
}
]
},
"PrimaryCategory":62202804,
"Images":{
"Image":[
]
},
"Attributes":{
"short_description":"Útilparafavorecerlafisiológicarelajación.",
"name":"ForzaVitaleQuietis(MelissaComposta)100Ml",
"description":"example of description for the product listing method Feed API",
"delivery_option_sof":"Yes",
"brand":"ForzaVitale"
}
}
}
POST_PRODUCT_PRICING_QUATITY_DATA
{ "updateTask1":{ "Sku":{ "ItemId":"1355777715065245", "SkuId":"2068481483383197", "SellerSku":"test-product-creatation-for-api-chasetest11123", "Price":"1000", "SalePrice":"995", "Quantity":"1000" } }, "updateTask2":{ } }
UPDATE_PRODUCT_SELLABLE_STOCK
{ "test_nacho_feeds_22032023_2_1":{ "Sku":{ "ItemId":"1356100789103878", "SellerSku":"test_nacho_feeds_22032023_2_1", "MultiWarehouseInventories":{ "MultiWarehouseInventory":[ { "WarehouseCode":"dropshipping", "SellableQuantity":40 } ] } } }, "test_nacho_feeds_22032023_2_2":{ "Sku":{ "ItemId":"1356100789103878", "SellerSku":"test_nacho_feeds_22032023_2_1", "MultiWarehouseInventories":{ "MultiWarehouseInventory":[ { "WarehouseCode":"dropshipping", "SellableQuantity":40 } ] } } } }
