.. _fmsapi-label:
================================
Flipkart Marketplace Seller APIs
================================
The Flipkart Marketplace Seller APIs allow a seller's applications to programmatically access and exchange data with the Flipkart Marketplace. They help automate business processes associated with selling on the Marketplace. A seller can use these APIs to search orders, print shipping labels and invoices, and manage orders at different stages of the order life cycle.
.. sidebar:: Developer Support
For any queries or clarifications on environments, authentication, and APIs, raise a ticket through the seller or partner portal under API GA node.
.. _seller-reg-label:
Seller Registration
===================
To start working with seller APIs, first register as a seller with the Marketplace at https://seller.flipkart.com.
|
|
|
|
.. note:: The username and password provided during the registration process on seller dashboard does not provide API access
API Application Setup
=====================
.. sidebar:: Developer Admin portal
* `Sandbox <https://sandbox-api.flipkart.net/oauth-register/login>`_
As a registered seller you can log into the **Seller Dashboard > Manage Profile > Developer Access** to create self access applications and to manage 3rd party API application access.
|
.. important::
* Testing the application integration in the sandbox setup is prerequisite to implementing it in a live (production) setup. Both setups use the OAuth framework.
* All seller APIs must be HTTPS requests. HTTP requests are not supported.
* Do not hard-code the Access Token value in the Authorization header as the token expires after some time - usually, 60days. If an expired Access Token is used, API requests would fail with ``401`` HTTP status code. You must regenerate the access token in such a scenario and use the new one in subsequent requests. Refer :ref:`gen-access-token-label` for details.
Sandbox Environment
-------------------
.. sidebar:: API Test Environment
* To access and test the self-serve APIs in sandbox, `click here <https://sandbox-api.flipkart.net/swagger/#/Self%20Serve>`_.
* To access and test the Order Management pull APIs in sandbox, `click here <https://sandbox-api.flipkart.net/swagger/>`_.
The sandbox is a staging setup where you can design, program, and test applications in a controlled environment before implementing them in the production environment. Products listed in this environment are not real; however, changing the base URL to that of the production environment enables the applications to go live with real products and users.
.. _prodenv-label:
Production Environment
----------------------
The production environment is the live Flipkart platform. Products listed in this environment are available to real Flipkart users. The information provided for this environment is governed by the Flipkart Marketplace terms of usage (TOU).
.. _authproc-label:
Application Registration
------------------------
**Self Access Application - For Sellers own use**
**Steps to set-up Self Access Application**:
- Log into the Seller Dashboard portal.
- Go to Manage Profile > Developer Access
- Click Create New Access
- Provide following details
- **Application Name** - Any text identifier name for your application
- **Application Description** - Text to describe the use of Seller APIs
- Click **Submit**. The new application is now added to your applications list and a unique **Application ID** (``<appid>``) and **Application Secret** (``<app-secret>``) pair is assigned.
- Kindly refer to :ref:`client-cred-label` Flow to understand access token generations
**Sandbox**: Raise a ticket through the seller or partner portal under API GA node to get your credentials to log into `Sandbox environment <https://sandbox-api.flipkart.net/oauth-register/login>`_
**Important note**: Do not share the self access application details with any 3rd party partner(s) / aggregator. It is meant strictly for self seller use. Violations will lead to seller account deactivation.
**Third Party Access Application - For Partners / Aggregator**
**Steps to set-up Third Party Access Application**:
- Register yourself on `Partner Dashboard <https://partners.flipkart.com/landing/home-page?redirect_url=/>`_ portal.
- While registering, select `Yes` to the question on whether you’re an API Partner
- Once registered, Flipkart team will reach out to verify your details within 72 hours.
- Once your profile is verified, you will be allowed to create a Third party Client
- To create a Third Party Application Go to Profile > Manage API Access
- Click on **Create Application**
- Provide following details:
- **Application Name**: The name of your third-party application.
- **Application Description**: Relevant description for your application.
- **Redirect URL**: The URL to which Flipkart will redirect the browser after authorization has been granted by the seller. Please note that the redirection link has to be strictly a valid https link.
- Click **Create Application**. The new application is now added to your applications list and a unique **Application ID** (``<appid>``) and **Application Secret** (``<app-secret>``) pair is assigned.
- Kindly refer to :ref:`auth-code-grant-label` to understand seller onboarding on the application created
**Sandbox**: Raise a ticket through the seller or partner portal under API GA node to get your credentials to log into `Sandbox environment <https://sandbox-api.flipkart.net/oauth-register/login>`_
**Please note**: Partner / Aggregator are strictly to use Third party Application. Any volition will lead to permanent ban on Flipkart.
.. note::
Application ID (``appid``) mentioned above and ``client_id`` used in the below mentioned OAuth APIs refers to the same thing.
.. _gen-access-token-label:
Generating Access Tokens
-------------------------
.. sidebar:: Reading Reference
* `About OAuth <http://oauth.net/2/>`_
* `Authorization Grants <https://tools.ietf.org/html/rfc6749#page-8>`_
* `Client Credentials Flow <https://www.oauth.com/oauth2-servers/access-tokens/client-credentials/>`_
* `Authorization Code Flow <https://www.oauth.com/oauth2-servers/server-side-apps/authorization-code/>`_
Once your application is registered, you need to generate an access token to be able to call the APIs. Flipkart API Authorization framework supports two grant types to generate access tokens namely, the **Client Credentials** (for Self access application) and **Authorization Code** (for third party application) flows.
**Notes** ::
Only an authorized user once approved by Flipkart has access to use tokens. Below are the following grant_type:
* authorization_code,
* client_credentials,
* implicit,
* password,
* refresh_token
.. _client-cred-label:
Client Credentials Flow(for Self Access Application)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This flow should be used if you are a registered seller on Flipkart Marketplace and want to integrate with the APIs for your **own** orders and listings management.
.. container:: toggle
.. container:: header
**☰ SHOW | HIDE**
To generate access tokens using the client_credentials flow, below API should be used. You can write code in language of your choice to make a REST call or use ``curl`` to get the access tokens. ::
GET /oauth-service/oauth/token?grant_type=client_credentials&scope=Seller_Api,Default
This API is authenticated using `Basic Access Authentication <https://en.wikipedia.org/wiki/Basic_access_authentication>`_ mechanism and so the required ``Authorization`` header is expected.
``credentials`` to be used in header is base64 encoding of your ``appId`` and ``appSecret`` separated by a colon (``:``).
**e.g.** if your registered application appId is ``my-appId-1`` and appSecret is ``my-app-secret-1``, the credential to be used for Basic authentication would be the base64 encoding of ``my-appId-1:my-app-secret-1``
**Examples**
- **Postman**
.. image:: https://img1a.flixcart.com/fk-sp-static/images/postman-oauth-1.png
:align: center
Using Postman is one of the easiest way to generate an access token and manually test and get a hang of the APIs. This screenshot of Postman can be referred to for building the request.
As can be seen here, the ``appId`` and ``appSecret`` can directly be used as the ``Username`` and ``Password`` after selecting ``Basic Auth`` as the Authorization Type. Postman will take care of doing the base64 encoding and setting appropriate headers.
- **Java**
If you are using Java, you can use the access token generation code which is bundled with the API client provided by us.
Refer to :ref:`integration-label` section below for more details.
Alternatively, here is a sample Java code which you can embed in your application to generate access tokens.
.. code-block:: java
import java.util.Base64;
import kong.unirest.Unirest;
import kong.unirest.json.JSONException;
import kong.unirest.json.JSONObject;
public final class MyFkApp {
private static final String CLIENT_ID = "__CLIENT_ID__"; // Replace with your application id or client id
private static final String CLIENT_SECRET = "__CLIENT_SECRET__"; // Replace with your application secret or client secret
private MyFkApp() {
}
public static void main(String[] args) {
String base64EncodedString = Base64.getEncoder().encodeToString((CLIENT_ID + ":" + CLIENT_SECRET).getBytes());
JSONObject respoJsonObject = Unirest.get("https://sandbox-api.flipkart.net/oauth-service/oauth/token?grant_type=client_credentials&scope=Seller_Api")
.header("Authorization", "Basic " + base64EncodedString)
.asJson()
.getBody()
.getObject();
String accessToken = "";
String error = "";
try {
accessToken = respoJsonObject.getString("access_token");
System.out.println("Access Token : " + accessToken);
} catch (JSONException jse) {
error = respoJsonObject.getString("error_description");
System.out.println("Error occurred ! Error description : " + error);
}
}
}
.. note:: You need to add a dependency on ``unirest-java`` for the above code to run. Kindly refer to unirest-java `documentation <https://github.com/Kong/unirest-java>`_ for more info.
- **Python**
.. code-block:: Python
import requests
import base64
url = "https://sandbox-api.flipkart.net/oauth-service/oauth/token"
querystring = {"grant_type": "client_credentials", "scope": "Seller_Api"}
client_id = "__CLIENT_ID__" # Replace with your application id or client id
client_secret = "__CLIENT_SECRET__" # Replace with your application secret or client secret
headers = {
'Authorization': "Basic " + base64.b64encode(client_id + ":" + client_secret)
}
response_json = requests.request("GET", url, headers=headers, params=querystring).json()
access_token = response_json["access_token"]
print("Your access token is : " + access_token)
- **C#**
.. code-block:: csharp
using System;
using Newtonsoft.Json;
using Newtonsoft.Json.Serialization;
using RestSharp;
namespace fk_api_client_dotnet
{
class Program
{
static string clientId = "__CLIENT_ID__"; // Replace with your application id or client id
static string clientSecret = "__CLIENT_SECRET__"; // Replace with your application secret or client secret
static string credentials = Base64Encode(clientId + ":" + clientSecret);
static void Main(string[] args)
{
var client = new RestClient("https://sandbox-api.flipkart.net/oauth-service/oauth/token?grant_type=client_credentials&scope=Seller_Api");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Basic " + credentials);
IRestResponse response = client.Execute(request);
var _snakeSettings = new JsonSerializerSettings()
{
ContractResolver = new UnderscorePropertyNamesContractResolver()
};
var accessTokenResponse = JsonConvert.DeserializeObject<AccessTokenResponse>(response.Content, _snakeSettings);
Console.WriteLine("Your access token is : " + accessTokenResponse.accessToken);
}
public class UnderscorePropertyNamesContractResolver : DefaultContractResolver
{
public UnderscorePropertyNamesContractResolver()
{
NamingStrategy = new SnakeCaseNamingStrategy();
}
}
private static string Base64Encode(string plainText) {
var plainTextBytes = System.Text.Encoding.UTF8.GetBytes(plainText);
return System.Convert.ToBase64String(plainTextBytes);
}
public class AccessTokenResponse
{
public string accessToken { get; set;}
}
}
}
.. note:: You need to add a dependency on ``RestSharp`` package for the above code to run. Kindly refer to RestSharp `documentation <http://restsharp.org/>`_ for more info.
- **curl**
.. code-block:: bash
curl -u <appid>:<app-secret> https://api.flipkart.net/oauth-service/oauth/token?grant_type=client_credentials&scope=Seller_Api
**Sample response** ::
{
"access_token": "<token>",
"token_type": "bearer",
"expires_in": 3330779,
"scope": "Seller_Api"
}
|
|
.. _auth-code-grant-label:
Authorization Code Flow (For Third Party Application)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This flow should be used if you are a an **partner/aggregator** or a **vendor** and is going to manage API on behalf of other sellers registered on Flipkart Marketplace.
.. note:: If you are a registered seller on Flipkart Marketplace and want to integrate with APIs for your **own** orders and listings management, kindly refer to :ref:`client-cred-label`
.. container:: toggle
.. container:: header
**☰ SHOW | HIDE**
a. **Get the Seller's Authorization**
To begin an Authorization Code flow, your web application should first send the seller to the authorization URL.
**Authorization URL** ::
https://sandbox-api.flipkart.net/oauth-service/oauth/authorize?
client_id=<client-id>&
redirect_uri=<redirect-uri>&
response_type=code&
scope=Seller_Api&
state=<state>
Where,
- ``client-id``: Your application's Client ID. You can find this value in **Seller APIs - Developer Admin** portal
- ``redirect-uri``: The URL to which Flipkart will redirect the browser after authorization has been granted by the seller. The Authorization Code will be available in the ``code`` URL parameter. This URL must be specified as a valid callback URL while creating application in **Seller APIs - Developer Admin** portal.
- ``state``: An opaque value (random text field) which your application should add to the initial request and that Flipkart also includes when redirecting back to the application. This value must be used by the application to prevent CSRF attacks. For more information, see `authorization request <https://www.oauth.com/oauth2-servers/authorization/the-authorization-request/>`_ .
Seller must login to the **Flipkart Permission Registration** page that appears using his/her login credentials.
**Flipkart Permission Registration page**
.. image:: https://img1a.flixcart.com/fk-sp-static/images/signin-page.png
After successful login, seller would be presented with a **Request for Authorization** dialog. Upon clicking the ``Allow`` button, seller would be redirected to the ``redirect_uri``, with authorization ``code`` and ``state`` as URL parameters.
**Request for Authorization page**
.. image:: https://img1a.flixcart.com/fk-sp-static/images/auth-request-page.png
b. **Exchange the Authorization Code for an Access Token**
Now that you have an Authorization Code, you must exchange it for an Access Token that can be used to call the Flipkart Orders and Listing APIs. Using the Authorization Code (code) from the previous step, you will need to send it to the Token URL.
**Token URL** ::
https://sandbox-api.flipkart.net/oauth-service/oauth/token?
redirect_uri=<redirect-uri>&
grant_type=authorization_code&
state=<state>&
code=<code>
**Sample Code**
For sample code in Java, Python and C#, kindly refer to the *Examples* in :ref:`client-cred-label` . You just need to replace the URL in the code with the **Token URL**.
**curl** ::
curl -u <appid>:<app-secret> https://sandbox-api.flipkart.net/oauth-service/oauth/token?redirect_uri=<redirect-uri>&grant_type=authorization_code&state=<state>&code=<code>
**Sample response** ::
{
"access_token": "f638949aÂc979Â4172Âb33cÂ23311a168647",
"token_type": "bearer",
"refresh_token": "860e03daÂd58aÂ4988Â9149-a4a7f365bba1",
"expires_in": 5183999,
"scope": "Seller_Api"
}
|
.. _gen-refresh-token-label:
Generating Access Tokens using Refresh Token
--------------------------------------------
- Sellers are also able to generate an access token by refresh token. Validity for access token is 60 days and for refresh token it is 180 days.
- The `grant_type` should be `refresh_token` and only Flipkart approved sellers can use the access token.
- When the validity of the refresh token expires, the sellers have to request to generate the access token again. After that, sellers get a new access token and a refresh token.
.. container:: toggle
.. container:: header
**☰ SHOW | HIDE**
a. Call the authentication API. You can write code in any language to make a REST call or use ``curl`` to get the access tokens. ::
oauth/token?grant_type=refresh_token&refresh_token=<refresh_token>
b. Set your **Application ID** and **Application Secret** in the header for Basic Authentication.
**Sample header for production** ::
curl -u <appid>:<app-secret> https://api.flipkart.net/oauth-service/oauth/token?grant_type=refresh_token&refresh_token=<refresh_token>
**Sample response** ::
{"access_token":"<token>","token_type":"bearer","refresh_token":"<refresh_token>","expires_in":3330779,"scope":Seller_Api"}
|
.. _integration-label:
API Integration
===============
Once the Access Token has been obtained it can be used to make calls to the API by passing it as a Bearer Token in the ``Authorization`` header of the HTTP request.
To integrate with the Flipkart Marketplace Seller APIs provided in this documentation, you could go through this API documentation and create your own application.
However, the recommended way to integrate is to use auto-generated client code by using the `Swagger spec <https://sandbox-api.flipkart.net/swagger/swagger.json>`_.
To ease the process, we are providing a sample java application which you can `refer <https://github.com/Flipkart/flipkart-seller-api-java-sdk>`_ and start integration using the api client included in it.
If you are using any other language, you can use ``swagger-codegen`` to auto generate the client code for that language.
Steps to install ``swagger-codegen`` can be followed from the `official documentation page <https://swagger.io/docs/open-source-tools/swagger-codegen/>`_.
.. _codegen-label:
Code Generation
---------------
- Python ::
swagger-codegen generate -i https://sandbox-api.flipkart.net/swagger/swagger.json -l python -o flipkart-seller-api-client-python
- C# ::
swagger-codegen generate -i https://sandbox-api.flipkart.net/swagger/swagger.json -l csharp -o flipkart-seller-api-client-csharp
.. _sample_call-label:
Sample API Call
----------------------
This is a sample code in Java which can be used to fetch the details of a shipment. This code is also provided in the above linked sample Java application.
.. code-block:: java
package com.flipkart.api.seller;
import com.flipkart.api.seller.v3client.api.ShipmentV3Api;
import com.flipkart.api.seller.v3client.model.ShipmentResponse;
public class MyFlipkartOrdersApplication {
public static void main(String[] args) {
String accessToken = AccessTokenGenerator.getClientCredentialsAccessToken(); // You need to write custom code for token generation if you are using your own auto-generated client code.
ApiClient apiClient = new ApiClient();
apiClient.setAccessToken(accessToken);
ShipmentV3Api shipmentV3Api = new ShipmentV3Api(apiClient);
String shipmentId = "__SHIPMENT_ID__";
try {
ShipmentResponse shipmentResponse = shipmentV3Api
.getShipmentDetailsByInternalId(shipmentId, null, null);
System.out.println("Order Id for shipment is " + shipmentResponse.getShipments().get(0).getOrderItems().get(0).getOrderId());
} catch (ApiException e) {
e.printStackTrace();
}
}
}
If you are creating your own custom application, you can refer to below ``curl`` command.
The following sample calls the Filter Shipments API in the sandbox environment on providing a valid ``<token>`` value. You can change the URL to ``https://api.flipkart.net/sellers/orders/search`` to call the API in production. ::
curl -H"Authorization:Bearer <token>"-H"Content-Type: application/json" -d '{"filter" :{}}' https://sandbox-api.flipkart.net/sellers/v3/shipments/filter