MiraKl_API_Guide
MiraKl_API_Guide
Agenda
1. Introduction
The purpose of this guide is to present the APIs integration method for sellers. We will go through the main interactions between sellers
systems and the Marketplace. In addition to this document you will have access to a technical documentation to build the APIs integration
with your IT system. This integration method requires some technical resources.
WHAT IS AN API?
An API (Application Programming Interface) is an interface provided by a computing program. It allows independent programs to interact
with each other. In other words it enables sellers to seamlessly manage their Marketplace activity with their overall ecommerce activity.
Thanks to Mirakl Seller APIs, sellers can automate their catalog, their orders and customer care management. It will increase their sales
efficiency with no additional charge on the teams. It can also improve their overall quality of service by decreasing customer response
time.
APIs are made to ease Marketplace daily operations. Depending on your level of autonomy you can automate part or all of your activity on
the marketplace. For example, you can automate offers and orders but upload products manually with an excel file.
Mirakl Seller APIs allow you to automate 4 main parts of your activity on the marketplace:
- Shop information
- Catalogue: products & offers
- Orders management & shipping information
- Accounting management
You are free to integrate part or all the APIs related to these 4 topics.
ORDERS
ACCOUNTING
MANAGEMENT
Mirakl provides different automation methods, you can use either one depending your IT system:
→ If you are using Magento 1, Mirakl has developed a connector that will enable you to automate your products and offers very rapidly. This integration
does not require any technical skills. Note that the order management is not available yet in the connector. If you want to automate your orders
management, you can combine this method with one of the following methods.
→ If your e-commerce solution is coded in PHP or Java, the operator will give you access to the Mirakl SDK. The SDK is a set of programming support
tools that will help you integrate flows and Mirakl APIs more easily and rapidly, whilst decreasing your margin of error in your regular flows sent out.
To access Mirakl SDK, make the request to your operator. The operator will then give you a link to your Artifactory account where the SDK is
hosted.
→ If your e-commerce solution is not Magento or is not coded in PHP or Java, you will have to make all the developments to integrate the APIs yourself.
! The last two methods require development skills. If you don’t have an IT department or if you don’t want to use an external resource, you can
opt for another integration method: manual, through file or FTP. Ask your operator for advice.
Requests the API Reads the Creates and Tests and develops Tests and develops the
integration documentation, configures POSTMAN APIs in the operator’s APIs in the prod
method chooses the APIs to to test the APIs to test environment environment
Seller
The API key is unique for each seller. It gives you 1. Log into your back office
access to all the Mirakl Seller APIs. Do not
communicate it to anyone. 2. Click on your username, in the top right, to access your user settings
3. In the tab “API key”, select “Generate” to create your own API key.
- An API Key is specific to an environment. You will have to generate an API key for the test environment and then, one for the
prod environment.
1
6
Product characteristics
4
Every core features and characteristics of the product, they do not
change from one seller to another:
1. Product name 7
2. Image(s) 2
3. Description
4. Product_ID / EAN / UPCs / ISBN…
5. Size / Color / Dimensions
8
Offer characeristics
All the info that are specific to each:
6. State of the product (new, second-hand, refurbished…)
7. Price
8. Available quantity
3 5
OPERATOR
SELLER CATALOG
CATALOG
P46 Get transformed product file
*See the integration errors and Get product integration error report
P45
solutions in slides 39-40 PX Optional API
X
! You must initialize the automation of your catalog by doing the mapping of your product format to the operator one. This action is required once and for
all, unless you have new categories within your catalog. Once the mapping is done, you can import all your products directly by API.
Click on: Shop > Mapping Configuration > Use the configuration Wizard
Best practice: the file uploaded must be saved in Excel format or CSV format encoded in UTF8
©2018 Mirakl, Inc.
Prerequisites to the products import automation: the mapping process
Creating a category tree will allow you to add product descriptions by breaking them down into segments. You must place all your product categories in one column,
which also includes the subcategory separator.
The list of values 'Brand' is predefined and it is possible that one of your brands is not registered.
In that case, please email to marketplace@OPERATOR.
Specify in the subject line «New brands to create » and in the email body, a list of your missing trademarks ©2018 Mirakl, Inc.
Prerequisites to the products import automation: the mapping process
OF
Get the offer integration status
02
OF
Get the offer integration error report*
03
SELLER OF OPERATOR
List all the offers of one shop
CATALOGUE 21 CATALOGUE
OF
Get information about one offer
22
OF
Update offers (Json / XML) OF
24
xx
Main API
! The format of the offer file is defined by the operator. See the fields and their status on the next slide. You can ©2018 Mirakl, Inc.
download the offer file from your backoffice: My inventory > Download an Excel file template for offers.
Offer file upload: Mandatory fields
There is no mapping on the offer file, you must ensure that you fill the fields as shown below:
product-id Unique product identifier for a given product-id-type Required Character string limited to 40 characters 98987DC
Value:
product-id-type Type of product-id identifier Required SKU
SKU (product SKU) ,ISBN, UPC, EAN, SHOP_SKU,…
price Original Recommended Retail Price (RRP) in GBP including taxes (VAT). Required Decimal number; a period is used to separate cents 45.50
The state code of the offer. This refers to whether the product is New or See available values in the
state Required The accepted values are defined in the back office view
Vintage. BO
quantity The quantity available in stock Required Integer greater than or equal to 0 100
product-tax-code The tax code associated to your products Required Text from the Avalara tax code list PF050900
There is no mapping on the offer file, you must ensure that you fill the fields as shown below:
internal-description The description of the offer as shown in the back office view Optional The offer’s internal description is limited to 2000 characters
This will overwrite the default logistics class defined for the product category Technical code of the logistic class.
logistic-class Optional Ex: SP (small package)
assigned to the offer. BO > Informaiton > Shipping charges > value in ()
Define offer as favorite and set its rank value. This affects its positioning in
favorite-rank Optional Integer other than 0 1
shop window The offer will not be part of the favorite if blank
The first day the offer becomes available The discount starts immediately if
discount-start-date Optional yyyy-mm-dd 2012-11-27
the discount price is filled and the start date is blank.
discount-end-date The last day the offer is available. The discount has no end date if blank Optional yyyy-mm-dd 2012-12-27
The discount quantity thresholds and prices to define discounts with ranges 2|9.00,10|8.50
discount-ranges Optional quantityThreshold1|price1,quantityThreshold2|price2
4. Update tracking
information (OR23)
5. Confirm order
shipment (OR24)
6. Upload invoice
7. Manage customer
(OR74)
care (OR42)
OR
Get the evaluation of an order
51
OR
OR xx
Main API
Upload documents to associate to an order
74
OR
OR Download one or multiple documents Optional API
00
73 associated to one or multiple orders
! If you do not want to automate your order management, you will still be able to track and process your orders from ©2018 Mirakl, Inc.
your Mirakl seller backoffice.
Automate your after-sales
service
APIs related to After-Sales management
M0
List all the messages sent to a seller
1
Of
List all messages of an offer
41
OF
Answer to a message of an offer OPERATOR
SELLER SYSTEM 43
PLATFORM
OF
List messages of an order
41
! - Messaging APIs enable the seller to communicate with a client or to answer a question about an order or his offers
on the marketplace. Messages can be sent to the operator, the customer or both.
- If you do not want to automate your order management, you will still be able to track and process your orders from
your Mirakl seller backoffice ©2018 Mirakl, Inc.
Automate your accounting
APIs related to Accounting
IV
List accounting documents
01
IV
OPERATOR
SELLER SYSTEM Download an accounting document
02 PLATFORM
! You can retrieve all your invoices, credit notes and transaction history in your Mirakl seller backoffice.
After reading the API documentation and defining your integration strategy, you can test all these APIs with Postman.
It will help you define which APIs you want to implement to automate your activity on the marketplace.
Requests the API Reads the Creates and Tests and develops Tests and develops the
integration documentation, configures POSTMAN APIs in the operator’s APIs in the prod
method chooses the APIs to to test the APIs to test environment environment
Seller
About Postman
Postman is a third-party software that has not been developed by Mirakl. It allows testing API calls easily and efficiently.
Thanks to Mirakl API collection that can be imported in Posmtan, you will be able to test your API integration. Ask your operator the
full API collection (under the format Json).
You must use Postman with the test environment of the operator.
1. In Postman, click on and select Manage Environments. A window appears.
2. Click on Add and enter a name.
3. Click on the field ”key” and enter:
1. the FRONT_KEY (ask for it to the operator)
2. the OPERATOR_KEY (ask for it to the operator)
3. the SHOP_KEY (that you will find in your backoffice: My user settings > API Key)
4. the URL (the URL of the operator test environment (e.g. https://dev-new.mirakl.net)
4. For each API key, enter the value in the “value” field.
5. Click on Add and close the window "Manage Environments".
6. Click on the drop-down list No Environments and select the environment that you just set up.
You can test your integration with Postman, with the help of the operator, in his test environment.
Here are some basic actions related to your activity on a marketplace that you can automate:
1. Before importing your catalog, check the operator category tree, thanks to the API H11, the mandatory and optional attributes related to the categories
with PM11, and the value lists associated with VL11.
2. Adapt your product format consequently, then proceed to the mapping with the operator product format, in our backoffice: My inventory > Import
Importer products in your format > Open the Configuration Wizard. (see slides 15 to 23 of this guide)
3. Import our catalogue thanks P41. Download the information related to the import as well as the error report with P42 and P44. See slides 39 and 40 to
correct the errors in your file.
4. Import your offers with OF01: to do so, download the operator offer format in the backoffice: My inventory > Import Importer products in your format
> Download an Excel file template for offers. Download the information related to the import as well as the error report with OF02 and OF03. See slides
40 to 43 to correct the errors in your file.
5. Once your catalogue has been correctly imported, ask the operator to create a test order in your shop.
6. Get the order with OR11, accept it with OR21 and confirm shipping with OR24. You can download then upload the documents related to one or more
orders thanks to OR73 and OR74.
7. Ask the operator to send a test message on the order.
8. Get the message with M01 and answer to it with OR42.
9. Ask the operator to create a test incident on this order.
10. Proceed to the full or partial reimbursement of this same order, thanks to OR28.
! All the Shop APIs are not described in this example. See the technical documentation to see all the available APIs.
Reminder: You can automate part or all you activity on the marketplace. You can choose the APIs you want to
©2018 Mirakl, Inc.
integrate.
Error reports on products and
offers imports
Error report on products (1/2)
The column which must contain the Catalog category is not specified in the file or not detected.
1004 "Category could not be identified"
Solution: Check if the attribute name is properly written in the header of the file (without space character).
"Hierarchy has to be mapped to a leaf Sellers can only create product on the leaf operator Catalog category.
1005
operator hierarchy" Solution: Sellers must change their mapping configuration to map their catalog categories to your leaf catalog categories.
This catalog category informed by the seller does not exist or is not properly written.
Solution:
1001 "Category is unknown"
- if the category exists, your seller should check whether it is properly written (without space character)
- or if the category does not exist, the seller must create its category and map it to your category (from the back office)
©2018 Mirakl, Inc.
Error report on products (2/2)
"The attribute {a} must be a numeric with at most {x} There are more decimals than allowed.
2016/3016
decimals Solution: In the imported product file, enter a value with no more than {x} decimals.
©2018 Mirakl, Inc.
Error report on offers (1/2)
The product linked to the new offer You are trying to change the product linked to an existing offer.
is different from the product linked Solution: You must delete the existing offer, wait for the offer-product assignment delay to be over, and recreate the offer on the new
to the existing offer. product.
You are trying to create an offer using the ID of a deleted offer. The new offer is linked to a different product than the product the deleted
The product linked to the new offer
offer was linked to.
is different from the product linked
There is a waiting period defined by the operator before you can create the new offer.
to an old offer which has the same
Solution: You can create the new offer with another ID to avoid waiting.
shop id.
For more information, refer to: Offer Stock Keeping Unit.
In your file, you must indicate the "product-id" and "product-id-type" to match your offers with the product.
If you got this error message, it is because no product with this identifier exists in Mirakl.
Solution:
The product does not exist
- check with the operator to make sure the type of the identifier is correct (it can be EAN, ISBN, SKU, SHOP_SKU...) or if the product
has been correctly created by the operator
- you can use API P31 to check if the product exists with the couple "product-id|product-id-type"
This import type does not allow the You cannot use the "update-delete" column with the current import mode.
use of the 'update-delete' column Solution: Use the "NORMAL" import mode to use the "update-delete" column in your file.
©2018 Mirakl, Inc.
Error report on offers (2/2)
The "price" field is not found in the file. This information is mandatory to create an offer.
The 'price' field is mandatory
Solution: If you have added this field, check if it is properly written.
The operator has temporarily or definitively decided not to sell this product.
This product is not available for sale
Solution: Contact your operator.
The price of your offer is lower or greater than the limit price set by the operator.
The 'price' field has an invalid range
Solution: Contact your operator. Ask for the limit and adjust the price of your offer.
The discount price of your offer is lower or greater than the limit price set by the operator.
The 'discount_price' field has an invalid range
Solution: Contact your operator. Ask for the limit and adjust the discount price of your offer.
The mandatory additional field set by the operator is missing in your file.
The mandatory additional field is missing
Solution: Call API AF01 to get the list of available additional fields.
The 'product-id' field is mandatory when 'product-id-type' is The "product-id" and "product-id-type" fields are linked together and cannot be separated.
filled The "product-id-type" is used to know the type of the product reference you filled in the "product-id" field.Mirakl, Inc.
©2018
Thank you